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,70 @@
+# Executive Summary — InboxIntel Discovery Blueprint
+
+**Ambition:** become one of the best **email search and management** experiences available
+— fast, scalable, secure, intuitive — with **AI used only where it clearly beats
+traditional approaches**, running **locally and privately**, and **never as a hard
+dependency**.
+
+## The opportunity (the wedge)
+The market has split in two, and both halves leave a gap:
+- **AI, but cloud** (Gmail/Gemini, Outlook/Copilot, Shortwave, Spark) — useful, but your
+  mail is processed off-device.
+- **Private, but little/no AI** (Proton, Thunderbird, Fastmail).
+
+**No mainstream product owns "genuinely useful AI that runs on your own machine."**
+InboxIntel can — and it already has the seams for it. Combined with three more openings —
+**approachable power-search as the home screen**, **explainability** ("why this matched /
+was categorised"), and **fast *and* friendly** (Superhuman is fast-but-intimidating; casual
+apps are friendly-but-slow) — this is a defensible, differentiated position.
+
+> **Positioning:** *Make search the fastest way to think about your inbox, with AI that runs
+> on your own machine and always explains itself. Powerful for pros, simple for anyone.*
+
+## Current state — verdict: extend, don't rewrite
+A clean, secure, well-tested .NET 8 / React foundation with **real Postgres full-text
+search** and **an AI provider abstraction already in place** (`NullAiProvider` /
+`OllamaProvider` / `OpenAiProvider`). The gaps are exactly where the product wants to win:
+relevance-ranked multi-mode search, a richer AI contract (embeddings/extraction),
+conversation intelligence, and a modern approachable UX. **None require a rewrite.**
+
+## Design direction (from the interview)
+Notion/Arc-**professional**, "anyone can pick it up": **pointer-first & discoverable**
+(palette/shortcuts as accelerators), **balanced density**, **dark-first** (genuine light
+too), **subtle motion**, **green `#3ba31f`** accent, clean rounded line icons, **fully
+responsive** desktop→mobile. The pivotal decision — *discoverable-first over keyboard-first*
+— reframes search from "a syntax you learn" into "an inviting, assisted experience."
+
+## Search & AI in a nutshell
+- **Search:** a 4-layer engine — Structured → **Lexical+Ranking** (always on) → Semantic
+  (pgvector) → AI-assisted (NL / ask-your-inbox / explanations) — with **hybrid RRF ranking**
+  replacing today's date-only sort. Degrades gracefully with AI off.
+- **AI:** extend the abstraction to embeddings + structured output behind a task facade with
+  **config-driven model routing**; on the **RTX 3080 (10 GB)**, **Qwen2.5-7B** (warm) +
+  **nomic-embed-text** (hot) do most jobs, vision on-demand. Traditional-first everywhere;
+  every AI feature has a non-AI fallback.
+
+## Roadmap shape
+**v1.0** redesign + world-class *deterministic* search + AI foundation → **v1.1** assisted
+search & productivity → **v1.2** semantic tier → **v2.0** ambitious AI (RAG, vision, graph)
+→ **v3.0** platform (collaboration, rules, plugins, mobile). Sequenced so **deterministic
+value ships before AI**, infrastructure is amortised, and **every release is complete with
+AI disabled.**
+
+## Key risks
+Migration of a full redesign (**mitigated by strangler + `ui.v2` flag**), VRAM limits
+(**7–8B sweet spot + load policy**), prompt injection (**AI advisory-only, never acts**), and
+scope creep (**value/effort-sequenced roadmap**). See [11](11-risks-and-future.md).
+
+## Recommendation
+**Proceed to v1.0.0** — the redesign, ranked/assisted search, and AI foundation. It's the
+biggest quality jump, it's low-risk and deterministic, and it stands entirely on its own
+without AI. Then layer local, private, explainable AI in value order.
+
+---
+### Read the full blueprint
+[01 Architecture](01-architecture-review.md) · [02 Competitors](02-competitor-analysis.md) ·
+[03 Users](03-user-research.md) · [04 UX + Design System](04-ux-redesign-and-design-system.md) ·
+[05 Search](05-search-redesign.md) · [06 AI Strategy](06-ai-strategy.md) ·
+[07 AI Features](07-ai-feature-catalogue.md) · [08 Architecture](08-technical-architecture.md) ·
+[09 Roadmap](09-roadmap.md) · [10 Git Plan](10-git-plan.md) ·
+[11 Risks & Future](11-risks-and-future.md) · [Design Brief](00-design-brief.md)