Multi-Tenant Architecture

Overview

Every piece of data in the system is scoped to an organization (tenant). The org_id from the JWT token determines which data a user can see.

How It Works

Login → Org Selection → JWT { org_id: "xxx" } → All queries filtered by org_id

Row Level Security (RLS)

Every resource table has RLS policies that:

Extract org_id from the current session
Filter rows to only those belonging to that organization
Prevent cross-tenant data access

Organization Hierarchy

┌─────────────────────┐
│  National Org       │  is_national = true
│  (cross-org access) │  country_code = 'SK'
└─────────────────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌──────┐  ┌──────┐
│ Org A│  │ Org B│  is_national = false
│      │  │      │  country_code = 'SK'
└──────┘  └──────┘

Organization IDs

Important: There are two different "org IDs":

Column	Table	Purpose
`org_id`	`organizations`	The JWT claim, used for RLS (UUID)
`id`	`resources_organization`	Internal PK, NOT the tenant ID

Always use organizations.org_id (= JWT org_id) for tenant scoping.

National Organizations

Organizations with is_national = true have special powers:

Cross-org visibility: Can view patients from all orgs with the same country_code
National registry: Used for health registries and regulatory reporting
CodeSystem ownership: Own shared medical terminology data

National Org	Country	Owns
Indonesian National (`cb6cd836`)	ID	ICD-10, ICD-9-CM codes
Slovak National (`fdfc8af2`)	SK	ICD-10 chapters, SNOMED CT

Shared Data

CodeSystem resources (ICD-10, ICD-9-CM, SNOMED CT) are not tenant-scoped:

can_access_resource_row() returns true for all CodeSystem resources
Any authenticated user can read terminology data regardless of org

Country-Aware Features

The system adapts behavior based on country_code:

Feature	SK (Slovakia)	ID (Indonesia)
ICD-10 format	22 chapter resources (2,351 codes)	267 flat resources
Condition coding	ICD-10 only	ICD-10 + Kemenkes dual coding
Language	Slovak + English	Indonesian + English
Labor rules (HR)	Slovak labor code	Indonesian labor law

Multi-Org Users

Staff and patients can belong to multiple organizations:

Staff hold a set of roles per organization
Patients hold a membership per organization, each with its own approval status

At login, users see all their orgs and select one. The JWT is scoped to that single org.

Organizational Affiliations

Organizations can have relationships (parent-child, network membership) via FHIR OrganizationAffiliation resources.

Specializations

Organizations declare their specialties using SNOMED CT codes (via OrganizationAffiliation). These are used for:

Public organization search and filtering
Patient-facing org discovery
Provider directory listings