Kulcare System Entities

Purpose: Comprehensive documentation of all system entities with real-world examples

Core Entity Concepts
Identity & Authentication Entities
Organizational Structure Entities
Healthcare Provider Entities
Clinical Care Entities

Core Entity Concepts

Multi-Tenancy Model

Tenant: A customer organization (e.g., Apollo Hospitals, Fortis Healthcare)

One tenant = One customer account
Contains multiple organizations, facilities, users
Isolated data access via Row-Level Security (RLS)

Example:

Tenant: Apollo Hospitals (ID: tenant-123)
├── Organizations: Apollo Hospital System, Apollo Clinics
├── Facilities: Apollo Main Hospital, Apollo Clinic Whitefield
└── Users: Dr. Smith, Nurse Johnson, Admin User

Key Principles

Global Entities: No tenant_id (Users, Practitioners, Reference data)
Tenant-Scoped: Has tenant_id with RLS (Organizations, Facilities, Patients)
Cross-Tenant Links: Practitioners can work at multiple tenants via roles

Identity & Authentication Entities

1. User

Purpose: Authentication identity - login credentials

Real-World Example: Dr. Sarah Johnson's login account

{
  "id": "user-abc123",
  "email": "sarah.johnson@example.com",
  "phone": "+919876543210",
  "first_name": "Sarah",
  "last_name": "Johnson",
  "display_name": "Dr. Sarah Johnson",
  "avatar_url": "https://cdn.example.com/avatars/sarah.jpg",
  "email_verified": true,
  "phone_verified": true,
  "is_active": true,
  "last_login_at": "2026-01-15T10:30:00Z"
}

Key Points:

No tenant_id - Users can belong to multiple tenants
One user can have multiple roles across different tenants
Login credentials work across all tenant memberships

Tables Affected: identity.users

2. UserMembership

Purpose: Links users to tenants with specific roles

Real-World Example: Dr. Sarah working at multiple hospitals

[
  {
    "id": "membership-001",
    "user_id": "user-abc123",
    "tenant_id": "apollo-tenant",
    "role": "practitioner",
    "status": "active"
  },
  {
    "id": "membership-002",
    "user_id": "user-abc123",
    "tenant_id": "fortis-tenant",
    "role": "practitioner",
    "status": "active"
  }
]

Role Types:

owner - Tenant owner (full access)
admin - Administrator (full operational access)
staff - Staff member (limited access)
practitioner - Healthcare provider (clinical access)

Tables Affected: identity.user_memberships

Organizational Structure Entities

3. Tenant

Purpose: Top-level customer account

Real-World Example: Apollo Hospitals chain

{
  "id": "apollo-tenant",
  "name": "Apollo Hospitals Group",
  "slug": "apollo-hospitals",
  "status": "active",
  "plan_tier": "enterprise",
  "settings": {
    "max_facilities": 100,
    "ai_enabled": true,
    "support_level": "premium"
  }
}

Plan Tiers:

free - 1 organization, 1 facility, 5 users
starter - 3 organizations, 5 facilities, 25 users
professional - 10 organizations, 25 facilities, 100 users
enterprise - Unlimited everything

Tables Affected: identity.tenants

4. Organization

Purpose: Legal healthcare entity (hospital system, clinic group)

Real-World Example: Apollo Hospital System

{
  "id": "org-main",
  "tenant_id": "apollo-tenant",
  "parent_id": null,
  "name": "Apollo Hospital System",
  "alias": ["Apollo Bangalore", "Apollo Main"],
  "organization_type": "hospital_system",
  "identifiers": [
    { "system": "gstin", "value": "29ABCDE1234F1Z5" },
    { "system": "pan", "value": "ABCDE1234F" }
  ],
  "email": "contact@apollohospitals.com",
  "phone": "+918012345678",
  "website": "https://apollohospitals.com",
  "address": {
    "line": "154/11, Bannerghatta Road",
    "city": "Bangalore",
    "state": "Karnataka",
    "postal_code": "560076",
    "country": "IN"
  },
  "is_active": true
}

