James Maes
514f8eb15b
Sweep every README/doc for accuracy and remove fabricated or stale content: - README/CLAUDE: add the live roadmap-page link and a rule to keep the rendered page in sync with docs/ROADMAP.md; fix the stale cov alias and the already-moved-shells note. - .github/CONTRIBUTING+SECURITY: drop the fabricated nuncio.mx site link and the aspirational release/security claims; state honest pre-alpha status. - docs/RUNNING, DEVELOPING, ARCHITECTURE, BACKLOG, Home, NSQL spec, corruption notes, proto/README: correct crate count/list, service list, CLI flags, phase status, and remove claims of unshipped/removed things (IPC-as-current, hardcoded-keys, unwired engines); mark superseded api-surface-draft historical. - Remove the fabricated benchmark baked into nsql_pipeline.svg and delete the orphaned ipc_sequence.svg (depicted the removed IPC with a fake timing).
99 lines
5.2 KiB
Markdown
99 lines
5.2 KiB
Markdown
# Nuncio Architecture
|
||
|
||
> **Status (2026-07-26):** this describes the **target** architecture the project
|
||
> is being rebuilt toward, and flags where the current tree differs. It replaces
|
||
> the previous `Architecture-Specification.md` (removed — it contained fabricated
|
||
> benchmarks and claims). Authoritative plan: [`ROADMAP.md`](ROADMAP.md); decision:
|
||
> [`adr/0001-engine-first-grpc-architecture.md`](adr/0001-engine-first-grpc-architecture.md).
|
||
|
||
## Principle: the daemon is the product
|
||
|
||
`nunciod` owns everything that matters — persistent state, credentials, protocol
|
||
synchronization, filtering, and all business logic. Every user interface is a thin
|
||
client that talks to the daemon over a published API and holds no logic or data of
|
||
its own. This is the language-server / database-server model.
|
||
|
||
The prior POC inverted this: four UI shells each carried their own (fake or
|
||
throwaway) state and business logic, so nothing worked end-to-end and the shells
|
||
drifted apart. Centralizing on the daemon makes correctness and cross-client
|
||
parity structural.
|
||
|
||
## Components
|
||
|
||
### Engine libraries (composed by `nunciod`)
|
||
|
||
- **`nuncio-core`** — domain models (`Email`, `CalendarEvent`, `Contact`), the
|
||
event bus, and cross-cutting services (export, RBAC, audit, config). Note: the
|
||
`e2ee`, `ai`, and `plugin` modules are non-functional placeholders in the
|
||
current tree and are deferred until re-justified.
|
||
- **`nuncio-store`** — SQLite persistence in WAL mode, migrations, FTS search,
|
||
payload ciphers (AES-GCM / age), corruption detection & recovery, and the OS
|
||
keyring vault abstraction. Genuinely engineered; the FTS-vs-encryption,
|
||
backfill, salvage-schema, and transient-error-vs-corruption fixes tracked in
|
||
[`BACKLOG.md`](BACKLOG.md) Phase 1.B are done.
|
||
- **`nuncio-mail`** — IMAP, JMAP, and SMTP engines and MIME handling. IMAP and
|
||
SMTP are wired into the daemon's real `fetch → store → read → send` spine
|
||
(Phase 1–2); JMAP still needs a real HTTP client (roadmap M3).
|
||
- **`nuncio-cal`** — iCalendar parsing, CalDAV/CardDAV, recurrence (`rrule`), and
|
||
scheduling. The engine layer is done (real CalDAV `REPORT` transport, the TZID
|
||
fix, a `CalendarBackend` trait, `calendar_events` store CRUD); the API vertical
|
||
and recurrence wiring are roadmap M1.
|
||
- **`nuncio-contacts`** — contacts store, CardDAV sync, vCard generation. Not yet
|
||
wired into the daemon or persisted across restarts (roadmap M2).
|
||
- **`nuncio-filter`** — the NSQL declarative filter language: parser
|
||
(`sqlparser`-based), multi-pass validator, and evaluation engine. The strongest
|
||
subsystem; correctness fixes (account scoping, `ON ACCOUNT`, non-ASCII offsets,
|
||
`NOT IN`) are done. Wiring the match-and-act engine into the live sync path so a
|
||
matching rule actually fires its action is roadmap M4. See
|
||
[`NSQL-Filter-Language-Specification.md`](NSQL-Filter-Language-Specification.md).
|
||
|
||
### The daemon
|
||
|
||
- **`nunciod`** — boots the event bus, opens/recovers the store, loads filter
|
||
rules, runs background workers, and serves the gRPC API. The
|
||
`IMAP fetch → store → read → SMTP send` spine is real and works end-to-end
|
||
(Phase 1–2). The remaining gaps are wiring the filter engine's actions into
|
||
that live sync path (roadmap M4) and incremental — rather than full-historical
|
||
— sync (roadmap M5).
|
||
|
||
### The published API
|
||
|
||
- A versioned **gRPC** service defined by Protocol Buffers in `proto/nuncio/v1/`
|
||
(delivered in Phase 1), served over **loopback TCP (`127.0.0.1:9420`)** with a
|
||
**bearer-token handshake** — the token minted into the OS keyring on first run
|
||
and sent as gRPC metadata.
|
||
- **Unary RPCs** for commands and queries; **server-streaming RPCs** for push
|
||
(new mail, sync progress, events). gRPC's multiplexing removes the
|
||
response/notification demux race that the old hand-rolled IPC suffered from.
|
||
- The `.proto` files are the versioned contract every client codegens against.
|
||
|
||
> **Removed:** the daemon previously also ran a hand-rolled length-prefixed
|
||
> JSON-RPC 2.0 transport on `127.0.0.1:9422`, which had a response/notification
|
||
> interleaving bug. It has been deleted — the daemon serves gRPC only.
|
||
|
||
### Clients
|
||
|
||
- **`nuncio-cli`** stays in-repo as the reference gRPC client and E2E driver.
|
||
- **Native GUIs** (`nuncio-gui-macos` in Swift, `nuncio-gui-windows` in WinUI/C#),
|
||
a **Rust TUI** (`nuncio-tui`), and an **MCP↔gRPC bridge** (`nuncio-mcp`) become
|
||
separate repositories consuming the published API (Phase 5). Linux is supported
|
||
at the daemon + CLI level; a native Linux GUI is deferred.
|
||
|
||
## Data & security model
|
||
|
||
- **Single local SQLite database per profile** (e.g. `~/.nuncio/`), WAL mode,
|
||
single-writer through the daemon.
|
||
- **Credentials and keys belong in the OS keyring.** Fixed in Phase 0.E:
|
||
production code reads/writes real keys via `OsKeyring` (Windows Credential
|
||
Manager / Keychain / Secret Service); only test code uses `MockKeyring`.
|
||
- **Full-text search** via SQLite FTS5 (trigram). The indexing-vs-encryption
|
||
strategy was corrected in Phase 1.B.
|
||
- **HTML email** must render sandboxed (`<iframe sandbox>`, JS disabled, strict
|
||
CSP) in GUI clients.
|
||
|
||
## Diagram
|
||
|
||
A current, accurate topology diagram covering the gRPC layer has not yet been
|
||
added. The previous `architecture.png` depicted the superseded socket/4-shell
|
||
model and was removed.
|