Skip to main content
Palyra utilizes a schema-first design where all cross-process and cross-platform communication is defined using Protocol Buffers (Protobuf). These definitions serve as the single source of truth for the gRPC services and message structures used by the Rust daemon, CLI, and various mobile/web stubs.

​
Architecture Overview

The protocol architecture is designed to ensure strict versioning and prevent “schema drift” between the central daemon (palyrad) and its clients (CLI, Mobile, Browser Extension).

​
Data Flow and Contract Enforcement

The system maintains a hierarchy of schema definitions and generated artifacts:
  1. Definitions: .proto files located in schemas/proto/palyra/v1/.
  2. Rust Stubs: Generated during the build process of internal crates (e.g., palyra-daemon, palyra-cli) using tonic-build.
  3. Cross-Platform Stubs: Pre-generated stubs for Kotlin and Swift, stored in schemas/generated/, ensuring that mobile and external clients can interact with the daemon without requiring a local Protobuf compiler.
  4. Validation: CI/CD scripts that verify the generated stubs match the current .proto definitions.

​
System Entity Mapping

The following diagram bridges the Protobuf service definitions to the actual code entities within the Rust crates. Diagram: Service to Code Entity Mapping Sources: schemas/proto/palyra/v1/gateway.proto#7-29, crates/palyra-daemon/build.rs#8-35, crates/palyra-cli/build.rs#8-35

​
Schema Definitions

The schemas are organized by domain under schemas/proto/palyra/v1/.

​
Core Services and Messages

ServiceProto FilePrimary Responsibility
GatewayServicegateway.protoRun orchestration, session management, and agent CRUD.
ApprovalsServicegateway.protoQuerying and exporting human-in-the-loop approval records.
VaultServicegateway.protoSecure storage and retrieval of secrets.
CanvasServicegateway.protoReal-time state synchronization for A2UI (Agent-to-User Interface).
BrowserServicebrowser.protoHeadless browser control and automation.

​
Common Types (common.proto)

The palyra.common.v1 package defines primitives used across all services: Sources: schemas/proto/palyra/v1/gateway.proto#1-51, schemas/proto/palyra/v1/common.proto#1-310

​
Generated Stubs

​
Rust Build Pipeline

The Rust crates use build.rs scripts to compile Protobuf files into Rust code at compile time. They utilize protoc-bin-vendored to ensure a consistent protoc version across developer environments.

​
Cross-Platform Support

For platforms where a Rust toolchain or protoc might not be available (e.g., lightweight mobile development), the repository includes pre-generated stubs: Sources: crates/palyra-daemon/build.rs#1-38, schemas/generated/kotlin/ProtocolStubs.kt#1-145, schemas/generated/swift/ProtocolStubs.swift#1-250

​
Validation and Drift Prevention

To ensure that the pre-generated stubs never fall out of sync with the .proto files, the system employs a suite of validation scripts. Diagram: Protocol Validation Workflow

​
Key Validation Scripts

  • validate-proto.ps1: Uses protoc with --descriptor_set_out to ensure all .proto files are syntactically correct and imports are resolvable scripts/protocol/validate-proto.ps1#57-66.
  • check-generated-stubs.ps1: Orchestrates the validation of all language-specific stubs.
  • validate-rust-stubs.ps1: Compiles the Rust stubs and compares the output against the tracked protocol_stubs.rs.
Sources: scripts/protocol/validate-proto.ps1#1-72, schemas/generated/rust/protocol_stubs.rs#1-5

​
Implementation Details

​
Versioning

The protocol defines a PROTOCOL_MAJOR_VERSION (currently 1) to handle breaking changes in the future schemas/generated/rust/protocol_stubs.rs#5. Every message typically includes a uint32 v = 1; field to allow for per-message schema evolution schemas/proto/palyra/v1/gateway.proto#86.

​
Field Reservations

To maintain backward compatibility during development, the schemas extensively use the reserved keyword for deleted field numbers and names schemas/proto/palyra/v1/gateway.proto:82, 105, 119. Sources: schemas/generated/rust/protocol_stubs.rs#1-10, schemas/proto/palyra/v1/gateway.proto#80-120