High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:The Digital Healthcare Platform is a single TypeScript monorepo providing a production-grade healthcare management system. The architecture integrates a centralized Fastify-based modular monolith API with multiple front-end applications, including a Next.js web portal and Expo-based mobile applications for both patients and clinical staff.
Sources: README.md:3-8, README.md:16-18
Monorepo Structure
The project uses pnpm workspaces and Turborepo to manage dependencies and build pipelines across multiple applications and shared packages. Shared code resides in the packages/ directory and is strictly enforced by linting rules to prevent illegal imports between applications.
Sources: README.md:12-14, package.json:20-22
Component Overview
The system divides functionality into discrete applications and supporting shared packages:
| Path | Category | Role |
|---|---|---|
apps/api | Application | Core Fastify modular monolith API serving REST endpoints under /v1. |
apps/web | Application | Next.js portal for patients, staff dashboards, and platform consoles. |
apps/workers | Application | Background task processing using BullMQ and Redis. |
apps/mobile | Application | React Native/Expo app for Patient and Clinic variants. |
packages/db | Shared Package | Prisma-based data access layer with row-level security (RLS). |
packages/contracts | Shared Package | Zod schemas acting as the single source of truth for API and client types. |
packages/domain | Shared Package | Business logic including UHID generation and currency handling. |
Sources: README.md:16-32, apps/web/package.json:17-23, apps/api/package.json:20-25
Architectural Relationship Diagram
The following diagram illustrates the structural relationships between the applications and shared packages within the monorepo.
API and Communication Layer
The API is built as a Fastify modular monolith. It communicates with clients primarily via REST endpoints defined by Zod schemas. These schemas generate OpenAPI 3.1 documentation, ensuring type safety from the server to the client.
Sources: README.md:17, packages/contracts/src/openapi.ts:702-740
API Design Principles
- Contract-First Development: Zod schemas in
packages/contractsdefine all request bodies, query parameters, and responses. - Unified Error Handling: Errors follow a standard shape including a code, message, and unique request ID for tracing.
- Versioning: Core API routes are prefixed with
/v1.
Sources: packages/contracts/src/openapi.ts:69-80, apps/api/src/app.test.ts:32-40, apps/api/src/app.test.ts:58-85
Communication Sequence
The following sequence diagram shows the interaction between a client (web/mobile) and the API for a standard authenticated request.
Data Architecture
The platform utilizes PostgreSQL 16 with Prisma ORM. Data isolation is strictly enforced via Postgres Row-Level Security (RLS), ensuring that users only access data belonging to their specific organization (tenant).
Sources: README.md:23-24, packages/db/prisma/migrations/20261007120000_scheduling/migration.sql:127-133
Core Data Models
The data layer manages clinical scheduling, organization settings, and personnel.
| Entity | Description | Constraints |
|---|---|---|
clinics | Consulting locations for an organization. | Unique name per organization. |
consultation_types | Defines modes (in-person, video), fees, and durations. | Duration 5-240 mins; Fees >= 0. |
booking_rules | Global scheduling limits (horizon, cutoffs). | Horizon 1-365 days. |
availability_versions | Weekly schedule templates for doctors. | Slot minutes 5-240. |
availability_exceptions | Leaves, holidays, and extra sessions. | End date >= Start date. |
Sources: packages/db/prisma/migrations/20261007120000_scheduling/migration.sql:7-73, packages/db/prisma/migrations/20261007120000_scheduling/migration.sql:111-122
Entity Relationship Diagram
The following diagram defines the relationships between core scheduling components.
Authentication and Multi-tenancy
The system supports two distinct authentication paths and a strict multi-tenancy model:
- Staff Authentication: Requires email/password followed by a Time-based One-Time Password (TOTP) MFA step.
- Patient Authentication: Uses mobile number with OTP verification.
- Tenant Isolation: Every database request runs under RLS using the
withTenantandwithAuthhelpers, filtering by the current organization's ID.
Sources: README.md:9-10, README.md:23-24, packages/contracts/src/openapi.ts:88-120
Security Constraints
- CORS: Strictly enforced based on configured origin white-lists.
- Internal Details: Unexpected error details are hidden from clients to prevent data leakage.
- Production Safety: Sensitive operations like database seeding are blocked in production environments.
Sources: apps/api/src/app.test.ts:114-135, apps/api/src/app.test.ts:80-85, apps/api/src/scripts/seed.ts:15-18
Summary
The architecture prioritizes developer productivity through a monorepo structure while maintaining high standards for data safety via Postgres Row-Level Security and Zod-based contract validation. By centralizing business logic in shared packages and utilizing a modular monolith for the API, the system provides a scalable foundation for diverse healthcare delivery channels.