Skip to content

Tenant Registry Service

Overview

The Tenant Registry Service is responsible for managing healthcare organizations onboarded onto the VitalBridge platform.

A tenant represents an independent healthcare organization such as:

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

The Tenant Registry Service acts as the authoritative source of tenant information and serves as the foundation of the platform's multi-tenant architecture.

Responsibilities

The Tenant Registry Service is responsible for:

  • Tenant onboarding
  • Tenant lifecycle management
  • Tenant status management
  • Tenant configuration
  • Tenant metadata management
  • Tenant event publication

The service is the system of record for all tenant-related information.

Service Architecture

flowchart TB

    ADMIN["Super Administrator"]

    TR["Tenant Registry Service"]

    TR_DB[("Tenant Registry DB")]

    ADMIN --> TR

    TR --> TR_DB
Hold "Alt" / "Option" to enable pan & zoom

Tenant Lifecycle

Every tenant progresses through a defined lifecycle.

stateDiagram-v2

    [*] --> Pending

    Pending --> Active

    Active --> Suspended

    Suspended --> Active

    Active --> Archived

    Archived --> [*]
Hold "Alt" / "Option" to enable pan & zoom

Pending

Tenant record has been created but onboarding is incomplete.

Active

Tenant is fully operational.

Suspended

Tenant access is temporarily disabled.

Archived

Tenant is no longer operational but historical records remain.

Tenant Onboarding

Tenant creation begins with a Super Administrator.

sequenceDiagram

    participant SA as Super Administrator

    participant TR as Tenant Registry Service

    participant DB as Tenant Registry DB

    SA->>TR: Create Tenant

    TR->>DB: Save Tenant

    DB-->>TR: Tenant Created

    TR-->>SA: Success
Hold "Alt" / "Option" to enable pan & zoom

Once a tenant has been created, additional onboarding workflows may be triggered.

Tenant Creation Workflow

flowchart LR

    CREATE["Create Tenant"]

    VALIDATE["Validate Request"]

    SAVE["Persist Tenant"]

    EVENT["Publish tenant.created"]

    COMPLETE["Onboarding Started"]

    CREATE --> VALIDATE

    VALIDATE --> SAVE

    SAVE --> EVENT

    EVENT --> COMPLETE
Hold "Alt" / "Option" to enable pan & zoom

The service publishes domain events to allow downstream services to participate in onboarding.

Tenant Data Model

Each tenant record contains organizational metadata.

erDiagram TENANT { uuid id string name string type string timezone string status datetime created_at datetime updated_at } ADDRESS { string line1 string line2 string city_id string state_id string country_code string postal_code } PRIMARY_CONTACT { string first_name string last_name string email string mobile } TENANT ||--|| ADDRESS : has TENANT ||--|| PRIMARY_CONTACT : has
Hold "Alt" / "Option" to enable pan & zoom

Typical tenant information includes:

  • Organization Name
  • Organization Identifier
  • Contact Information
  • Timezone
  • Operational Status
  • Configuration Settings

Domain Events

The Tenant Registry Service publishes domain events whenever tenant state changes.

flowchart LR

    TR["Tenant Registry Service"]

    KAFKA["Apache Kafka"]

    TR --> KAFKA
Hold "Alt" / "Option" to enable pan & zoom

Examples include:

  • tenant.created
  • tenant.updated
  • tenant.activated
  • tenant.suspended
  • tenant.archived

These events allow other services to react independently.

Tenant Creation Event

flowchart LR

    TR["Tenant Registry Service"]

    K["Apache Kafka"]

    ADMIN["Admin Service"]

    ID["Identity Service"]

    DOC["Doctor Service"]

    PAT["Patient Service"]

    TR -->|"tenant.created"| K

    K --> ADMIN

    K --> ID

    K --> DOC

    K --> PAT
Hold "Alt" / "Option" to enable pan & zoom

The Tenant Registry Service remains unaware of how downstream services process the event.

This preserves service autonomy.

Tenant Isolation

The Tenant Registry Service is the source of truth for tenant ownership.

flowchart TB

    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

Every business entity ultimately belongs to a tenant.

Tenant Validation

Other services frequently need to validate tenant existence.

sequenceDiagram

    participant Service

    participant TenantRegistry

    Service->>TenantRegistry: Validate Tenant

    TenantRegistry-->>Service: Tenant Exists
Hold "Alt" / "Option" to enable pan & zoom

The Tenant Registry Service acts as the authoritative source for tenant validation.

Database Ownership

The service owns its database exclusively.

flowchart TB

    TR["Tenant Registry Service"]

    DB[("Tenant Registry DB")]

    TR --> DB
Hold "Alt" / "Option" to enable pan & zoom

No other service may:

  • Read tenant tables directly
  • Modify tenant records
  • Share schemas

All interactions must occur through APIs or events.

Security Model

Only authorized users may perform tenant operations.

flowchart LR

    USER["User"]

    AUTH["Authorization"]

    TENANT["Tenant Operation"]

    USER --> AUTH

    AUTH --> TENANT
Hold "Alt" / "Option" to enable pan & zoom

Super Administrators

Can:

  • Create tenants
  • Update tenants
  • Suspend tenants
  • Archive tenants

Tenant Administrators

Cannot:

  • Create tenants
  • Delete tenants
  • Manage other tenants

Event-Driven Integration

The Tenant Registry Service integrates with the rest of the platform through events.

flowchart TB

    TR["Tenant Registry Service"]

    OUTBOX["Transactional Outbox"]

    K["Apache Kafka"]

    CONSUMERS["Consumer Services"]

    TR --> OUTBOX

    OUTBOX --> K

    K --> CONSUMERS
Hold "Alt" / "Option" to enable pan & zoom

This ensures reliable event delivery while maintaining service independence.

Design Principles

The Tenant Registry Service follows several architectural principles.

Single Source of Truth

Tenant information exists in exactly one place.

Event-Driven Integration

Tenant state changes are propagated through domain events.

Service Ownership

Only the Tenant Registry Service may modify tenant data.

Multi-Tenant Foundation

All tenant-aware services depend on tenant information originating from this service.