The application is the composition root. src/main.rs loads paths, settings and
design tokens and passes them, with the SSH/local transports and the vault, to
src/bootstrap.rs, which installs services in one order shared with the GUI
tests and registers independent workspace features. The vault adapter is passed
as a VaultAccess port; its installed feature handle owns settings observation
and is retained by the app. The dependency map is generated from
Cargo metadata; cargo xtask architecture enforces its declared layers and
rejects runtime GUI dependencies below the UI layer. Service crates sit beside
the UI layer: they own GPUI entities and background work but no views, so they
depend on GPUI alone, never on the component library, UI or features. The
storage and security boundaries records protections,
regression evidence and residual constraints.
The architecture guardrails also measure existing
debt inside crates and prohibit its growth through an exact source inventory.
| Layer | May depend on | GUI | Notes |
|---|---|---|---|
| foundation | foundation | none | Foundation |
| domain | domain, foundation | none | Domain |
| adapter | domain, foundation | none | Adapters |
| service | service, domain, foundation | GPUI only | Services |
| ui | service, ui, domain, foundation | yes | UI |
| feature | service, ui, domain, foundation | yes | Features |
| app | everything but tooling | yes | App and tooling |
| tooling | everything but app and tooling | — | App and tooling |
Features never depend on each other; they meet in the workspace's seams (items, panels, actions, the session factory). Accepted decisions and the alternatives they rejected are recorded in docs/adr.
Each layer's notes describe the behaviour and boundaries of its crates; the dependency map lists every crate with its layer, internal dependencies and purpose.
A self-hosted Nocterm server keeps what an account owns (saved servers, vault passwords), can
carry an SSH route and runs the account's agents. These crates carry it:
nocterm-hubs-model (domain: addresses, trust rules, the [hubs] settings, the ports),
nocterm-hub-io (adapter: the only crate that speaks the hub protocol, which lives in a
separate contract repository; it keeps device
credentials in private files), nocterm-hubs (service: known hubs, their status, sign-in),
nocterm-hubs-ui (feature: the sign-in dialog, the Servers settings page and the sign-in
commands), nocterm-hub-agents-model (domain: agents, providers, agent servers and their
ports) and nocterm-hub-agents (service: the agents and agent servers of each tracked hub, and
Agent access of a saved server). A hub agent's chat is an ordinary agent chat: nocterm-hub-io
implements nocterm_ai::AgentConnector over the hub's chat service, so the agent panel and the
transcript are the same as for a local agent, and a hub ChatRepository lists the hub's chats
beside the local history of a hub window
(ADR 0148). A hub can also
be the first step of an SSH route: the transport asks the RelayDialer port that
nocterm-hub-io implements for a stream
(ADR 0100). A window shows one environment, this
computer or the account of one hub: the application builds one in-memory mirror of the
account's connections, its vault and the terminal credentials per hub and composes each window
from its own sources (ADR 0104). User guide:
hubs.
The window shell hosts contributions: panels and status bar widgets. The shell's own functions are core contributions; every other contribution belongs to a system plugin that its crate declares and that is compiled into the application. One checked catalog lists them with their placement hints (ADR 0082), and the window draws the status bar and arranges its panel groups from a layout resolved against that catalog (ADR 0083).
User plugins are the second tier: files the user installs, part of every build
(ADR 0161). A run loads them only when [plugins] user_plugins is set, and never in
--safe-mode; one gate in the application covers every load path, and the API surface is
checked against the latest release (ADR 0093;
author documents in plugins).
Add a new Item for another kind of tab, a Panel for another sidebar section or a registered action for a command. Observe the terminal model or session contract for integrations. Add another Transport implementation to support another kind of session. Theme changes belong in the token source or its user override. IDE features, collaboration, Vim mode and an extension runtime remain future consumers of these boundaries.
The workspace seams are described in the UI layer; the agent's layers in the service layer. References and the dependency map are generated: see generated documentation.