Workspace Architecture
Palyra is managed as a Rust-centric monorepo using a Cargo workspace to coordinate multiple crates, while also hosting application-specific code for web, desktop, and mobile platforms.Cargo Workspace Configuration
The rootCargo.toml defines the workspace members and shared metadata. It uses a centralized versioning and dependency management strategy to ensure consistency across the platform.
| Property | Value |
|---|---|
| Rust Edition | 2021 Cargo.toml#23 |
| Rust Version | 1.91 Cargo.toml#26 |
| Resolver | Version 2 Cargo.toml#20 |
| License | PCSL v1.1 (referenced as LICENSE) Cargo.toml#24 |
unsafe_op_in_unsafe_fn Cargo.toml#85 and various Clippy lints such as dbg_macro Cargo.toml#90 and todo Cargo.toml#91.
Monorepo Layout
The repository is organized into functional directories:crates/: Core logic, libraries, and the primary Rust binaries.palyra-daemon: The central control plane (palyrad) crates/palyra-daemon/Cargo.toml#12.palyra-cli: The primary command-line interface (palyra) crates/palyra-cli/Cargo.toml#12.palyra-common: Shared utilities including the workspace patching pipeline Cargo.toml#3.palyra-plugins/: Contains the Wasmruntimeandsdkfor skill extensibility Cargo.toml#14-15.
apps/: Platform-specific client applications.apps/web: React/TypeScript web console scripts/run-pre-push-checks.sh#46.apps/desktop: Tauri-based desktop supervisor and UI Makefile#95.apps/android/apps/ios: Mobile client scaffolds justfile#27.
schemas/: Cross-language protocol definitions.schemas/proto/: Protobuf definitions for gRPC services (Gateway, Auth, Node, etc.) crates/palyra-daemon/build.rs#7-14.schemas/json/: JSON schemas for envelopes and configuration.
scripts/: Automation for bootstrapping, protocol generation, and CI gates.
Workspace Dependency Graph
The following diagram illustrates how the primary binaries consume internal crates. Crate Relationship Diagram Sources: Cargo.toml#1-19, crates/palyra-daemon/Cargo.toml#22-34, crates/palyra-cli/Cargo.toml#25-32Task Runner and Orchestration
Palyra uses a dual-interface task runner system supporting bothmake and just. These runners wrap complex operations like gRPC stub generation, environment validation, and security auditing.
Primary Commands
TheMakefile and justfile provide identical targets for core workflows:
make doctor: Runs strict environment checks via the CLI’sdoctorcommand to ensure the local toolchain is compatible Makefile#10.make dev: The standard entry point for developers. It validates the environment, ensures the desktop UI is built, and compiles the workspace Makefile#16-19.make protocol: Validates.protofiles and generates Rust stubs usingscripts/protocol/generate-stubs.shMakefile#29-32.make security: Executes a suite of audits includingcargo audit,cargo deny, and custom scripts to check for high-risk patterns or leaked artifacts Makefile#56-62.
Pre-push Integrity
A git hook.githooks/pre-push:4 executes scripts/run-pre-push-checks.sh. This script supports two profiles:
fast(default): Checks JS workspace health,rustfmt, module budgets, and runs the deterministic core smoke suite scripts/run-pre-push-checks.sh#49-72.full: Includes allfastchecks plusclippy, full workspace tests, and the workflow regression matrix scripts/run-pre-push-checks.sh#74-108.
Protocol and Build Logic
The codebase uses a “Schema-First” approach. gRPC services are defined inschemas/proto and compiled into Rust modules during the build phase of the daemon and CLI.
Build-time Code Generation
Bothpalyra-daemon and palyra-cli utilize build.rs scripts to invoke tonic-build. This ensures that any change to the .proto files triggers a recompilation of the dependent Rust code.
Protocol Build Flow
Key services compiled include:
GatewayService: Primary gRPC interface crates/palyra-daemon/build.rs#8.NodeService: Multi-node coordination crates/palyra-daemon/build.rs#13.AuthService: OAuth and profile management crates/palyra-daemon/build.rs#11.
Navigation and Hygiene
Environment Bootstrapping
Initial setup is handled by platform-specific scripts:scripts/dev/bootstrap.sh(Linux/macOS)scripts/dev/bootstrap.ps1(Windows)
make dev can be successfully executed.
Artifact Hygiene
The repository maintains strict rules against committing runtime artifacts. The.gitignore excludes target/, node_modules/, and various .tmp or .log files .gitignore:1-34. The task runner includes artifact-hygiene checks to ensure that no generated data (like SQLite databases or temporary certificates) is accidentally tracked Makefile#63-64.
Sources: scripts/dev/bootstrap.sh, scripts/dev/bootstrap.ps1, Makefile#63-68, .gitignore#1-72