Engine-First egui Application Architecture (L0–L7)
This skill guides you through setting up and maintaining a pure-Rust, engine-first desktop (eframe/egui), CLI, and WebAssembly application with strict architectural boundaries.
Architectural Principles
- Strict Acyclic Layering (
L0–L7): Every workspace crate is assigned a layer inxtask/src/layers.rs. A crate at layer $N$ may only depend on crates in layers $< N$ (plus explicit intra-layer chains). - Standalone Format & OS Helper Crates: Reusable parsers/encoders (
codecs,formats) and isolated OS helpers are classified asStandaloneatL0and must have zero workspace dependencies so they remain independently publishable and testable. - UI Containment (
L6+only): No crate belowL6may depend on UI or windowing crates (egui,eframe,winit,rfd).L0–L5must compile headlessly and forwasm32-unknown-unknown. - Never Crash (No Panic, No Unsafe): Workspace-wide
unsafe_code = "forbid"and#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]on every library and binary crate. If an isolated OS integration crate requires FFI, isolate it in its ownL0crate withunsafe_code = "deny"and explicitSAFETY:comments and platform tests.
Step-by-Step Workflow
1. Organize the Cargo Workspace into Layers
Structure the repository into crates/*, apps/*, and xtask (adapt layers as needed for your domain):
L0Foundation: Core primitives, geometry, math, and copy-on-write data containers.L0Standalone: Format parsers/writers and OS helpers with no workspace dependencies.L1Document / Domain Model:doc— pure serializable data structures (document tree, entities, metadata). No rendering or UI logic.L2Operations & Algorithms:ops(undo/redo history),algo(domain transformations, queries, and processing).L3Rendering & Native Persistence: CPU/GPU rendering backends (wgpu) andformat(content-addressed or structured native bundle).L4I/O & Plugins:io(maps standalone formats $\leftrightarrow$doc::Document), optional sandboxed plugins.L5Engine Façade:engine(Session,CommandSpecregistry, backgroundJobs,Preferences).L6Shells & Automation:ui-egui(thineguifrontend + optional JSON control protocol),automation(MCP server + headless JSON-RPC).L7Binaries (Exempt):apps/<app>(desktopeframebinary),apps/<app>-cli(headless CLI + MCP/RPC host),apps/<app>-web(browser Wasm),xtask.
2. Configure Workspace Lints and Cargo Profiles
Apply the workspace lint gates and build profiles in the root Cargo.toml.
See layering-and-profiles.md for the exact Cargo.toml configuration:
- Optimize dependencies in dev builds (
[profile.dev.package."*"] opt-level = 2) so rendering and compute loops run at interactive speeds during development. - Use
debug = "line-tables-only"in[profile.dev]to halve link times and symbol sizes. - Set
[profile.test.package.<ui-crate>] opt-level = 0to speed up UI test compilation. - Configure
[profile.wasm-release]withlto = "fat"and per-crateopt-leveloverrides ("z"for data/parsers/UI,3for hot compute crates).
3. Enforce Layering with cargo xtask layers
Whenever adding a crate or dependency:
- Register the crate in
xtask/src/layers.rs(TABLE). - Add the crate header lints (
#![forbid(unsafe_code)]and#![deny(clippy::unwrap_used, ...)]) to itssrc/lib.rs. - Write or update
Cargo.tomlatomically if working alongside parallel agents.
4. Validation Steps
Run these commands to verify architectural compliance (see egui-testing-infrastructure for the full 7-tier verification, corpus, performance, and scorecard workflow):
cargo xtask layers
cargo xtask wasm
cargo clippy --workspace --all-targets -- -D warnings