Skip to content

Multi-Tenancy Architecture

Overview

VitalBridge is a multi-tenant healthcare platform where each healthcare organization operates as an independent tenant.

Examples of tenants include:

  • Hospitals
  • Clinics
  • Healthcare Networks
  • Telehealth Providers
  • Corporate Wellness Organizations

Although all tenants share the same platform infrastructure, each tenant's data, users, providers, patients, appointments, and schedules remain logically isolated from every other tenant.

What is a Tenant?

A tenant represents a healthcare organization onboarded onto the VitalBridge platform.

Examples:

Tenant Type
Starlight Hospital Hospital
Green Valley Clinic Clinic

Each tenant owns:

  • Tenant Administrators
  • Providers
  • Patients
  • Schedules
  • Appointments
  • Configuration

Multi-Tenant Model

VitalBridge uses a Shared Application, Shared Database, Tenant-Isolated Data Model.

flowchart TB

    PLATFORM["VitalBridge Platform"]

    TENANT_A["Tenant A"]
    TENANT_B["Tenant B"]
    TENANT_C["Tenant C"]

    PLATFORM --> TENANT_A
    PLATFORM --> TENANT_B
    PLATFORM --> TENANT_C
Hold "Alt" / "Option" to enable pan & zoom

All tenants use the same application deployment while maintaining strict logical isolation.

Tenant Isolation

Every business entity belongs to exactly one tenant.

flowchart LR

    TENANT["Tenant"]

    PROVIDERS["Providers"]
    PATIENTS["Patients"]
    APPOINTMENTS["Appointments"]
    SCHEDULES["Schedules"]

    TENANT --> PROVIDERS
    TENANT --> PATIENTS
    TENANT --> APPOINTMENTS
    TENANT --> SCHEDULES
Hold "Alt" / "Option" to enable pan & zoom

A provider, patient, schedule, or appointment can never belong to multiple tenants.

Tenant Context Propagation

Every authenticated request carries tenant context.

flowchart LR

    USER["Authenticated User"]

    TOKEN["JWT Access Token"]

    GATEWAY["API Gateway"]

    SERVICE["Domain Service"]

    USER --> TOKEN

    TOKEN --> GATEWAY

    GATEWAY --> SERVICE

    SERVICE -->|"Validate tenant_id"| SERVICE
Hold "Alt" / "Option" to enable pan & zoom

Before performing any operation, the service validates:

  • User identity
  • User role
  • Tenant ownership

Requests that attempt cross-tenant access are rejected.

Authorization Boundaries

Tenant isolation is enforced alongside role-based access control.

flowchart TB

    SUPER["ROLE_SUPER_ADMIN"]

    TENANT_ADMIN["ROLE_TENANT_ADMIN"]

    PROVIDER["ROLE_PROVIDER"]

    PATIENT["ROLE_PATIENT"]

    SUPER -->|"All Tenants"| PLATFORM["Platform"]

    TENANT_ADMIN -->|"Single Tenant"| TENANT["Tenant"]

    PROVIDER -->|"Own Tenant"| TENANT

    PATIENT -->|"Own Tenant"| TENANT
Hold "Alt" / "Option" to enable pan & zoom

Super Administrator

Can access:

  • All tenants
  • Platform-wide operations

Tenant Administrator

Can access:

  • Their tenant only

Provider

Can access:

  • Their own tenant
  • Authorized provider resources

Patient

Can access:

  • Their own tenant
  • Their own records

Service-Level Enforcement

Tenant isolation is enforced within every service.

flowchart LR

    REQUEST["Incoming Request"]

    TENANT_CHECK["Validate tenant_id"]

    AUTH_CHECK["Validate Role"]

    RESOURCE_CHECK["Validate Ownership"]

    BUSINESS["Execute Operation"]

    REQUEST --> TENANT_CHECK

    TENANT_CHECK --> AUTH_CHECK

    AUTH_CHECK --> RESOURCE_CHECK

    RESOURCE_CHECK --> BUSINESS
Hold "Alt" / "Option" to enable pan & zoom

No service may rely solely on gateway validation.

Every service independently validates tenant ownership before accessing data.

Tenant Onboarding

Tenant creation is initiated by a Super Administrator.

flowchart LR

    SA["Super Administrator"]

    TENANT["Tenant Registry Service"]

    ADMIN["Admin Service"]

    IDENTITY["Identity Service"]

    SA -->|"Create Tenant"| TENANT

    TENANT -->|"Tenant Created Event"| ADMIN

    TENANT -->|"Tenant Created Event"| IDENTITY
Hold "Alt" / "Option" to enable pan & zoom

The onboarding process provisions:

  • Tenant record
  • Administrative accounts
  • Identity mappings
  • Platform configuration

Data Ownership

Each service stores tenant-scoped data.

flowchart LR

    TENANT["Tenant A"]

    DOC_DB[("Doctor DB")]
    PAT_DB[("Patient DB")]
    APPT_DB[("Appointment DB")]
    SCH_DB[("Schedule DB")]

    TENANT --> DOC_DB
    TENANT --> PAT_DB
    TENANT --> APPT_DB
    TENANT --> SCH_DB
Hold "Alt" / "Option" to enable pan & zoom

All records include a tenant identifier and are filtered by tenant boundaries.

Cross-Tenant Access Prevention

The following scenario is prohibited:

flowchart LR

    TENANT_A["Tenant A"]

    TENANT_B["Tenant B"]

    PROVIDER["Provider"]

    PROVIDER --> TENANT_A

    PROVIDER -. Access Denied .-> TENANT_B
Hold "Alt" / "Option" to enable pan & zoom

No user, provider, patient, or administrator may access data owned by another tenant.

Architectural Benefits

The VitalBridge multi-tenant architecture provides:

  • Shared operational infrastructure
  • Strong tenant isolation
  • Lower operational costs
  • Simplified deployments
  • Horizontal scalability
  • Centralized platform management

Future Evolution

As platform adoption grows, the architecture can evolve toward:

flowchart TB

    PLATFORM["VitalBridge"]

    SMALL["Shared Tenants"]

    ENTERPRISE["Dedicated Enterprise Tenant"]

    PLATFORM --> SMALL

    PLATFORM --> ENTERPRISE
Hold "Alt" / "Option" to enable pan & zoom

This model allows enterprise customers to receive dedicated infrastructure while maintaining the same application architecture.

Key Principles

VitalBridge enforces the following multi-tenancy rules:

  • Every request must have tenant context
  • Every write operation must validate tenant ownership
  • Every service enforces tenant isolation
  • No cross-tenant access is permitted
  • Role validation and tenant validation are independent concerns
  • Tenant data ownership is mandatory across all services

These principles form the foundation of the platform's security and data isolation model.