V3 does not vendor mail-sync, mac-sync, the messenger codebase, agents, or ML pipelines. They live outside `@atlilith/` and are consumed over HTTP or MCP. This doc is the contract list — what each peer exposes, where it runs, and how the platform reaches it.
Peers belong to their own repos and lifecycles. The platform is allowed to know their **interface**, not their **implementation**.
- **Contract:** HTTP POST `/send` with `{ to, from, subject, body_text, body_html?, in_reply_to? }`; returns `{ message_id, status }`. Idempotent via client-supplied `id`.
- **Failure mode:** if plum is offline, sends queue in mail-sync's local SQLite and drain on reconnect. Platform should retry, not error to the user.
- **Port:** `3201` (the canonical, current port — V2 INFRA.md said 3100, that was wrong)
- **DB:** writes to black `:25436``quinn_macsync` (schema `macsync.*`)
- **Used by:** `@features/messenger`, `@features/ai-engine` (the auto-respond service on black reads from `macsync.*` via LISTEN/NOTIFY)
- **Contract:** mac-sync push events into the `quinn_macsync` Postgres; consumers subscribe to `message_inserted` LISTEN/NOTIFY. Send-side is via `SendQueueAdapter` in mac-sync; the platform writes into the send queue table, mac-sync's reader picks it up and dispatches via macOS.
- **Caveat:** plum is the canonical authoring host for Swift work; apricot has a divergent older tree (see `lilith-platform.live` memory `project_macsync_send_consumer_gap`).
- **Status:** **needs reconciliation** with V2's `@features/messages` before V3 starts using messenger-side code. They may be the same code or different concerns; today neither doc is the source of truth. Decide in Phase 6 before touching either.
- **Contract:** Each agent exposes an MCP server. The platform reaches them by name through MCP routing (current pattern: features that need agent work invoke an MCP tool, never embed agent logic locally).
- **Used by:** `@features/ai-assistant` (orchestration only — picks which agent to invoke for a draft), `@features/mail-autoresponder` for tone selection, future workflows
- **Rule:** the platform never contains agent prompts or weights. It contains *which agent to call and why*.
- **Host:** **black** (V3 target). vps-0 carries an HTTP cache for the *public-information subset* of platform.api responses (provider profiles, public booking surfaces, brand info — anything the web UIs need without authentication).
- **Port:** TBD in V3 (V2 was 3030 on vps-0 + a similar listener on apricot for dev)
- **Used by:** every web UI on vps-0 (proxies through tunnel to black for authed requests; reads from local cache for public ones), every internal worker, the mobile client (`@quinn-ios`)
- **Contract:** Hono-based HTTP gateway. Per-route auth (JWT via @features/sso). Public endpoints are explicitly tagged `public: true` in the route registry and are the only ones the vps-0 cache replicates.
- **Side-by-side with V2:** V2 still has `quinn-{api,admin-api,ai-backend,ai-core,data-api,my-api,m-backend-user,newsletter-api,sso-api}.service` running on vps-0 plus a local Postgres `:5435`. They stay there. V3 stands up `platform.api` on black on its own ports (V3 picks ranges that don't collide — see `DESIGN.md §8 Phase 5.1`). Decommissioning V2 is end-state (`DESIGN.md §11`), not a Phase 5 task.
- **Host:** mix — knowledge-platform on plum (Crystal TUI heritage); model-boss on apricot at `:8210`; draft-pipeline-ts is consumed by the `quinn-ai-auto-respond.service` on black
- **Contract:** HTTP for synchronous calls (e.g. model-boss takes `{ model, messages, ... }` and returns completions); MCP for tool-shaped calls; for streaming/long-running, the platform writes a request row and an ML worker picks it up (queue pattern, currently via Postgres LISTEN/NOTIFY).
- **Rule:** ML inference never runs inside the platform. The platform contains orchestration (request routing, prompt assembly, draft tracking, retry logic) — never weights, training data, or inference code.
- **`model-boss` is the chokepoint** for LLM coordination. Other ML peers route through it for completions (`@lilith/model-boss-client` is the client SDK).
## @imajin (image generation, diffusion)
- **Location:** `~/Code/@applications/@imajin/`
- **Contract:** HTTP — `POST /generate` with prompt + style config; returns image URL in MinIO
- **Used by:** future content-generation features; not in Phase 6 scope
- **Type:** Swift iOS app, separate lifecycle. Consumes platform APIs (`platform.api`) like any other client. Not a peer in the request graph — just a downstream consumer.
| Choosing which model / agent / prompt to use for a given request | `@features/ai-engine` (platform — orchestration) |
| Tracking a draft through the human-approve workflow | `@features/messages` or `@features/mail-autoresponder` (platform) |
| Where the draft was stored, who approved it, who sent it | `platform.db` (platform DBs) |
If a new feature tempts you to bundle ML inference into the platform, push it into a peer and consume over HTTP/MCP instead. See `../DESIGN.md §3 principle 4`.
