Monorepo & Build System

Relevant source files

The following files were used as context for generating this wiki page:

• pnpm-workspace.yaml
• package.json
• apps/desktop/package.json
• CONTRIBUTING.md
• README_en.md
• FEATURES.md

Zephyr utilizes a monorepo architecture to manage its desktop application, core business logic, and shared frontend packages. This structure allows for unified linting, testing, and dependency management across both Rust and JavaScript environments. The project relies on pnpm workspaces for frontend orchestration and cargo for the Rust-based backend and core logic.

The build system handles cross-platform compilation for Windows, macOS, and Linux, supporting both x64 and ARM64 architectures. It integrates specialized tools like Tauri for the desktop framework, UnoCSS for styling, and Style Dictionary for design tokens.

Sources: README_en.md, CONTRIBUTING.md

Workspace Architecture

Zephyr organizes its code into three main directories: apps, crates, and packages. This separation isolates the desktop entry point from reusable logic and shared assets.

Workspace Structure

• apps/: Contains the main desktop application built with Tauri.
• crates/: Holds Rust libraries, including the business logic (zephyr-core) and mobile-binding entries (zephyr-core-ffi).
• packages/: Includes shared frontend code, project scripts, and the design token system.

Sources: README_en.md, pnpm-workspace.yaml

Project Dependencies

The project enforces specific runtime and toolchain versions to ensure build consistency:

• Rust: Version 1.96.0+ (pinned via rust-toolchain.toml).
• Node.js: Version 20.18.1+.
• pnpm: Version 9+.

Sources: CONTRIBUTING.md, package.json:6-8

The diagram shows the relationship between the root workspace and its constituent modules, highlighting how the desktop application depends on core Rust crates and shared frontend packages.

Sources: README_en.md, pnpm-workspace.yaml

Build System Operations

The build system is driven by pnpm scripts in the root and member package.json files. It manages CSS generation, design token compilation, and the Tauri-specific build process.

Common Build Commands

Command	Action	Scope
pnpm install	Installs all workspace dependencies	Global
pnpm run dev	Starts the Tauri development environment	@zephyr/desktop
pnpm run build	Builds CSS and then the Tauri production binary	Global
pnpm run build:css	Compiles tokens, copies shared assets, and runs UnoCSS	@zephyr/desktop
cargo test --workspace	Runs all Rust unit and integration tests	Rust Workspace

Sources: package.json:10-18, apps/desktop/package.json:7-17, CONTRIBUTING.md

Frontend Build Pipeline

The desktop frontend build process involves several sequential steps before the Tauri bundler starts:

1. Design Tokens: style-dictionary builds CSS variables from primitive and semantic definitions.
2. Shared Assets: Shared JavaScript logic is copied from packages/shared to the desktop source.
3. Styling: UnoCSS processes atomic classes and generates the final stylesheet.
4. Editor Bundle: esbuild bundles CodeMirror 6 components for the rule editor.

Sources: apps/desktop/package.json:9-14

Testing & Quality Verification

Zephyr implements a multi-tier verification strategy across its Rust backend and JavaScript frontend.

Rust Verification

The project uses cargo clippy with 170 deny rules classified into four tiers:

1. Correctness & Security: Denies unwrap_used, expect_used, and undocumented_unsafe_blocks.
2. Concurrency & Memory Safety: Denies rc_mutex and future_not_send.
3. Memory Allocation Performance: Denies redundant_clone and large_enum_variant.
4. CPU & Algorithm Performance: Denies suboptimal_flops.

Sources: CONTRIBUTING.md, FEATURES.md

Automated Testing Tiers

• Unit Tests: Located inline within Rust modules (#[cfg(test)]).
• Snapshot Tests: Utilizes the insta crate for Golden snapshot testing of 68 scenarios, including config sanitization and name truncation.
• Frontend Tests: Uses vitest with a happy-dom environment for unit and state machine testing.
• Integration Tests: Comprehensive backend tests are located in apps/desktop/src-tauri/src/prism_tests.rs.

Sources: CONTRIBUTING.md, FEATURES.md, apps/desktop/src-tauri/src/prism_tests.rs

CI/CD Pipeline

The project uses GitHub Actions to enforce security and quality standards on every pull request and push to the main branch.

The CI pipeline ensures that code passes strict linting, security audits, and tests before generating Software Bill of Materials (SBOM) and release binaries.

Sources: CONTRIBUTING.md, FEATURES.md

Security Controls

The build pipeline includes specific security jobs:

• cargo-deny: Checks for disallowed licenses (e.g., AGPL-3.0).
• Semgrep SAST: Scans for static vulnerabilities.
• Trufflehog: Detects hardcoded secrets.
• SBOM Generation: Merges Rust and Frontend SBOMs into a single merged-sboms.json via a specialized Python script.

Sources: FEATURES.md, package.json:34

Summary

The Zephyr Monorepo and Build System provide a standardized environment for developing a cross-platform desktop application. By leveraging pnpm workspaces and cargo, the project maintains a clear separation between its native business logic and its lightweight frontend. Strict CI/CD controls, including 170 Clippy deny rules and automated security audits, ensure the integrity and safety of the final application binaries.

Sources: README_en.md, CONTRIBUTING.md, FEATURES.md