Inboxintel/docs/discovery/multi-provider/12-migration-guide.md

12 — Migration Guide (Part 10)

Moving the current single-account Gmail app to the multi-provider, multi-user model — additive and reversible, no destructive step. Executed as ordered EF Core migrations + idempotent backfills, behind a short maintenance window.

Principles

• Additive first: create new tables/columns before moving data; keep old columns until parity is verified.
• Idempotent backfills: safe to re-run; keyed on stable ids.
• Flag-gated cutover: the new sign-in/model activates behind flags; the old path stays until removed.
• Reversible: each step has a documented rollback; no data is deleted during migration.

Step-by-step

1. Schema (additive migration)
   • Create users, accounts, provider_tokens, sessions, user_settings, system_settings, feature_flags, audit_logs.
   • Add account_id, user_id (nullable) to the current email/thread tables; widen search_vector; add nullable embedding vector(768) + pgvector extension.
2. Identity backfill
   • For the existing operator/user, create a users row; mark the first user = Admin.
   • Create one Google account per existing identity (is_login_identity=true); move current encrypted Gmail tokens → provider_tokens.
3. Email backfill
   • Set account_id/user_id on all existing Email/thread rows to the default Google account.
   • Regenerate the widened search_vector; leave embedding null (backfilled later by the AI phase).
   • Enforce the new unique keys (account_id, provider_message_id) / (account_id, provider_thread_id).
4. Config seed
   • Seed feature_flags: provider.google=on, provider.microsoft=off, provider.imap=off, ai.enabled = derived from the current Ai:Mode (Disabled→off), ai.*=off, maintenance.*=off.
   • Create system_settings singleton; create user_settings from any existing per-user prefs (else defaults).
5. Cutover
   • Enable the new OAuth-as-login + unified sync behind their flags; verify on staging first (the pipeline we built), then production via a tagged release.
6. Cleanup (later, separate migration)
   • Once parity is confirmed in production, drop obsolete columns/paths. Not part of the cutover.

Verification checklist

• Existing user signs in via Google → lands on their mail unchanged.
• Email counts match pre/post; search returns identical results for sample queries.
• Tokens decrypt and refresh; sync resumes from the correct cursor.
• No cross-user rows visible (isolation test).

Rollback

• Pre-cutover: additive changes are inert → simply don't flip the flags; drop new tables if aborting.
• Post-cutover issue: flip flags off / redeploy previous tag; old columns still present → the legacy path still works. No data was deleted, so no data rollback is needed.

Provider-app prerequisites (operator setup)

• Google: OAuth client (existing) + redirect /(…)/signin/google; scopes gmail.readonly gmail.modify.
• Microsoft: register an Entra app; redirect /(…)/signin/microsoft; scopes Mail.Read Mail.ReadWrite offline_access; admin consent if required.
• IMAP (future): per-account host/credentials; validated against the SSRF allowlist.
• Because providers are flag-gated, an unconfigured provider is simply hidden — configure, then enable.