docs: discovery blueprint + multi-provider design (#8)

2026-07-01 19:59:53 +02:00
parent 9ee5d757f5
commit 4ce2df0a2b
27 changed files with 2032 additions and 0 deletions
@@ -0,0 +1,37 @@
+# 11 — Risk Assessment & Future Opportunities
+
+## Risk assessment
+Likelihood (L) / Impact (I): H/M/L.
+
+| # | Risk | L | I | Mitigation |
+|---|------|---|---|------------|
+| R1 | **Full UI redesign destabilises a working app** | M | H | Strangler migration behind `ui.v2` flag, screen-by-screen; API untouched; ship via the proven `develop→staging` pipeline; keep old screens until parity verified |
+| R2 | **VRAM (10 GB) can't hold desired models concurrently** | M | M | 7–8B sweet-spot (not 14B); embeddings hot + LLM warm + vision on-demand; VRAM guard serialises heavy jobs; small models for high-volume paths |
+| R3 | **Local AI quality/latency disappoints** | M | M | Traditional-first (AI only where it clearly wins); AI advisory + optional; stream responses; cache; model routing lets us swap models without code change |
+| R4 | **Prompt injection via email content** | M | H | Treat all model output as advisory; **AI never triggers actions**; human/rule confirms; sanitise; SSRF/egress guards; local-only by default |
+| R5 | **Gmail API quota / sync scale at 100k+ mailboxes** | M | M | Batching + Polly backoff (exists); incremental sync; background enrichment queue with backpressure; keyset pagination |
+| R6 | **Semantic infra (pgvector/embeddings) ops complexity** | M | M | Introduce once (v1.2), backfill worker VRAM-aware + resumable; HNSW tuning; feature hides if unavailable |
+| R7 | **Search relevance regressions vs today** | L | M | Lexical hits never lose to fuzzy noise (weighting); benchmark suite as a release gate; keep date-sort as a user option |
+| R8 | **Scope creep — trying to beat everyone at once** | H | M | Roadmap value/effort discipline; MVP is deterministic + small AI; platform features deferred to v3 |
+| R9 | **Solo-dev bandwidth / single-machine staging** | H | M | Small shippable features; CI/CD automation already reduces toil; staging owned by automation (don't hand-run it — see memory note) |
+| R10 | **Mainstream-vs-power tension dilutes the UX** | M | M | Progressive disclosure: simple default, power revealed on demand; pointer-first with keyboard as accelerator |
+| R11 | **Privacy promise broken by a cloud provider option** | L | H | Local default; cloud is explicit per-feature opt-in with egress logging + consent; never silent |
+| R12 | **pgvector image / Ollama container adds deploy friction** | L | L | Optional Compose profiles (`ai`); AI-off deployments omit them entirely |
+
+## Future opportunities (beyond v3.0)
+- **Additional mail backends** — IMAP/JMAP, Outlook/Graph — become a true multi-provider client.
+- **On-device personalisation** — light fine-tuning / user-preference adapters for priority & tone.
+- **Calendar & tasks integration** — close the loop from extraction to action.
+- **Voice** — dictate replies, "ask your inbox" by voice (local Whisper).
+- **Plugin marketplace** — third-party analyzers/widgets on the analyzer + command-palette APIs.
+- **Team knowledge base** — shared, permissioned knowledge graph across a team inbox.
+- **Native desktop shell** (Tauri) for OS integration, global hotkey, tray, true multi-window.
+- **Smart compose surfaces** — templates that learn, snippet library, per-recipient tone memory.
+- **Local model upgrades** — swap in newer/quantised models as they ship (router makes it a config change).
+
+## Recommendation
+The foundation is strong and the wedge is real. **Proceed with v1.0.0 (redesign +
+deterministic search + AI foundation)** — it's high-value, low-risk, and independent of AI
+being enabled — then layer local AI in value order. The biggest watch-items are **R1
+(migration discipline)** and **R8 (scope)**; both are controlled by the strangler approach
+and the value/effort-sequenced roadmap.