Architecture
The patterns the architect template is showcasing.
architect’s architecture is opinionated: contracts are the source of truth, implementations are pluggable, and the monorepo layout makes the distinction visible at a glance.
Pages in this section#
- The architect pattern — what
#[derive(architect::Entity)]emits and how to write an entity. - Multi-backend features — one contract, multiple implementations behind one facade.
- Extensibility — in-tree vs third-party implementations; how the contract crate makes both paths interchangeable.
- Construction: Resource & Scope —
build the backend (
config → pool → repo) with dependent composition, memoization, and LIFO teardown. - Monorepo layout — one crate per feature,
with its layers as cargo features; apps under
apps/<app>/. - The in-process transport —
LocalServer: typed clients over a vox memory link; desktop, CLI, and tests with no server. - The HTTP face —
#[architect::service]: one trait, vox and HTTP+JSON, clients for both; how a host mounts the generated faces next to its plugins. - Testing strata — native unit, native integration, browser e2e: which lives where.
- Server push —
PubSub, Entity events,#[subscribe]streams, the client hooks, and the real-time-safety rules for audio-thread producers. - Idioms & enforcement — the vox + Dioxus conventions (data flows through vox, never Dioxus server functions) and the CI gates that keep them honest.
- Spec coverage — per-feature
features/<feature>/spec/*.mdtracked by tracey. - The auth feature — the session RPC surface,
AuthServerMiddleware, the client session kit, and the engine underneath. - Scheduling & resilience —
scheduleretry/repeat policies (exponential backoff, jitter, caps) and theplatformclock they run on (deterministicTestClockincluded); how clients tolerate a flaky server. - Collaboration — Loro CRDT
documents,
DocSyncover vox, the multi-docDocRegistry, presence and persistence. - Peers: documents between nodes —
crdt::peer: pairwise exchange with no hub, and per-document access checked by every node. - Devices: who a node lets in —
architect-devices: the account’s devices, per-org enrolment, pairing by code or QR, and one admission table every lane checks. - Async diagnostics — a design note for moiré instrumentation of the axum_ws adapter (not in the tree today).
- Commands: the Action List — one
registry every key, menu, palette, CLI and MCP model runs an app’s
commands through;
architect-mcp; per-action timings. - Theming —
architect-theme: a palette resolved into every token, the cascade from the app’s default to a preview, theme files that hot-reload,THEME_*actions, and how the shell, architect-ui and paint views follow one store.
In this section
- The architect patternOne source struct, every surface — wire, repo trait, storage.
- Multi-backend featuresOne contract, swappable storage.
- ExtensibilityTwo ways to add features: in-tree (monorepo) and external (third-party crate).
- Construction: Resource & ScopeBuild the backend — config → pool → repo — with dependent composition, build-once sharing, and LIFO teardown.
- Monorepo layoutapps/<app>/<role> + features/<feature>: one crate per feature, roles as cargo features.
- The in-process transportarchitect::local — serve a LayerRouter over a vox memory link: typed clients, no server, no socket.
- The HTTP face#[architect::service] — one trait, vox and HTTP+JSON, clients for both; what the derive emits and how a host mounts it.
- Testing strataNative unit, native integration, browser e2e — which lives where.
- Server push: streams end to endPubSub fan-out, Entity events, #[subscribe] siblings, the client hooks — and the real-time-safety rules.
- Idioms & enforcementThe bearcove/vox + Dioxus conventions architect follows, and what keeps them honest.
- Spec coveragePer-feature spec rules tracked by tracey.
- Composing the UIHow architect's Dioxus client is structured: feature crates own state + presentation, the shell owns transport + routing + composition, and pages compose by matching an AtomResult phase.
- Organizations: the spine everything is scoped byThe organization (workspace) is architect's, not an app's: files, documents, settings, extensions, presence, permissions and the shell's switcher all know which org they are in, so every app gets multi-org behaviour without writing it.
- Spaces: rooms with collaborators, below the orgA space names part of an org — a project, a wiki, a folder, a document, a session — and has its own members (from this org, from others, link guests), roles that compile to permits, per-resource grants and an org policy that caps them. One model drives the gate, documents and files.
- The app shellOne shell for every FastTrackStudio app: a title and its actions at the top, four tabs and a separate button at the bottom, a sidebar on each side — laid out for a phone, a tablet and a desk from one declaration.
- The auth featurearchitect-auth — the session RPC surface, the server middleware, the client session kit, and the engine underneath.
- Optimistic state (architect-atom)Client-side optimistic, stale-while-revalidate state for Dioxus — the client twin of architect's server-side Layer/Resource DI, borrowed from effect-atom without the monad.
- The workspace: docking, tabs and screensetsOne layout system for every app: tab groups in splits, docks on each side, stacked tabs, pop-out windows, per-tab history, and screensets — as flexible as Obsidian, REAPER and Premiere, so no app builds docking again.
- App menusThe menu bar (File, Edit, View, …) built from the Action List: native on macOS, the shell's own elsewhere, enabled and ticked as the actions are.
- Feature flagsEvery architect cargo feature, what it implies, and which profile to reach for.
- Motion: one clock for every animationSprings and coasts on one clock: the wall clock in a window, architect-guide's virtual clock in a film or a test. The workspace's docks, tab moves, stacked tabs and splits move on it.
- App presenceHow a desk app lives when its window is not on screen: the Dock icon (badge, menu, progress, attention), a menu-bar or tray item, background mode, reopen, opening at login and one instance, all on the Action List.
- Forms (architect-form)Typed, validated form state for Dioxus — the effect-form analog, building on architect-atom and submitting through vox.
- Settings: declared once, a page for freeAn app declares its settings as typed structs; architect stores them (per device or synced to the person), and builds the Settings page — T3 Code's design — with search, reset and restore.
- Documents: one layer for files, undo, sync and peersWhat an app's work is saved as, how it is undone, versioned, synced to a server and to peers, and how its media travels — architect's, so an app only declares its schema.
- ErrorsRepoError's four variants and when each is right, ClientError<E> on the client, and the blessed pattern for a custom service error enum.
- Devices: who a node lets inarchitect-devices — this device on the account, an org's enrolled devices, pairing a device by code or QR, revoking, and the one admission table every peer-to-peer lane checks.
- Peers: documents between nodescrdt::peer — pairwise document exchange with no hub, and per-document access the library checks.
- Real-time collaboration (Loro)Offline-first collaborative state: Loro CRDT replicas synced over vox channels — local writes are instant, everything merges, reconnects are deltas.
- Scheduling & resiliencearchitect::schedule retry/repeat policies and the architect::platform clock they run on.
- Async diagnosticsmoiré runtime instrumentation — see what every task is waiting on.
- Commands: the Action ListOne registry of everything an app can do. Keys, menus, the palette, a CLI and a model over MCP all run the same action by id.
- App settingsarchitect::settings — a typed Store<T> of facet JSON in the app's config dir (atomic, skip-if-equal, optional 0600), and FileKv.
- Capability tokensEd25519-signed, expiring purpose|expiry|subject grants, and the 0600 server key file behind them.
- Blob transfer and storageResumable, sha256-verified fetch into place, a content-addressed blob store, and blobs by hash on demand from peers and servers: streamed, pinned, collected.
- Crash flight recorderarchitect_telemetry::flight — a tracing log ring, crash.log and flight-log.txt in the app dir, and the previous run's last lines at launch.
- Snapshot quiesceWriteGate, GatedLayer and the bounded pause → checkpoint → step cycle for consistent on-disk snapshots.
- Keymaps (architect-input)architect-input: a key trie, a modal input processor and which-key, binding keys to Action List ids.
- Signed self-updateReplace a running binary with a newer GitHub Release, only after its signature, checksum and version check out.
- Actions everywhere: bindings, ⌘K and ⌘OREAPER's Action List, taken further: everything any UI does is an action, any action binds to any number of keys, sequences, held-letter mouse tools, MIDI or OSC, per context; which-key, a ⌘K palette and a ⌘O open-anything come free.
- App updatesHow the Architect app updates itself: a check at start and daily, Install on request, verified against the org-signed sums, written where the Nix launcher or the AppImage expects it.
- Guide mediaOne scenario file, three outputs: a headless film (GIF, WebM, MP4, poster), a test, and an in-app tour; a story carries its own.
- Extensions and scriptsAdding to an app at runtime, without rebuilding it: data-only extensions, WASM components over a versioned WIT world drawn from the Action List, Luau scripts for macros, out-of-process plugins on a desk — with capabilities, and views as frame documents.
- Embedded views: view kindsOne contract every view mounts through — a Dioxus component, a GPU scene, a web view, a Frame surface, an agent's generated UI — a registry of the kinds an app provides, where each can be shown and mounted, and what each may do.
- Pages as filesA view written as a file — TSX or JS on QuickJS (in a browser, a Web Worker), Luau elements, A2UI JSON — re-rendered live on save, on a thread of its own, drawn as the same edit stream a process view sends; one API defined once in Rust, its TypeScript and Luau types generated from it.
- ThemingRuntime themes: a small palette resolved into every semantic token, a cascade of layers from the app's default to a transient preview, theme files that hot-reload, THEME_* actions, and how the shell, architect-ui and view kinds follow one store.
- The interface as files, the chrome as slotsThe shell's regions are slots a view can fill, and the window — its slots, its look, its arrangement, its keys — is files under the app's folder that an agent or a person edits live, a broken one keeping its last good version.
- Toolbars: the visual editorEdit toolbars in place — + chips, drag and drop, action and widget pickers, item and toolbar settings — and every edit as a TOOLBAR_* action, written debounced with rolling backups.
- Project files: projects, assets and their syncThe spec for architect's files feature (#347): every org's projects and asset libraries held by the headless node in place, pinned per machine, browsed on demand, versioned, previewed, on what architect already has.
- File registry and copies: every file, where it lives, how many verified copiesThe spec for the files feature's registry (#347): one local index of every file in every root a device may see, searchable offline, and signed, verified accounting of which holders store each blob, so a copy count is a fact.
Linked from
- architectA Rust framework for local-first, multiplayer, collaborative apps: declare each service and document once, and architect gives you every wire, offline and peer-to-peer sync, and one Action List that keys, menus, scripts, extensions and MCP all run.
- FeaturesOne page per major architect feature: what it is, the least code to use it, a tour of its code, the tests to read, and its status.