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,50 @@
+# 10 — Git Workflow (Part 11)
+
+Extends [../../WORKFLOW.md](../../WORKFLOW.md) for multi-phase, multi-provider work. The
+core idea: **feature flags decouple *merging* from *activating*, which makes every
+integration safe to land and trivial to roll back.**
+
+## Branching per phase
+| Phase | Milestone | Branches |
+|-------|-----------|----------|
+| 1 Provider abstraction + Google | `v1.x` | `epic/provider-platform` → `feature/email-provider-interface` · `feature/gmail-adapter` · `feature/oauth-login-users` |
+| 2 Microsoft | `v1.x` | `feature/outlook-provider` · `feature/microsoft-oauth` |
+| 3 Unified model + sync | `v1.x` | `feature/normalised-email-model` · `feature/sync-orchestrator` · `feature/data-migration` |
+| 4 Settings | `v1.x` | `feature/settings-store` · `feature/feature-flags-engine` |
+| 5 Admin | `v1.x` | `feature/admin-api` · `feature/admin-ui` · `feature/audit-log` |
+| 6 AI layer | `v1.x` | `feature/ai-abstraction-ext` · `feature/ai-analyzers` · `feature/ai-flag-gating` |
+- `feature/* → develop` (squash), `develop → main` (merge commit) — as established. Epics are
+  tracked by milestone/label; features integrate continuously (no long epic branch).
+
+## PR structure per provider integration
+Each provider is a self-contained PR set that lands **dark**:
+1. **Adapter PR** — `IEmailProvider` impl + normaliser + unit tests (mocked provider).
+2. **Auth PR** — OAuth login/link for that provider.
+3. **Enablement PR** — register in `ProviderFactory` + seed `provider.<x>` flag **OFF**.
+4. **Activation** — flip the flag on in staging → verify end-to-end → roll out in prod.
+- **PR checklist adds:** provider behind a flag (off by default) · normaliser tests · token
+  encryption verified · no Domain leakage · docs updated.
+
+## Feature flags prevent breaking changes
+- Merge = code present but **inert** until its flag is on. So half-finished providers/AI can
+  live on `main` safely; CI stays green; no long-lived divergence.
+- AI ships behind `ai.*`; providers behind `provider.*`; risky changes behind their own flag.
+
+## Rollback strategy (per provider / per feature)
+| Level | Action | Speed |
+|-------|--------|-------|
+| **Flag** (first resort) | Admin flips `provider.<x>` / `ai.<x>` **off** | **Instant, no deploy** — feature disappears, existing data untouched |
+| **Deploy** | Redeploy the previous **tag** (`vX.Y.Z-1`) | Minutes (pipeline) |
+| **Revert** | `git revert` the PR → PR → merge → deploy | Minutes–hours |
+| **Data** | Provider accounts are isolated; disabling a provider **pauses** its sync — no destructive change to migrate back | Safe by design |
+- Because providers are isolated and flag-gated, a bad integration **never blocks the others**
+  and never requires a risky data rollback.
+
+## Release milestones
+- Cut a tag when a phase reaches its exit criteria (`deploy-prod.yml` fires on `v*`).
+- Suggested: `v1.1` provider platform + Google · `v1.2` +Outlook · `v1.3` unified sync ·
+  `v1.4` settings+admin · `v1.5` AI layer — folded into the blueprint roadmap ([../09](../09-roadmap.md)).
+
+## Docs alongside code
+Every feature PR updates the relevant `multi-provider/*` doc + `CHANGELOG.md`; on approval the
+design docs graduate into living `docs/` references (provider system, settings, admin, security).