Organization Types:

hospital_system - Multi-facility hospital group
healthcare_provider - Single hospital/clinic
clinic_group - Chain of clinics
laboratory - Diagnostic lab chain
pharmacy - Pharmacy chain

Tables Affected: identity.organizations

5. Facility

Purpose: Physical location where healthcare is delivered

Real-World Example: Apollo Hospital Bannerghatta

{
  "id": "facility-bannerghatta",
  "tenant_id": "apollo-tenant",
  "organization_id": "org-main",
  "name": "Apollo Hospital Bannerghatta",
  "display_name": "Apollo Bannerghatta",
  "facility_type_id": "type-general-hospital",
  "service_level": "opd_ipd_surgery",
  "ownership_model": "corporate",
  "specialty_scope": "multi_specialty",
  "bed_count": 350,
  "icu_bed_count": 24,
  "ot_count": 8,
  "has_opd": true,
  "has_ipd": true,
  "has_emergency": true,
  "has_surgery": true,
  "has_pharmacy": true,
  "has_lab": true,
  "has_imaging": true,
  "operational_status": "active",
  "is_virtual": false
}

Service Levels:

opd_only - Outpatient only
opd_daycare - OPD + daycare (<24h admission)
opd_ipd - OPD + inpatient
opd_ipd_surgery - Full services including surgery

Tables Affected:

identity.facilities
identity.facility_locations (addresses)

Healthcare Provider Entities

6. Practitioner

Purpose: Licensed healthcare provider (global entity)

Real-World Example: Dr. Sarah Johnson

{
  "id": "practitioner-sarah",
  "user_id": "user-abc123",
  "first_name": "Sarah",
  "last_name": "Johnson",
  "display_name": "Dr. Sarah Johnson MD",
  "gender": "female",
  "birth_date": "1985-05-15",
  "photo_url": "https://cdn.example.com/practitioners/sarah.jpg",
  "identifiers": [
    { "system": "mci", "value": "12345-Karnataka-2010", "state": "Karnataka" },
    { "system": "npi", "value": "1234567890" }
  ],
  "qualifications": [
    {
      "code": "MBBS",
      "issuer": "Bangalore Medical College",
      "year": 2010
    },
    {
      "code": "MD",
      "specialty": "Cardiology",
      "issuer": "AIIMS Delhi",
      "year": 2014
    }
  ],
  "languages": ["English", "Hindi", "Kannada"],
  "is_active": true
}

Key Points:

No tenant_id - Practitioners work across facilities
One practitioner = One global record
Links to User (optional) for login
Multiple PractitionerRole entries for different facilities

Tables Affected:

identity.practitioners
connect.professional_profiles (LinkedIn-style profile)

7. PractitionerRole

Purpose: Assigns practitioner to specific facility with role

Real-World Example: Dr. Sarah's roles at different hospitals

[
  {
    "id": "role-apollo-cardio",
    "tenant_id": "apollo-tenant",
    "practitioner_id": "practitioner-sarah",
    "facility_id": "facility-bannerghatta",
    "role_type": "physician",
    "specialty_id": "specialty-cardiology",
    "available_days": {
      "mon": true,
      "tue": true,
      "wed": true,
      "thu": true,
      "fri": true,
      "sat": false,
      "sun": false
    },
    "is_primary": true,
    "is_active": true,
    "start_date": "2020-01-15",
    "end_date": null,
    "consultation_fee": 1500,
    "currency": "INR"
  },
  {
    "id": "role-fortis-cardio",
    "tenant_id": "fortis-tenant",
    "practitioner_id": "practitioner-sarah",
    "facility_id": "fortis-main",
    "role_type": "physician",
    "specialty_id": "specialty-cardiology",
    "available_days": {
      "mon": false,
      "tue": false,
      "wed": false,
      "thu": true,
      "fri": true,
      "sat": true,
      "sun": true
    },
    "is_primary": false,
    "is_active": true,
    "start_date": "2022-06-01",
    "consultation_fee": 2000,
    "currency": "INR"
  }
]

