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,93 @@
+# 09 — Product Roadmap (Phase 8)
+
+Everything from discovery, split into releases and **prioritised by user value vs
+engineering effort**. The guiding sequence: **ship the redesign + dramatically better
+(deterministic) search first**, then layer **optional local AI** in value order, each tier
+reusing infrastructure the previous one built.
+
+> **Update — multi-provider platform epic.** The
+> [multi-provider + admin/settings design](multi-provider/README.md) is a **v1.x platform
+> epic** (its own 6-phase plan) that the search/AI features build on. Sequencing note: the
+> **provider abstraction, unified email model, settings, and feature-flag engine land early
+> in v1.x** (they underpin multi-user + AI gating); the AI features from this roadmap then
+> plug into that flag system. Both plans share the same flag-gated, ship-dark discipline.
+
+## Prioritisation framework
+Score each item **Value (1–5) × (6 − Effort 1–5)**, then sequence so that (a) high-value/
+low-effort ships first, (b) risky/expensive AI comes only after its infrastructure exists,
+and (c) **nothing in an early release depends on AI being enabled.**
+
+```
+ Value ▲   ★ MVP first        ● do next        ○ later
+   5 │ ★ranking ★redesign     ●NL search       ○ask-inbox
+   4 │ ★fuzzy ★chips ★summary ●semantic ●brief  ○knowledge graph
+   3 │ ★perf/indexes          ●people ●extract  ○collaboration
+   2 │                        ●categorise-tail  ○plugins ○mobile
+   1 │                                          ○multi-provider
+     └───────────────────────────────────────────────────►
+        low effort ──────────────────────────► high effort
+```
+
+---
+
+## MVP → **v1.0.0** — "The redesign + world-class deterministic search"
+Rationale: the single biggest perceived-quality jump, built mostly on **deterministic**
+tech (low risk). AI appears only as a few optional, reversible wins behind a toggle.
+- **UX v2 shell + design system + both themes** (dark-first, green ramp) — the "world-class" feel.
+- **Search core:** relevance ranking (RRF/`ts_rank`), multi-field weighted FTS, `pg_trgm`
+  fuzzy, **filter chips**, saved/recent/suggested, **"why matched"** (lexical), keyset pagination.
+- **Perf/debt:** `pg_trgm` + FTS indexes, virtualised list, code-splitting, fix EF
+  query-filter warning, language-aware FTS.
+- **AI foundation:** extended abstraction (`IAiProvider`+`IEmbeddingProvider`+facade+router),
+  Null + Ollama wired, **VRAM guard**, prompt templates.
+- **First AI wins (optional):** thread summary · follow-up detection (heuristic + AI confirm)
+  · reply suggestions.
+- **Why now:** delivers the flagship promise (fast, approachable, ranked, explainable search
+  + a premium UI) even with AI off.
+
+## v1.1 — "Assisted search & productivity"
+Rationale: build on MVP's embedding groundwork; assist without heavy compute.
+- **Natural-language search** parse (rules-first + optional LLM), shown as editable chips.
+- **People search** · **attachment (filename) search** · **search-driven bulk actions**.
+- **Inbox assistant / daily brief** · **task/calendar/reminder extraction**.
+- **Categorisation long-tail** (embedding zero-shot + confidence) · **priority prediction v1**.
+- **Why now:** the "assisted, not syntactic" search vision, plus the highest-value AI
+  productivity features — all still light on VRAM.
+
+## v1.2 — "Semantic tier"
+Rationale: introduces `pgvector` + embedding backfill; unlocks meaning-based features.
+- **Semantic search** (pgvector HNSW, hybrid RRF) · **related / find-similar**.
+- **Near-duplicate detection** · **thread summaries surfaced in results** · **conversation insights**.
+- **Relationship mapping (basics)**.
+- **Why now:** semantic recall is a headline differentiator but needs the embedding
+  infrastructure and backfill worker to be mature and VRAM-safe.
+
+## v2.0 — "Ambitious AI"
+Rationale: flagship, compute-heavy features that need a mature semantic + vision stack.
+- **Conversational "ask your inbox"** (RAG + **citations**).
+- **Entity search & facets** (amounts, orgs, dates) · **attachment OCR/content understanding** (vision, on-demand).
+- **Phishing reasoning** (LLM over flagged mail, async, explained) · **knowledge graph**.
+- **Why now:** highest wow-factor and the strongest "local private AI" story, but only
+  worthwhile once retrieval, extraction, and vision infra are proven.
+
+## v3.0 — "Platform"
+Rationale: expand beyond the individual power-user once the core is best-in-class.
+- **Collaboration / shared inbox** (assign, comment) · **automation / rules engine**
+  (a `docs/specs/feature-rules-engine.md` already exists — fold it in).
+- **Multi-account & additional providers** (IMAP/Outlook) · **plugin ecosystem** (analyzer
+  API) · **mobile app** · **multi-window / desktop shell** (Tauri) · **multi-provider AI**.
+- **Why now:** platform bets that only pay off on top of a beloved core product.
+
+---
+
+## Sequencing principles (explained)
+1. **Deterministic value before AI.** MVP's biggest wins (ranking, chips, redesign) need no
+   AI — they de-risk the release and prove the product before compute-heavy features.
+2. **Infrastructure amortised.** Embeddings introduced once (v1.1 foundations → v1.2 usage)
+   power search, dedup, related, categorisation, and RAG — spread the cost.
+3. **Value-first within a release.** Inside each version, highest value/effort ships first so
+   partial delivery is still shippable.
+4. **AI is always additive.** Every release is complete and excellent with AI disabled —
+   protecting the "works without AI" mandate and the mainstream audience.
+5. **Platform last.** Collaboration/plugins/mobile are large and only worthwhile once the
+   individual experience is genuinely best-in-class.