Skip to main content
This section provides an overview of Palyra’s cross-language API contracts. Palyra maintains strict protocol governance to ensure compatibility between the Rust-based daemon (palyrad), the TypeScript/React web console, the Kotlin/Swift mobile scaffolds, and the various CLI tools. These contracts are defined primarily through Protocol Buffers (Protobuf) for RPC communication and JSON Schemas for persistent data and webhook envelopes.

​
Overview of Contract Governance

Palyra uses a “schema-first” approach where all external and internal service interfaces are defined in the schemas/ directory. These definitions serve as the single source of truth for:
  1. gRPC Services: Defining RPC methods for gateway, browser automation, and node management.
  2. JSON Envelopes: Defining the structure of webhooks, A2UI (Agent-to-User Interface) patches, and configuration exports.
  3. Cross-Language Stubs: Automated generation of Rust, Kotlin, and Swift code to ensure type safety across the monorepo.
The system enforces a PROTOCOL_MAJOR_VERSION to manage breaking changes across the ecosystem schemas/generated/rust/protocol_stubs.rs#5-5.

​
Service and Schema Landscape

The following diagram maps the relationship between the schema definitions and the code entities that implement or consume them. Schema to Entity Mapping Sources: schemas/proto/palyra/v1/gateway.proto#7-29, schemas/proto/palyra/v1/browser.proto#7-42, schemas/generated/rust/protocol_stubs.rs#1-7, schemas/generated/kotlin/ProtocolStubs.kt#1-4, schemas/generated/swift/ProtocolStubs.swift#1-3

​
Protobuf Service Definitions

Palyra uses Protobuf to define its core gRPC services. These definitions are organized by versioned packages (e.g., palyra.gateway.v1). For details on RPC methods and message structures, see Protobuf Service Definitions.

​
JSON Schemas and Envelope Formats

For asynchronous communication and data persistence where Protobuf is not suitable (e.g., Webhooks or A2UI state patches), Palyra utilizes JSON Schemas. These schemas enforce strict versioning via a v field and use additionalProperties: false to prevent schema drift.
  • Webhooks: Standardized envelopes for inbound events from platforms like Discord or Slack.
  • A2UI: The protocol for patching the Agent-to-User Interface state in the web console.
  • Config: Export and import formats for daemon settings.
For details on envelope structures and validation rules, see JSON Schemas and Envelope Formats.

​
Generated Stubs and Protocol Governance

To maintain synchronization across languages, Palyra employs a code generation pipeline. Stubs are not just generated but are also validated through compilation checks in CI. Protocol Build & Validation Pipeline Sources: scripts/protocol/generate-stubs.ps1#82-87, scripts/protocol/validate-rust-stubs.ps1#25-26, scripts/protocol/validate-kotlin-stubs.ps1#25-26, scripts/protocol/validate-swift-stubs.ps1#22-23 Key governance mechanisms include: For details on the generation pipeline and CI gates, see Generated Stubs and Protocol Governance.

​
Child Pages