> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fau.run/developer/llms.txt
> Use this file to discover all available pages before exploring further.

# Product architecture (non-normative)

> How the Mac node vision maps onto this monorepo — not part of protocol fau/1.

**Status:** non-normative product sketch. It is **not** part of protocol `fau/1`.
Wire contracts stay in [Protocol overview](https://docs.fau.run/developer/protocol/overview.md) and the
[Wire specification](https://docs.fau.run/developer/protocol/spec.md). Do not treat boxes here as MUST/SHOULD.

## Custody boundary

The **Mac Node** is where personal data is decrypted, classified, indexed, and
policy-gated. Assistants reach it only through the **Relay** request/response path;
the phone exchanges **permission** and **preference** state with the node. That left
side of the vision (Assistants ↔ Relay ↔ Node + phone) is the protocol surface.
Everything else in the diagram is **node-local** product scaffolding inside this
monorepo (`node/`), not a reason to split into a new platform repo.

## Vision → code seams

| Vision box | Scaffold as | Today |
| - | - | - |
| Google / Apple / Internet | Installable `Channel` plugins under node custody | `channels/mail/`, `channels/imessage/` (+ contacts/calendar/reminders/notes/photos/voice\_memos) |
| Raw Big Data | Corpus items in the sealed store | `Message` + `messages` (+ `source` / `external_id`) |
| Pre-processing | Ingest pipeline | Channel `ingest` → classify → indexers.maintain; **images** → OCR/vision text (bytes discarded) |
| Classes | `Classifier` Protocol + registry (use case → backend) | Default **jev** (falls back to rules); **rules** alternate |
| Indexes | `Indexer` Protocol + registry; each backend owns artifacts | Default **jev** (+ **fts** maintained); ask vs structured use cases |
| Mac Node | Runtime + gateway | `NodeRuntime` / `Gateway` |
| RAG | Grant-filtered retriever + answer engine | `retrieve(use_case=…)` ∩ grant ∩ class — **not** open RAG |
| Relay / Assistants | Protocol | Leave alone |
| iPhone perm / pref | Approvals + preferences sidecar | Approvals live; prefs stub |
| Computer Use / OS | `Actuator` port | Drafts / send today; richer actuators later |
| Vault / Prefs / Procedures / History | Sidecar modules | Vault = Keychain/secrets; others stub |
| Verifiers / Extensions | Checks + tool registry | `engine/checks.py` + `server/tools.py` |

Classifier/indexer backends live under `FAU_HOME/artifacts/{classifiers,indexers}/<name>/`.
Jev is an implementation detail behind the Protocol — swap with `config.classify` /
`config.index` without a protocol bump.

**Channels** are installable plugins (`channels/` in this monorepo, entry point group
`fedagent.channels`) — outside the kernel *package*, still inside the Mac Node
trust boundary.

## Suggested build order

```text theme={null}
Doc boundary + ports
  → Channel plugins (mail + Apple + Google) with LocalIngestChannel
  → channel_cursors + incremental iMessage (imsg)
  → Google OAuth (dashboard) + Drive image ingest pipeline
  → Photos originals loader → image pipeline
  → Source-aware retrieve + classifier source priors
  → EventKit helper (fau-apple-helper) + install.sh
  → Grant × source + dashboard channel controls + channels doctor/smoke
  → Local index / classifier quality (ongoing)
  → (much later) Computer Use actuator
```

## Explicitly later

* Full Google / Apple ecosystem connectors
* Computer Use over Safari / Terminal / third-party apps
* Verifiers / Agents / Extensions as a plugin marketplace
* New repo or splitting `fedagent` into many packages
* Protocol bump for channel types

## Related

* [Extend the codebase](https://docs.fau.run/developer/developers/extend.md)
* [Node](https://docs.fau.run/developer/protocol/node.md) — normative runtime surface
* [Concepts](https://docs.fau.run/developer/concepts.md) — custody invariants


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.