Features
One 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.
Each page has the same five sections:
- What it is and when to use it, with a link to the design page under Architecture.
- A minimal example: the least code an app writes.
- Code tour: the files and symbols in reading order, and how one call flows through them.
- Tests to read: the tests that show it working end to end.
- Status: what is done in architect, and what Task and Studio still have to adopt.
When a page and the code disagree, the code is right.
Core#
- Services and entities:
#[architect::entity],#[architect::service],#[architect::rpc]and the layers they emit. - Transports: vox in process, over WebSocket and over iroh; the HTTP face with query arguments, ranged bytes and SSE.
- EngineHost and protocol mounts: one server binary,
/vox,/health,/version.json,vox_at,document,dav,otlp_forward. - Errors:
#[architect::error],ClientError, the HTTP error envelope. - Telemetry: call spans as wide events, stages,
rpc.server.duration, trace context across calls. - PubSub and streams: fan-out hubs,
#[subscribe], client hooks, the full-sink pump.
Data#
- Documents:
CrdtDoc, kinds of document, named undo,DocRegistry. - The document file:
crdt::file, one durable file per document. - Org sync driver:
OrgSyncs,OrgDocs,Placement. - Peer to peer: pairwise exchange, iroh, device admission, share links.
- Devices: the account’s devices, per-org enrolment, pairing by code or QR, revoking, one admission table.
- Presence and collaborative text:
Here,Roster, places,TextBinding,crdt(text). - Blobs: content-addressed bytes fetched on demand, pinned and collected.
- Files:
architect-files, an org’s files with versions, quota and access. - Attachments:
architect-attachments, files attached to documents and records, offline first, access following the parent. - Bases:
architect-bases, a vault’s.basefiles as table, cards and list views, view types extensions add,BASES_*.
Identity#
- Auth: the auth engine, its services, the client kit,
apps/auth-server. - Permissions:
Principal, permit tables,PermissionsGate, the Action List authorizer. - Organizations:
architect-orgs, the current org, scopes, server confinement.
App#
- Settings:
#[derive(Settings)], scoped values, the settings page. - Commands and the Action List:
ActionList, the palette, the action list window, MCP. - Key bindings:
architect-input, the person’s keymap, the binding editor. - Menus:
MenuBarfrom the commands, native and in the window. - Workspace and shell: tab groups, docks, pop-out windows, screensets, the app frame.
- Atom and forms: the optimistic store, the offline call queue, validated fields.
- Editor:
architect-editor, the one door to the editor repository; the language registry,[[languages]], thesyntax.*theme tokens. - Capture: one quick-add parser, the composer, a capture window on a system-wide shortcut, the vault inbox and processing it,
[[capture_targets]],CAPTURE_*andINBOX_*.
Extending#
- Scripting: Luau over the Action List, saved scripts as actions.
- Extensions: run-time packages from registries, hot reload, project requirements.
- Canvas overlays and ImGui-shaped UI: drawing over a view in its coordinates; tool windows for scripts.
- Remote views: a process extension’s Dioxus views in workspace panes.
- Navigator: folders beside notes in the sidebar, a port of Notebook Navigator (GPL-3.0), as a built-in extension.
- A2UI: agents’ generated UI: an agent’s form, list or approval drawn with architect-ui from a catalog, kept in Loro, its buttons asking before any write.
- Sites: a vault published as a static site, extensions drawing their blocks, hosted by the architect server.
In this section
- Services and entitiesThe derives: one Rust declaration gives the wire types, the vox service, the HTTP face, the clients and the actions.
- TransportsOne router, any wire: vox in process, over WebSocket and over iroh; the HTTP face with query arguments, ranged bytes and SSE.
- EngineHost and protocol mountsOne server builder: /health, /vox and /version.json always; plugins, protocol mounts and iroh by builder method; the permissions gate on every vox lane.
- ErrorsOne typed error per service, the same on every wire: #[architect::error], ClientError, the HTTP envelope.
- TelemetryWide events: each call is a span you enrich, stages are child spans, calls and stages are metrics, and one trace follows a caller into the calls it makes.
- PubSub and streamsServer push: PubSub hubs, #[subscribe] streams over vox and SSE, the client hooks, and the pump that delivers past a full sink.
- DocumentsCo-edited state as Loro documents: CrdtDoc, kinds of document with schema stamps and migrations, named undo, DocRegistry, crdt entities and the sync hooks.
- The document filecrdt::file: one append-only file per document, every finished step durable, Save as name and fold, crash recovery, branches, versions and blobs.
- Org sync driverOrgSyncs, OrgDocs and Placement: a device keeps every document of each of its orgs synced, offline-safe, in the files the person opens.
- Peer to peerDevices sync documents with each other directly over iroh, admitted per document; a share link opens one live document to a guest.
- DevicesThis device on the account, an org's enrolled devices, pairing by code or QR, revoking — and the one admission table every peer-to-peer lane checks.
- Presence and collaborative textWho is here and where: pointers as places in a view's coordinates, selections, carets and playheads; text that merges, with remote carets.
- Blobsarchitect::blob: content-addressed bytes, fetched by hash on demand from a peer or a server, streamed while they arrive, resumed, pinned and collected.
- Filesarchitect-files: an org's files in roots, a version per save, labels, resumable uploads and ranged reads over vox and HTTP, renditions, quota, access by role and per-folder grants.
- Attachmentsarchitect-attachments: files attached to a document or a record, kept by hash, offline first, uploaded resumably and once, under a quota, previewed through renditions, readable by whoever may read the parent.
- Drivearchitect-files' drive: every project and asset library a device knows, mounted as a real folder (FUSE), pinned roots at local speed, the rest fetched on open and kept for offline use.
- AuthAccounts and sessions: the auth engine, its services on every transport, the client kit (token store, OIDC with PKCE, device flow), and apps/auth-server.
- PermissionsPrincipal, resource, action: permit tables per service, PermissionsGate on every mounted router, observe-only for migration, and the same engine for Action List runs.
- Organizationsarchitect-orgs: the person's organizations, the window's current one or All, roles and capabilities, the switcher, everything stored under the org, and servers confined to the caller's org.
- SettingsSettings declared once (a struct, or data an extension registers), held by scope over an org's defaults and locks, stored on the device, the project or the person's synced document, and drawn as one settings page.
- Commands and the Action ListOne registry of everything a person or an agent can do: the ActionList, actions from a service, the ⌘K palette, ⌘O, the action list window, custom actions, and MCP.
- Key bindingsarchitect-input's keymap engine (chords, sequences, modes, contexts, held-letter tools, MIDI and OSC, which-key), the person's keymap over the app's, and the binding editor.
- MenusThe menu bar declared over command ids: labels, shortcuts, enabled state and ticks from the commands, live sections, native on macOS, Linux and iPadOS, in the window elsewhere.
- Workspace and shellarchitect-workspace: tab groups in splits, docks, stacked tabs, floats, pop-out OS windows, stable pane ids and screensets; architect-shell: the app's frame on desk, tablet and phone.
- Atom and formsarchitect-atom: optimistic, stale-while-revalidate client state, a keyed store with temp ids, mutations that patch then reconcile, device rows and an offline call queue; architect-form: typed, validated fields.
- Scriptingarchitect-scripting: Luau over the Action List; a run is one undo step; saved scripts become actions in ⌘K, keys and MCP; errors carry their line.
- Extensionsarchitect-extensions: packages that add actions, settings, views and document data at run time; data, Luau and process kinds; git, folder and ReaPack sources; hot reload; a project's required extensions under an org's policy.
- Canvas overlays and ImGui-shaped UIarchitect-canvas: a view publishes its coordinate spaces, scripts draw layers over it with hit regions, and ReaImGui-shaped tool windows open as workspace panes.
- Remote viewsA process extension draws Dioxus views in its own process; the app shows them in workspace panes over vox, and a placeholder with the reason when the process dies.
- A2UI: agents' generated UIarchitect-a2ui: an agent shows the person a form, a list, cards or an approval as A2UI v1.0, drawn with architect-ui from a catalog that is the security boundary, kept in Loro, its buttons running Action List actions that ask before every write.
- Basesarchitect-bases: a vault's .base files as table, cards and list views with filters, sort, group-by, properties and formulas; view types extensions add; the BASES_* actions; a note's ```base fence.
- NavigatorNavigator: folders beside notes in the sidebar, a port of Notebook Navigator (GPL-3.0). A built-in extension over architect-navigator: groups, pins, images, tags, folder notes, a manual order, each folder's and tag's own list.
- SitesSites: any vault published as a static site, with working links, tags, backlinks, search and a page's contents, in architect's themes, readable on a phone. Extensions draw the blocks they claim at build time, and the architect server hosts the result.
- Capturearchitect-capture: one quick-add parser, the composer, a capture window on a system-wide shortcut, the vault inbox and processing it, capture targets extensions add, CAPTURE_* and INBOX_*.
- Editorarchitect-editor: the one door to FastTrackStudios/editor (its document model, TextEditor and CodeEditor re-exported), the language registry that drives the editor's, grammars linked into the app, [[languages]], and the syntax.* theme tokens.
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.
- Getting startedGet a dev shell up, build the workspace and run the reference feature's tests.