> ## Documentation Index > Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt > Use this file to discover all available pages before exploring further. # Protobuf Schemas and Generated Stubs
Relevant source files The following files were used as context for generating this wiki page: * .github/codeql/codeql-config.yml * .github/workflows/ci.yml * .github/workflows/cli-full-regression.yml * .github/workflows/cli-install-smoke.yml * .github/workflows/codeql.yml * .github/workflows/dependency-review\.yml * .github/workflows/release.yml * .github/workflows/security.yml * schemas/generated/kotlin/ProtocolStubs.kt * schemas/generated/rust/protocol\_stubs.rs * schemas/generated/swift/ProtocolStubs.swift * schemas/proto/palyra/v1/browser.proto * schemas/proto/palyra/v1/gateway.proto
Palyra utilizes Protocol Buffers (v3) as the canonical definition for its internal and external service interfaces. These schemas define the communication contracts for the gateway, memory, browser automation, and security subsystems. A dedicated code generation pipeline ensures that these definitions remain synchronized across the Rust daemon, Kotlin/Android clients, and Swift/iOS applications. ## Protobuf Schema Definitions The core schemas are located in `schemas/proto/palyra/v1/` and are organized by functional domain. All services follow a versioned package naming convention (e.g., `palyra.gateway.v1`) [schemas/proto/palyra/v1/gateway.proto#3-3](http://schemas/proto/palyra/v1/gateway.proto#3-3). ### Core Service Schemas | Service | File | Primary Responsibility | | :----------------- | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GatewayService` | `gateway.proto` | Core agent orchestration, session resolution, and event streaming [schemas/proto/palyra/v1/gateway.proto#7-29](http://schemas/proto/palyra/v1/gateway.proto#7-29). | | `BrowserService` | `browser.proto` | Chromium/Simulated engine control, including navigation, DOM interaction, and tab management [schemas/proto/palyra/v1/browser.proto#7-45](http://schemas/proto/palyra/v1/browser.proto#7-45). | | `VaultService` | `gateway.proto` | Secure storage and retrieval of secrets indexed by scope and key [schemas/proto/palyra/v1/gateway.proto#37-42](http://schemas/proto/palyra/v1/gateway.proto#37-42). | | `ApprovalsService` | `gateway.proto` | Management and export of human-in-the-loop (HITL) authorization records [schemas/proto/palyra/v1/gateway.proto#31-35](http://schemas/proto/palyra/v1/gateway.proto#31-35). | | `AuthService` | `auth.proto` | Management of `AuthProfile` entities and provider-specific credentials [schemas/generated/rust/protocol\_stubs.rs#7-59](http://schemas/generated/rust/protocol_stubs.rs#7-59). | ### Common Types and Versioning All messages include a version field `uint32 v` to support forward and backward compatibility during rolling updates [schemas/proto/palyra/v1/browser.proto#48-48](http://schemas/proto/palyra/v1/browser.proto#48-48). Common primitives, such as `CanonicalId` (ULID-based identifiers), are shared via `common.proto` [schemas/proto/palyra/v1/gateway.proto#5-5](http://schemas/proto/palyra/v1/gateway.proto#5-5). ### Interface Data Flow: Browser Automation The following diagram illustrates how the `BrowserService` protobuf definition maps to system entities. **Diagram: Browser Protocol Entity Mapping** ```mermaid theme={null} graph TD subgraph "Natural Language Space" A["'Open a new tab and go to Google'"] B["'Take a screenshot of the page'"] end subgraph "Code Entity Space (browser.proto)" direction LR S1["BrowserService::OpenTab"] S2["BrowserService::Navigate"] S3["BrowserService::Screenshot"] M1["OpenTabRequest"] M2["NavigateRequest"] M3["ScreenshotResponse"] T1["BrowserTab"] B1["SessionBudget"] end A --> S1 A --> S2 B --> S3 S1 -.-> M1 S2 -.-> M2 S3 -.-> M3 M1 -.-> T1 S2 -.-> B1 ``` **Sources:** [schemas/proto/palyra/v1/browser.proto#7-45](http://schemas/proto/palyra/v1/browser.proto#7-45), [schemas/proto/palyra/v1/browser.proto#65-82](http://schemas/proto/palyra/v1/browser.proto#65-82). ## Code Generation Pipeline Stubs are generated using the `scripts/protocol/generate-stubs.sh` script [schemas/generated/rust/protocol\_stubs.rs#1-1](http://schemas/generated/rust/protocol_stubs.rs#1-1). This pipeline produces strongly-typed interfaces for three target languages: 1. **Rust:** Generated in `schemas/generated/rust/protocol_stubs.rs`. It includes `pub mod` blocks for each protobuf package and traits for service clients [schemas/generated/rust/protocol\_stubs.rs#7-59](http://schemas/generated/rust/protocol_stubs.rs#7-59). 2. **Kotlin:** Generated in `schemas/generated/kotlin/ProtocolStubs.kt`. It uses `data class` representations for messages and `interface` definitions for services [schemas/generated/kotlin/ProtocolStubs.kt#4-34](http://schemas/generated/kotlin/ProtocolStubs.kt#4-34). 3. **Swift:** Generated in `schemas/generated/swift/ProtocolStubs.swift`. It utilizes `enum` namespaces and `struct` message types with `Equatable` conformance [schemas/generated/swift/ProtocolStubs.swift#3-77](http://schemas/generated/swift/ProtocolStubs.swift#3-77). ### Stub Structure and Constraints Generated stubs are marked as `DO NOT EDIT` to prevent manual drift [schemas/generated/rust/protocol\_stubs.rs#1-1](http://schemas/generated/rust/protocol_stubs.rs#1-1). In the current build phase, many generated stubs utilize placeholder fields (e.g., `val placeholder: Int = 0`) to maintain ABI stability while the underlying serialization logic is finalized [schemas/generated/kotlin/ProtocolStubs.kt#5-26](http://schemas/generated/kotlin/ProtocolStubs.kt#5-26). **Diagram: Generation Pipeline and Artifact Distribution** ```mermaid theme={null} graph TD subgraph "Source (schemas/proto/)" P1["gateway.proto"] P2["browser.proto"] P3["common.proto"] end subgraph "Pipeline (scripts/protocol/)" GS["generate-stubs.sh"] end subgraph "Generated Artifacts" R["protocol_stubs.rs"] K["ProtocolStubs.kt"] S["ProtocolStubs.swift"] end P1 & P2 & P3 --> GS GS --> R GS --> K GS --> S R --> D["palyra-daemon"] K --> AM["Android Mobile App"] S --> IM["iOS Mobile App"] ``` **Sources:** [schemas/generated/rust/protocol\_stubs.rs#1-1](http://schemas/generated/rust/protocol_stubs.rs#1-1), [schemas/generated/kotlin/ProtocolStubs.kt#1-1](http://schemas/generated/kotlin/ProtocolStubs.kt#1-1), [schemas/generated/swift/ProtocolStubs.swift#1-1](http://schemas/generated/swift/ProtocolStubs.swift#1-1). ## CI Validation and Hygiene To ensure that schemas and generated stubs do not drift, the CI pipeline enforces several hygiene checks: * **Runtime Artifact Hygiene:** The `scripts/check-runtime-artifacts.sh` script is executed during the `quality` job to ensure no stale or unauthorized binary artifacts are present in the schema directories [.github/workflows/ci.yml#230-232](http://.github/workflows/ci.yml#230-232). * **Security Scanning:** All generated code is included in the `CodeQL` analysis matrix for Rust and JavaScript/TypeScript to detect potential vulnerabilities in the protocol implementation [.github/workflows/codeql.yml#19-25](http://.github/workflows/codeql.yml#19-25). * **Version Coherence:** The `scripts/release/assert-version-coherence.ps1` script validates that the protocol version matches the repository release version during the packaging flow [.github/workflows/release.yml#45-45](http://.github/workflows/release.yml#45-45). * **Cross-Platform Build Tests:** CI validates that the generated stubs compile correctly across Linux, macOS, and Windows runners [.github/workflows/ci.yml#26-34](http://.github/workflows/ci.yml#26-34). ### Protocol Security Gates The `security-gates` job performs supply chain auditing on the tools used for protocol management, including `cargo-audit` and `cargo-deny` to check for vulnerabilities in the protobuf compiler dependencies [.github/workflows/security.yml#95-99](http://.github/workflows/security.yml#95-99). **Sources:** [.github/workflows/ci.yml#215-232](http://.github/workflows/ci.yml#215-232), [.github/workflows/security.yml#95-99](http://.github/workflows/security.yml#95-99), [.github/workflows/codeql.yml#19-25](http://.github/workflows/codeql.yml#19-25), [.github/workflows/release.yml#41-60](http://.github/workflows/release.yml#41-60).