Role Types:

physician - Doctor/medical practitioner
nurse - Nursing staff
technician - Lab/ imaging technician
therapist - Physical/speech therapist
pharmacist - Pharmacy staff
admin - Administrative staff

Tables Affected: identity.practitioner_roles

Clinical Care Entities

8. Patient

Purpose: Person receiving healthcare (tenant-scoped)

Real-World Example: Patient Raj Kumar at Apollo

{
  "id": "patient-raj",
  "tenant_id": "apollo-tenant",
  "user_id": "user-raj",
  "mrn": "APOLLO-2024-001234",
  "first_name": "Raj",
  "last_name": "Kumar",
  "gender": "male",
  "birth_date": "1980-03-20",
  "blood_type": "O+",
  "identifiers": [
    { "system": "aadhaar", "value": "1234-5678-9012" },
    { "system": "abdm_health_id", "value": "12-1234-1234-1234" }
  ],
  "contact": {
    "phone": "+919876543211",
    "email": "raj.kumar@example.com"
  },
  "emergency_contact": {
    "name": "Priya Kumar",
    "relationship": "spouse",
    "phone": "+919876543212"
  },
  "is_active": true
}

Key Points:

Has tenant_id - Patients belong to specific tenant
Can be linked to multiple facilities via patient_facilities
MRN (Medical Record Number) is tenant-specific

Tables Affected:

clinical.patients
clinical.patient_facilities (links to facilities)

Quick Reference Summary

Entity	Tables Affected	Tenant Scoped	Real-World Example
User	`identity.users`	No	Dr. Sarah's login account
UserMembership	`identity.user_memberships`	Yes	Sarah → Apollo Hospitals
Tenant	`identity.tenants`	No	Apollo Hospitals account
Organization	`identity.organizations`	Yes	Apollo Hospital System
Facility	`identity.facilities`	Yes	Apollo Bannerghatta Hospital
Practitioner	`identity.practitioners`	No	Dr. Sarah (global record)
PractitionerRole	`identity.practitioner_roles`	Yes	Sarah @ Apollo Cardiology
Patient	`clinical.patients`	Yes	Patient Raj @ Apollo
Invoice	`billing.invoices`	Yes	Raj's consultation bill

This guide provides complete entity documentation with real-world examples to help your team understand the system architecture and implement profile switching functionality.

Kulcare System Entities

Table of Contents

Core Entity Concepts

Multi-Tenancy Model

Key Principles

Identity & Authentication Entities

1. User

2. UserMembership

Organizational Structure Entities

3. Tenant

4. Organization

5. Facility

Healthcare Provider Entities

6. Practitioner

7. PractitionerRole

Clinical Care Entities

8. Patient

Quick Reference Summary

On this page

Kulcare System Entities

Table of ContentsCopy Anchor Link

Core Entity ConceptsCopy Anchor Link

Multi-Tenancy ModelCopy Anchor Link

Key PrinciplesCopy Anchor Link

Identity & Authentication EntitiesCopy Anchor Link

1. UserCopy Anchor Link

2. UserMembershipCopy Anchor Link

Organizational Structure EntitiesCopy Anchor Link

3. TenantCopy Anchor Link

4. OrganizationCopy Anchor Link

5. FacilityCopy Anchor Link

Healthcare Provider EntitiesCopy Anchor Link

6. PractitionerCopy Anchor Link

7. PractitionerRoleCopy Anchor Link

Clinical Care EntitiesCopy Anchor Link

8. PatientCopy Anchor Link

Quick Reference SummaryCopy Anchor Link

On this page

Table of Contents

Core Entity Concepts

Multi-Tenancy Model

Key Principles

Identity & Authentication Entities

1. User

2. UserMembership

Organizational Structure Entities

3. Tenant

4. Organization

5. Facility

Healthcare Provider Entities

6. Practitioner

7. PractitionerRole

Clinical Care Entities

8. Patient

Quick Reference Summary