Skip to main content
This section covers the formal definitions that govern communication between Palyra components. Palyra uses a combination of Protocol Buffers (Protobuf) for gRPC-based service interactions and JSON Schemas for message envelopes and configuration exchange. To ensure type safety across the monorepo’s diverse technology stack (Rust, TypeScript, Kotlin, Swift), the system employs automated stub generation and validation scripts.

​
Protocol Architecture Overview

The communication backbone is defined in schemas/proto, organized by versioned packages. These schemas serve as the single source of truth for the Daemon, CLI, and mobile/desktop clients.

​
Component Interaction Diagram

The following diagram illustrates how the generated contracts bridge different language spaces within the Palyra ecosystem. “Contract Distribution and Stub Generation” Sources: scripts/protocol/generate-stubs.ps1#82-91, schemas/proto/palyra/v1/common.proto#1-10.

​
Protobuf Service Definitions

The core services are defined using Protobuf to provide high-performance, versioned RPC interfaces. Key services include: For a detailed breakdown of every RPC method and message field, see Protobuf Service Definitions.

​
Cross-Language Stub Generation

Palyra ensures that clients in different languages remain synchronized with the daemon through a centralized generation pipeline. The script scripts/protocol/generate-stubs.ps1 parses the .proto files and emits native code structures for:
LanguageOutput FileUsage
Rustschemas/generated/rust/protocol_stubs.rsInternal daemon logic and CLI schemas/generated/rust/protocol_stubs.rs#1-7
Kotlinschemas/generated/kotlin/ProtocolStubs.ktAndroid and JVM-based integrations schemas/generated/kotlin/ProtocolStubs.kt#1-4
Swiftschemas/generated/swift/ProtocolStubs.swiftiOS, macOS, and Safari Extension schemas/generated/swift/ProtocolStubs.swift#1-3

​
Code Entity Mapping

This diagram shows how Protobuf definitions map to generated code entities across languages. “Protobuf to Native Code Mapping” Sources: schemas/proto/palyra/v1/browser.proto#7-20, schemas/generated/rust/protocol_stubs.rs#167-176, schemas/generated/kotlin/ProtocolStubs.kt#126-138, schemas/generated/swift/ProtocolStubs.swift#273-280.

​
Protocol Validation and CI Enforcement

To prevent breaking changes, the repository includes a suite of validation scripts that are executed during CI.
  1. Schema Validation: validate-proto.ps1 ensures all .proto files are syntactically correct and can be compiled into a descriptor set scripts/protocol/validate-proto.ps1#48-66.
  2. Stub Coherence: check-generated-stubs.ps1 verifies that the generated code in schemas/generated matches the current source definitions. If they differ, the CI build fails scripts/protocol/check-generated-stubs.ps1#14-21.
  3. Compilation Checks: Language-specific scripts like validate-kotlin-stubs.ps1 and validate-swift-stubs.sh attempt to compile the generated stubs using kotlinc and swiftc respectively to ensure no invalid code was produced scripts/protocol/validate-kotlin-stubs.ps1#25-29, scripts/protocol/validate-swift-stubs.sh#20-21.
For details on JSON schemas and the internal mechanics of the generation scripts, see JSON Envelope Schemas and Stub Generation. Sources:

​
Child Pages