Skip to main content

​
Multi-Branch Architecture: 12 -> 40 Branch Clinic Group

​
Goal

Scale OdontoX from a mid-size multi-branch tenant to a 40-branch operating model without rewriting the current product surface. The path should preserve today’s clinic-scoped data model, extend the existing module and notification patterns, and keep tenant isolation explicit.

​
Current Baseline

  • Single platform codebase with clinic-scoped records across appointments, patients, invoices, conversations, and notifications.
  • Branch context is selected per clinic and already drives branding, modules, permissions, and most routing.
  • Superadmin tooling exists for cross-tenant operations, but clinic users primarily operate inside one current clinic context at a time.
  1. Keep one tenant per legal clinic group, with each physical branch represented as its own clinic record.
  2. Treat clinic_id as the operational branch boundary for day-to-day booking, billing, inbox, and notification behavior.
  3. Add group-level reporting and governance as aggregation on top of branch data, not by weakening branch isolation.

​
Why This Fits The Existing Code

  • Module loading is already clinic-aware.
  • Notification preferences already live per clinic.
  • WhatsApp routing and inbox conversations already resolve by clinic context.
  • PDF letterhead resolution is already tenant-aware and should remain clinic-scoped unless an explicit group override is introduced later.

​
Data Boundaries

​
Branch-scoped

  • Appointments
  • Patients
  • Conversations and inbox activity
  • Invoices, quotations, receipts, installment plans
  • Inventory
  • Staff assignments
  • Notification preferences
  • Branding and PDF assets

​
Group-scoped

  • Cross-branch analytics rollups
  • Shared purchasing / finance exports
  • Central policy templates
  • Marketplace / module rollout governance
  • Optional shared patient identity linking

​
Patient Identity Strategy

Use a two-layer model.
  • Keep the existing branch-local patient record as the default operational record.
  • Introduce an optional group-level patient identity link only when the clinic group genuinely needs cross-branch continuity.
  • Never replace branch-local patient IDs in existing workflows; add linkage metadata alongside them.
This avoids rewriting current appointment, billing, and inbox flows while still allowing future shared-history views.

​
Staff Strategy

  • Keep user accounts global enough for authentication, but keep branch access through clinic assignments.
  • Visiting doctors remain no-login contact records and should continue receiving branch-scoped booking emails only when the clinic enables that toggle.
  • Shared staff across branches should carry multiple clinic assignments instead of duplicated user records.

​
Notifications And Communications

  • Store all notification preferences per clinic.
  • Keep WhatsApp inboxes branch-scoped so inbound traffic lands in the correct operational queue.
  • Use group-level broadcasting only for explicitly centralised campaigns, never for operational appointment traffic.

​
Reporting Path

  1. Preserve branch-first transactional writes.
  2. Build group dashboards from read-side aggregation across clinics.
  3. Keep filters explicit: branch, city, region, doctor, date range, module.
This keeps transactional correctness simple while still supporting executive reporting for 40 branches.

​
Operational Risks To Watch

  • Cross-branch patient duplication if a shared identity layer is added without clear merge rules.
  • Staff permission drift when one user is assigned to many clinics.
  • Notification mistakes if group-wide defaults start overriding branch-specific preferences.
  • Query cost growth on analytics endpoints if rollups stay fully live instead of gaining cached summaries.

​
Delivery Phases

  1. Phase 1: Stabilise branch isolation and branch-aware routing everywhere.
  2. Phase 2: Add group reporting surfaces and shared filters.
  3. Phase 3: Add optional shared patient identity linking.
  4. Phase 4: Introduce group policy inheritance where it reduces admin work without removing branch override control.

​
Recommendation

For a 12 -> 40 branch rollout, keep the current clinic-scoped architecture as the core operating model and layer group capabilities on top. That is the lowest-risk path, matches the current codebase, and avoids a rewrite of appointments, billing, WhatsApp inboxes, or notification routing.