Admin Service¶

Overview¶

The Admin Service is responsible for managing Tenant Administrators within the VitalBridge platform.

A Tenant Administrator represents an individual authorized to manage a healthcare organization after it has been onboarded.

The service manages:

Tenant Administrator creation
Tenant Administrator lifecycle management
Administrative profile management
Tenant Administrator activation and deactivation
Tenant Administrator event publication

The Admin Service does not manage tenant organizations themselves. That responsibility belongs to the Tenant Registry Service.

Responsibilities¶

The Admin Service is responsible for:

Tenant Administrator Management¶

Create Tenant Administrators
Update Tenant Administrators
Activate Tenant Administrators
Deactivate Tenant Administrators

Administrative Profiles¶

Administrative contact information
Organization assignments
Administrative metadata

Identity Integration¶

User provisioning requests
Role assignment coordination
Identity lifecycle synchronization

Event Publication¶

administrator.created
administrator.updated
administrator.activated
administrator.deactivated

Service Architecture¶

flowchart TB

    SA["Super Administrator"]

    ADMIN["Admin Service"]

    ADMIN_DB[("Admin DB")]

    SA --> ADMIN

    ADMIN --> ADMIN_DB

Hold "Alt" / "Option" to enable pan & zoom

Service Ownership¶

The Admin Service owns all Tenant Administrator data.

flowchart TB

    ADMIN["Admin Service"]

    ADMIN_DB[("Admin DB")]

    ADMIN --> ADMIN_DB

Hold "Alt" / "Option" to enable pan & zoom

No other service may:

Create administrator records
Modify administrator records
Access administrator tables directly

Cross-service communication occurs through APIs and events.

Administrative Hierarchy¶

flowchart TB

    PLATFORM["VitalBridge Platform"]

    TENANT["Tenant"]

    ADMIN["Tenant Administrator"]

    PLATFORM --> TENANT

    TENANT --> ADMIN

Hold "Alt" / "Option" to enable pan & zoom

A Tenant Administrator always belongs to exactly one tenant.

An administrator cannot belong to multiple tenants.

Tenant Administrator Lifecycle¶

stateDiagram-v2

    [*] --> Pending

    Pending --> Active

    Active --> Inactive

    Inactive --> Active

    Active --> Archived

    Archived --> [*]

Hold "Alt" / "Option" to enable pan & zoom

Pending¶

Administrator record created but onboarding not completed.

Active¶

Administrator can access the platform.

Inactive¶

Administrator access is temporarily disabled.

Archived¶

Administrator no longer participates in tenant operations.

Tenant Administrator Data Model¶

erDiagram

    TENANT_ADMIN {

        uuid id

        uuid tenant_id

        string first_name

        string last_name

        string email

        string mobile

        string status

        datetime created_at

        datetime updated_at

    }

Hold "Alt" / "Option" to enable pan & zoom

Tenant Administrator¶

Represents an organization administrator responsible for managing a tenant.

Field	Description
id	Unique administrator identifier
tenant_id	Owning tenant
first_name	Administrator first name
last_name	Administrator last name
email	Administrator email
mobile	Administrator mobile number
status	Lifecycle status
created_at	Creation timestamp
updated_at	Last update timestamp

Administrator Creation Workflow¶

sequenceDiagram

    participant SA as Super Administrator

    participant ADMIN as Admin Service

    participant DB as Admin DB

    SA->>ADMIN: Create Administrator

    ADMIN->>DB: Save Administrator

    DB-->>ADMIN: Administrator Created

    ADMIN-->>SA: Success

Hold "Alt" / "Option" to enable pan & zoom

Identity Provisioning¶

The Admin Service collaborates with the Identity Service to provision platform access.

sequenceDiagram

    participant AdminService

    participant IdentityService

    participant Keycloak

    AdminService->>IdentityService: Provision User

    IdentityService->>Keycloak: Create Account

    Keycloak-->>IdentityService: Account Created

    IdentityService-->>AdminService: User Provisioned

Hold "Alt" / "Option" to enable pan & zoom

The Admin Service remains responsible for administrative records while the Identity Service manages identity provisioning.

Tenant Assignment¶

Every administrator belongs to a tenant.

flowchart LR

    ADMIN["Tenant Administrator"]

    TENANT["Tenant"]

    ADMIN --> TENANT

Hold "Alt" / "Option" to enable pan & zoom

This relationship is immutable after creation.

Tenant migration requires administrative intervention.

Domain Events¶

The Admin Service publishes events whenever administrator state changes.

flowchart LR

    ADMIN["Admin Service"]

    KAFKA["Apache Kafka"]

    ADMIN --> KAFKA

Hold "Alt" / "Option" to enable pan & zoom

Examples include:

administrator.created
administrator.updated
administrator.activated
administrator.deactivated

Event Flow¶

flowchart LR

    ADMIN["Admin Service"]

    OUTBOX["Transactional Outbox"]

    KAFKA["Apache Kafka"]

    ADMIN --> OUTBOX

    OUTBOX --> KAFKA

Hold "Alt" / "Option" to enable pan & zoom

All events are published through the Transactional Outbox pattern.

Authorization Model¶

Tenant Administrators operate within tenant boundaries.

flowchart TB

    SUPER["ROLE_SUPER_ADMIN"]

    TENANT_ADMIN["ROLE_TENANT_ADMIN"]

    TENANT["Tenant"]

    SUPER --> TENANT

    TENANT_ADMIN --> TENANT

Hold "Alt" / "Option" to enable pan & zoom

Super Administrator¶

Can:

Create administrators
Update administrators
Deactivate administrators

Tenant Administrator¶

Can:

Access their tenant
Manage tenant operations

Cannot:

Manage other tenants
Create new tenants

Security Boundaries¶

The Admin Service enforces:

Authentication
Role validation
Tenant validation
Resource ownership validation

flowchart LR

    REQUEST["Request"]

    AUTH["Authentication"]

    ROLE["Role Validation"]

    TENANT["Tenant Validation"]

    EXECUTE["Business Operation"]

    REQUEST --> AUTH

    AUTH --> ROLE

    ROLE --> TENANT

    TENANT --> EXECUTE

Hold "Alt" / "Option" to enable pan & zoom

Design Principles¶

Single Responsibility¶

The service manages tenant administrators only.

Tenant Ownership¶

Every administrator belongs to exactly one tenant.

Event-Driven Integration¶

Administrative changes are propagated through domain events.

Service Autonomy¶

The service owns its data and business rules.

Identity Separation¶

Authentication and identity provisioning remain external responsibilities.