`docs/ARCHITECTURE.md`

61 lines
# Architecture

See `SPEC.md` for the source-of-truth diagrams. This file holds the runtime view (what's actually deployed today vs. what's planned).

## Today (Phase 0 / scaffold)

```
                  Browser
                     │
                     │ HTTP
                     ▼
         ┌──────────────────────┐
         │  Express server :9931 │
         │  (server.js)         │
         └─────────┬────────────┘
                   │
       ┌───────────┼─────────────────┐
       ▼           ▼                 ▼
   routes/auth  routes/connectors  routes/purchases
       │           │                 │
       │           ▼                 ▼
       │     lib/gmail-fetcher    lib/db (pg.Pool)
       │     lib/google-oauth         │
       │           │                  ▼
       └───────────┴───────────►  PostgreSQL abrams_os
                                   ├ user_account
                                   ├ consent_grant
                                   ├ connector_account (refresh_token AES-256-GCM)
                                   ├ source_message (jsonb)
                                   ├ document
                                   ├ purchase
                                   ├ purchase_item
                                   └ audit_log
```

External:
- Google OAuth → consent → callback → encrypted refresh token at rest
- Local Ollama qwen3:14b on Mac1 (`http://192.168.1.133:11434`) — receipt extractor tier-2 fallback
- pm2 supervisor (Mac2) → autorestart + log rotation

## Future (the SPEC.md target)

The scaffold above grows into the full diagram in `SPEC.md`:
- **Connector Gateway** layer fronting all per-user connector_accounts (Gmail, Outlook, Calendar, Plaid, Stripe, PayPal, MCP)
- **Ingestion Pipeline** workers (OCR, ER, Recall Matcher, Coverage Analyst)
- **Rights Rules Corpus** as a versioned read-side
- **Case & Claims Service** with the Claim Strategist + Letter Composer
- **Approval Policy Engine** as a blocking checkpoint for every Action Agent call
- **Audit Log Service** as an append-only ledger (eventually a Merkle-chained store)
- **Document / Letter / Messaging Service** for outbound

Migration path is incremental: each milestone in `ROADMAP.md` adds one column of the target diagram.

## Key invariants

1. **No external action without an audit_log row** referencing the consent_grant that authorized it.
2. **Refresh tokens never leave PG in plaintext.**
3. **Rights-rule snapshots are immutable** — corrections create new versions, never overwrite.
4. **Consumer and medical data are separable** — medical_consent_grant is a hard precondition for any medical_* table read.
5. **No marketplace scraping.** Consumer data comes from inbox + user-authorized exports + official APIs only.