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,57 @@
+# 09 — Implementation Plan (Part 9)
+
+Six phases (from the brief), each **shippable behind feature flags** so `main`/staging never
+break and providers activate only when ready. Follows the established
+[../../WORKFLOW.md](../../WORKFLOW.md) pipeline (PR → checks → staging → tag→prod).
+
+## Phase 1 — Provider abstraction + Google login refactor
+- **Goal:** introduce the seam and move the *existing* Gmail behaviour behind it, with
+  OAuth-as-login and the multi-user identity foundation.
+- **Deliverables:** `IEmailProvider` + `ProviderFactory`; **`GmailProvider`** adapter wrapping
+  today's Gmail code; `users` / `accounts` / `provider_tokens` / `sessions` tables;
+  OAuth-as-login for Google; first-user→Admin bootstrap.
+- **Flags:** `provider.google` (on). **Exit:** existing Gmail users function unchanged through
+  the new abstraction; sign-in creates a `user`+`account`; all tests green.
+
+## Phase 2 — Microsoft Outlook integration
+- **Goal:** prove the abstraction with a second provider.
+- **Deliverables:** **`OutlookProvider`** (Microsoft Graph, delta query); Microsoft OAuth login
+  + link-mode; scope config; normaliser mappings.
+- **Flags:** `provider.microsoft` (**off** until verified, then rollout). **Exit:** a user can
+  link an Outlook mailbox; it syncs and searches alongside Gmail; no core changes needed.
+
+## Phase 3 — Unified email model + sync engine
+- **Goal:** formalise the normalised store and provider-agnostic sync.
+- **Deliverables:** normalised `email_messages`/`email_threads` (widened `search_vector`,
+  nullable `embedding`); **`ISyncOrchestrator`** + `AccountSyncWorker` (per-account cursors,
+  idempotent upserts, incremental); **data migration** of existing Gmail rows → default account.
+- **Flags:** none user-facing; migration behind a maintenance window. **Exit:** all providers
+  sync through one orchestrator into one store; cross-account search works.
+
+## Phase 4 — Settings system
+- **Goal:** user + system settings + the flag engine.
+- **Deliverables:** `user_settings`, `system_settings`, **`feature_flags`** + `IFeatureFlags`/
+  `IAiGate` (cached, fail-closed); settings UI; maintenance-mode middleware.
+- **Flags:** self-hosting (the engine that hosts the rest). **Exit:** users edit prefs; admins
+  can flip flags; AI gate resolves the AND-chain.
+
+## Phase 5 — Admin panel + feature flags
+- **Goal:** the Admin surface + RBAC + audit.
+- **Deliverables:** Admin API (policy-gated) + UI (Users/Flags/AI/Providers/System/Monitoring/
+  Audit); `audit_logs`; role management; basic monitoring.
+- **Flags:** admin nav shown by role. **Exit:** an Admin can manage users/flags/providers,
+  every action audited; step-up + rate-limit enforced.
+
+## Phase 6 — AI integration layer
+- **Goal:** wire optional AI behind the gate.
+- **Deliverables:** extend `IAiProvider` (+`CompleteStructuredAsync`, `IEmbeddingProvider`);
+  `IInboxAi` facade + model router + VRAM guard; analyzer pipeline; first AI features
+  (summaries, reply, follow-up-confirm) each **flag-gated + fallback**.
+- **Flags:** `ai.enabled` + `ai.<feature>` (rollout). **Exit:** AI features work when enabled,
+  **vanish/fallback** when off; core unaffected; Ollama health in admin.
+
+## Sequencing notes
+- Phases 1–3 are the platform spine; 4–5 the control plane; 6 the optional intelligence.
+- **Nothing activates on merge** — flags gate everything, so partial phases are safe on `develop`/`main`.
+- Aligns with the blueprint roadmap ([../09](../09-roadmap.md)): this multi-provider work is a
+  **v1.x platform epic** that the search/AI features then build on.