metal-kompanion/docs/design-local-first-architecture.md

Design Decision: Local-First Personal Store with Optional Federated Services

Decision: Kompanion adopts a two-tier architecture. A personal, local store (Akonadi-like) is the authoritative home of a user's data and operates fully offline. An optional federated layer provides encrypted backups, multi-device sync, and paid cloud conveniences (e.g., hosted search/rerank). Users can run purely local, or selectively enable cloud features.

Encryption Note: We deliberately leave the exact cryptography suite open to allow hardware/OS keychains, libsodium, AES-GCM, or XChaCha20-Poly1305. The guardrails below assume end-to-end encryption (E2EE) with keys controlled by the user.

---

1) Personal Store (Local Core) — kom.local.v1

• Runs entirely on-device; no network required.
• DB: SQLite (+ FTS/trigram for "rgrep" feel) + FAISS for vectors.
• Embeddings/Reranker: local (Ollama + optional local reranker).
• Privacy defaults: do-not-embed secrets; private-vault items are never vectorized/FTS'd; E2EE for backups/exports.
• Backup tools: backup.export_encrypted, backup.import_encrypted (E2EE blobs).

2) Federated Services (Optional) — kom.cloud.v1

• Adds encrypted sync, cloud backup, micropayment-backed hosted compute (e.g., heavy reranking), and optional hosted pgvector search.
• Server sees ciphertext plus minimal metadata; hosted search is opt-in and may store embeddings either encrypted or plaintext only by explicit consent.
• Per-namespace tenancy and isolation (RLS when using Postgres).

3) Key & Auth Model

• Users may only retain authentication/secret-store access; Kompanion handles day-to-day operations.
• Device enrollment shares/wraps keys securely (mechanism TBD; QR/device handoff).
• Key rotation and export are first-class; backups are always encrypted client-side.

4) Search Modes

• Lexical: FTS + trigram, scoped to namespace/thread/user; grep-like snippets.
• Semantic: vector ANN with local reranker by default.
• Hybrid: configurable orchestration; always respects scope and privacy flags.

5) Privacy Controls

• Sensitivity flags: metadata.sensitivity = secret|private|normal.
• secret items: E2EE only (no FTS, no embeddings).
• Server-side scope injection (namespace/user) in all handlers; default-deny posture.
• Purge policy: soft-delete + scheduled hard-delete; cascades to chunks/embeddings and remote copies.

6) Compatibility with Postgres+pgvector

• When cloud search is enabled, a hosted Postgres+pgvector instance enforces isolation via RLS and per-namespace session GUCs.
• Local SQLite store remains the source of truth unless user opts to delegate search to cloud.

---

Action List (from privacy review)

1. DB hardening (cloud path): add RLS policies; add FTS + pg_trgm; unique (namespace_id, key); partial ANN indexes per model.
2. Server enforcement: inject namespace/user via session context (GUCs); default-deny widening; rate limits.
3. Redaction pipeline: protect secrets before embedding; skip embedding/FTS for secret items.
4. Private vault mode: key-only retrieval paths for sensitive items (no index participation).
5. Backups: define E2EE export/import format; provider adapters (e.g., Google Drive) use pre-encrypted blobs.
6. Sync: event-log format (append-only); conflict rules; device enrollment + key wrapping; later CRDT if needed.
7. Purging: scheduled hard-deletes; admin "nuke namespace/user" procedure.
8. Tests: cross-tenant leakage, redaction invariants, purge/TTL, hybrid-vs-lexical, hosted-vs-local parity.

Files to Watch

• docs/db-schema.md, sql/pg/001_init.sql (cloud path)
• src/mcp/ToolSchemas.json and MCP handlers (scope + sensitivity gates)
• kom.local.v1.backup.*, kom.cloud.v1.* (new tool surfaces)