Docs / Developer Documentation

Developer Documentation

This is the technical implementation guide for Global Clinic. It describes the system as built today (a statically-exported Next.js reference implementation on mock data) and defines the production system it is designed to become: the architecture, the data model, the production APIs, the integrations, the security model, and operations.

It is written for engineers extending the platform. Product and operational context is in the Product Documentation. The authoritative typed contract for data shapes is lib/schema.ts; the single data-access seam is lib/data.ts.

How this guide is organised

Section	What it covers
1. Architecture	System, component, deployment, multi-tenant and security architecture
2. Data Model	Entity-relationship diagram, entity definitions, attributes, validation, indexing, audit
3. API Guide	Production REST APIs for all 17 resource groups, plus the OpenAPI spec
4. Integrations	Inbound and outbound integration patterns and provider catalogue
5. Security	Authentication, authorization, RBAC, encryption, secrets, audit, PII, secure API design
6. Operations	Deployment, environment config, monitoring, backup and recovery, incident response, support

The machine-readable API contract lives at docs/developer/api/openapi.yaml.

Extending the platform. The Implementation Plan specifies the next build: new entities and the proposed lib/schema.extensions.ts, API groups 18–23 with extensions to groups 5/7/9/12/13/16 (API & Integration), proposed seed data in data/_proposed/*.json, and the new integrations (insurer/TPA, FRRO/government, airline/hotel/tour, translation, WhatsApp).

Current state in one paragraph

The repository is a Next.js 16 / React 19 / TypeScript front-end reference build that exports to a fully static site (output: "export") and is hosted on S3 behind CloudFront via an AWS CDK (Python) app. Every screen reads typed values from lib/data.ts, which today imports static JSON from data/. lib/schema.ts is a rich, documented schema that already models the production system (stages carry owner and slaTarget; corridors carry Country-Pack fields). Mutable UI state lives in client contexts (PortalProvider, ClinicProvider); a small mock auth layer lives in lib/auth.tsx. There is no backend, database, real authentication, real payments, real storage, or external integration yet. The design intent is that swapping mock data for a real API is a localised change at the lib/data.ts seam while lib/schema.ts stays the contract.

The backend swap, in principle

flowchart LR
  UI[Screens / Views] --> DATA[lib/data.ts: the single seam]
  DATA -- today --> JSON[(static JSON in /data)]
  DATA -- production --> API[REST API + Postgres]
  SCHEMA[lib/schema.ts: typed contract] --- DATA
  SCHEMA --- API

Keep every type in lib/schema.ts, replace the JSON imports in lib/data.ts with fetch calls to the APIs defined in section 3, make the consuming Server Components async (or load via a client data library), and seed the client providers from server responses. Nothing else in the UI has to change.