palyrad), the browser automation service (palyra-browserd), and various client SDKs (Kotlin, Swift). These protocols are defined using Protocol Buffers (Protobuf) for RPC services and JSON Schema for message envelopes and configuration exports.
All schema definitions and their generated outputs reside in the schemas/ directory 1.1:Repository Structure.
System Architecture and Schema Flow
The following diagram illustrates how Protobuf definitions are transformed into language-specific stubs used by different components of the system.Schema Transformation Pipeline
Sources: scripts/protocol/generate-stubs.ps1#82-91, scripts/protocol/validate-proto.ps1#6-7Protobuf Service Definitions
The core of Palyra’s communication is defined inschemas/proto/palyra/v1/. These files define the gRPC services and message structures used for orchestration, security, and automation.
| Service | File | Primary Responsibility |
|---|---|---|
GatewayService | gateway.proto | Main entry point for Run orchestration and message routing schemas/proto/palyra/v1/gateway.proto#7-29. |
BrowserService | browser.proto | Interface for palyra-browserd to control Chromium instances schemas/proto/palyra/v1/browser.proto#7-42. |
VaultService | gateway.proto | Secure storage and retrieval of encrypted secrets schemas/proto/palyra/v1/gateway.proto#37-42. |
ApprovalsService | gateway.proto | Management of human-in-the-loop tool execution approvals schemas/proto/palyra/v1/gateway.proto#31-35. |
AuthService | auth.proto | Management of OAuth profiles and API credentials. |
Multi-Language Stub Generation
To maintain type safety across the monorepo, Palyra uses a custom generation pipeline. Unlike standardprotoc outputs which can be verbose, the generate-stubs.ps1 script produces ergonomic stubs for Rust, Kotlin, and Swift.
Language Mappings
The generator maps Protobuf packages to native language constructs:- Rust: Packages become modules with
CamelCasemessage names andSnake_Casetraits schemas/generated/rust/protocol_stubs.rs#7-59. - Kotlin: Packages become
objectscontainingdata classdefinitions schemas/generated/kotlin/ProtocolStubs.kt#4-34. - Swift: Packages become
enumscontainingstructandprotocoldefinitions schemas/generated/swift/ProtocolStubs.swift#3-77.
Stub Coherence
The CI pipeline enforces that generated stubs are never out of sync with the source.proto files. The check-generated-stubs.ps1 script runs the generator and performs a git diff to ensure no manual changes or omissions exist scripts/protocol/check-generated-stubs.ps1#9-21.
For details on the JSON envelope schemas and the validation logic, see JSON Envelope Schemas and Stub Generation.
Protocol Validation and Safety
Every change to the protocol undergoes a multi-stage validation process to prevent breaking changes in the distributed system.Validation Flow
Sources: scripts/protocol/validate-proto.ps1#43-46, scripts/protocol/validate-rust-stubs.ps1#9-15, scripts/protocol/validate-kotlin-stubs.ps1#9-15, scripts/protocol/validate-swift-stubs.ps1#9-15- Protoc Validation: Ensures all
.protofiles are syntactically correct and imports are resolvable scripts/protocol/validate-proto.ps1#58-63. - Compiler Verification: Each generated stub file is compiled using its native compiler (
rustc,kotlinc,swiftc) to ensure the generated code is valid scripts/protocol/validate-rust-stubs.ps1#25-27.
- schemas/proto/palyra/v1/gateway.proto#1-256
- schemas/proto/palyra/v1/browser.proto#1-242
- schemas/generated/rust/protocol_stubs.rs#1-179
- scripts/protocol/generate-stubs.ps1#1-203
- scripts/protocol/check-generated-stubs.ps1#1-24