Migration Plan Mongo to Auth Core

Related documentation: Data ownership

Status

This document is FINAL and ENFORCEABLE for migrating legacy systems to the new architecture.

---

1. Purpose

This plan defines how to migrate:

• MongoDB users
• Finance system companies
• Legacy permission system

into:

• Auth Backend (identity, memberships, permissions)
• Platform Core (companies, entitlements, subscriptions)

---

2. Migration Principles

No big-bang migration
No downtime
No dual source of truth long-term
Fail-safe and reversible steps

---

3. Target Mapping

Legacy	New System
users (Mongo)	Auth users
company_users	Auth memberships
permissions	Auth permissions
package_permissions	Core entitlements
finance companies	Core companies

---

4. Phases

Phase 1 — Read-only sync

• keep Mongo as source of truth

• build sync job: Mongo → Auth Mongo → Core

• validate data consistency

---

Phase 2 — Dual write

• new writes go to:

  • Mongo (legacy)
  • Auth/Core (new)

• ensure both stay aligned

---

Phase 3 — Read switch

• backend reads from:

  • Auth (users, permissions)
  • Core (entitlements)

• Mongo becomes fallback only

---

Phase 4 — Freeze legacy writes

• disable writes to Mongo
• validate full system using Auth/Core

---

Phase 5 — Decommission

• remove Mongo logic
• remove legacy permission code
• remove dual write

---

5. Data Migration Details

5.1 Users

• copy users → Auth
• map:
  • _id → uuid
  • email → email
  • roles → tenantRole

---

5.2 Companies

• move finance companies → Core.companies
• assign unique UUID
• preserve legacy Mongo/finance identifiers in companies.old_id
• map company master fields to Core company columns
• map embedded package/subscription state to company_subscriptions / company_addons
• do not keep embedded users/permissions inside company payloads after migration

Legacy company split

Legacy company documents often mix multiple domains. The migration must split them as follows:

• company master and lifecycle fields → Core.companies
• package/subscription/add-on state → Core.company_subscriptions / Core.company_addons
• embedded users and roles → Auth memberships
• embedded permission arrays → Auth membership grants
• profile/social/document metadata → Core profile tables or later company-profile storage

---

5.3 Memberships

• create membership per user-company
• assign:
  • role
  • modules (initial grants)
  • permissions

---

5.4 Permissions

• map legacy permissions → new permission keys
• normalize naming (e.g. finance.expense.view)

---

6. Sync Strategy

6.1 Incremental sync

• run scheduled job (cron)
• detect changes
• push to Auth/Core

---

6.2 Event-based sync (optional)

• Mongo change streams
• trigger updates instantly

---

7. Validation

Before switching reads:

• user count matches
• company count matches
• membership count matches
• permission parity validated

---

8. Rollback Plan

At any phase:

• revert reads to Mongo
• disable Auth/Core reads
• maintain data sync

---

9. Risks

• inconsistent IDs
• missing permissions
• stale cache

Mitigation:

• strict validation
• logs
• metrics

---

10. Final Rule

Migration is complete only when Mongo is no longer used for:
- users
- permissions
- company access