# Architecture Overview

## Current Architecture

A nine-crate Rust workspace. The operator selects one direct API route or one explicitly
configured local route for execution. Only `nh-routes::RouteResolver` can mint a
`ResolvedRoute`; it carries the trusted endpoint, wire protocol, model ID, limits, modality,
thinking dialect, and catalog price data. Local routes are OpenAI-compatible and loopback-only;
they are excluded from cheapest-capable advice and cost anchors. The schema can parse delegate
routes, but no delegate execution backend ships yet.
Loopback describes the endpoint, not where that server performs inference. Local-route billing
and execution location are not inferred from the address.

## Main Components

- `nh-cli`: command parsing and the `setup`, `init`, `key`, `run`, `chat`, `doctor`, `resume`, `why`,
  `profile`, `catalog`, `model`, `tui`, `fleet`, and loopback `mcp serve` surfaces.
- `nh-tui`: ratatui frontend, with terminal lifecycle and worker ownership extracted into
  dedicated modules. Its timeline is view/inspect only; snapshot restore is not implemented.
- `nh-core`: OpenAI/Anthropic wire clients, turn loop, context compaction, receipts, the
  shared credentialed-connection boundary, and contained runtime paths.
- `nh-routes`: trusted catalog parsing, non-forgeable routes, profiles, capability checks,
  price calculation, and cheapest-capable advice.
- `nh-law`: layered constitution and policy loading. Repository inputs are symlink-rejected,
  contained, and size-bounded.
- `nh-tools`: bounded read/edit/exec tools plus the outbound MCP client. Shell execution
  requires explicit approval and receives a minimal environment.
- `nh-vault`: OS-native storage, exact-origin credential authorization, zeroizing secret
  ownership, and output redaction.
- `nh-fleet`: bounded task validation, worker ownership, append-only JSONL ledger, locking,
  budgets, escalation, and idempotent resume.
- `nh-mcp`: stateless, bearer-guarded, loopback-only preview server with bounded request and
  Fleet concurrency limits.

## Internal Responsibility Boundaries

For a task-oriented route through the enforcement points, use the
[audit map](AUDIT_MAP.md).

Crate roots expose the existing public API. Most retain only top-level orchestration or a small
shared import boundary, and production responsibilities live in named modules. `nh-tools` and
`nh-vault` are stated exceptions, described below:

- `nh-cli`: one command module per user-facing command; `cmd_run::{config,meter}` isolate trusted
  configuration assembly and receipt projection, chat startup is isolated from its REPL, and
  large command test suites live beside, but outside, their production modules.
- `nh-tui`: `input` owns event reduction while `input::commands` owns slash commands; `render`
  owns frame components while `render::transcript` owns projection and wrapping; `session`,
  `state`, `terminal`, `timeline`, and `worker` each retain one lifecycle concern.
- `nh-core`: `agent`, `credential`, `receipt`, `runtime_path`, `session_ledger`, and `wire`.
  `agent::context` owns cache-safe prefix sealing, estimation, and compaction, and
  `agent::tool_repair` owns tool-argument parsing and repair. `session_ledger` owns crash-safe,
  append-only ledgers for interactive chat and TUI sessions. The wire facade owns shared types and
  route-to-client construction; `wire::{http,openai,anthropic}` isolate common HTTP safety limits
  and provider-specific encoding.
- `nh-routes`: `pricing`, `profiles`, `resolver`, and `route`. `ResolvedRoute` is defined inside
  `resolver`, keeping its private construction boundary colocated with `RouteResolver`;
  `resolver::catalog` owns untrusted TOML parsing and validation.
- `nh-law`: `load` for layered parsing/compilation, `matcher` for pure matching, and `model` for
  policy types and read-only views.
- `nh-tools`: `edit` for indentation-flexible match location, `search` for the glob and grep
  tools, `file_publication` for staging, no-clobber creation and edit conflict checks,
  `exec` for process execution, and `mcp::{adapter,client,config}` for outbound MCP;
  `mcp::client::oauth` owns token lifetime and refresh state; `mcp::client::response` validates
  correlated JSON and bounded SSE replies. The crate root is an exception to
  the rule above: it holds the read, write and edit tool orchestration together with the shared
  workspace containment resolver and the creation guard. Publication helpers have one
  implementation in their named module; the extraction does not add OS isolation.
- `nh-fleet`: `engine` owns workers and durable I/O, `scheduler` owns task state transitions,
  and `ledger`, `model`, and `prepare` own persistence, public types, and validated setup; the
  crate root owns run/resume orchestration.
- `nh-mcp`: `protocol`, `route_tools`, `receipts`, `fleet_tools`, and `response`; `request`
  validates the modern envelope and matching transport headers before dispatch. The crate root
  owns authenticated loopback transport and shutdown.
- `nh-vault`: one cohesive production module for the OS key store, secret ownership, audience
  checks, and scrubber; its test suite is isolated from production code.

## Data Flow

1. The CLI loads bundled/user/repository policy. Repository policy may only tighten trust.
2. A trusted catalog is accepted only when it matches the bundled catalog or an exact
   operator-reviewed user-global copy.
3. The operator's route is resolved. The shared credential boundary validates its exact
   origin before materializing only that route's key.
4. `nh-core` sends the stable constitution plus dynamic conversation data to the selected
   provider. Read, edit, shell, and MCP tools pass through policy and approval boundaries.
5. Provider-reported usage is validated and written to a local typed receipt. Fleet adds a
   locked append-only run ledger. Required-receipt failure cannot be reported as success.

## Deployment Shape

`nh` is a local CLI, not a hosted multi-user service. Windows releases include a portable
executable and ZIP with checksums. Source installation remains available. The WinGet
[package submission](https://github.com/microsoft/winget-pkgs/pull/438174) is awaiting catalog
approval and is not available through WinGet yet.
Version 0.2.2 adds an in-terminal setup guide and DeepSeek Flash image input.
Windows is supported. macOS is in testing. Linux builds from source and is not yet verified.
Required CI covers Windows, macOS, supply chain, and public-tree/secret checks.

There is no OS-level sandbox. Containment is policy-level: workspace path checks,
protected-file holds, exact-origin credential audiences, minimal child environments, explicit
shell approval, time/output bounds, and best-effort process-tree termination with explicit
incomplete-cleanup reporting. Cancellation blocks new tool actions once observed, but does not
undo completed changes or immediately abort an in-flight provider request. The
MCP server cannot bind outside `127.0.0.1` and is not a public network service.