Introduction & Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• apps/api/src/scripts/seed.ts
• apps/web/package.json
• packages/contracts/src/openapi.ts
• apps/api/src/app.test.ts

Digital Healthcare Platform is a production-grade clinic management system built as a single TypeScript monorepo. It provides a comprehensive suite of applications including a web app for staff and patients, mobile apps for iOS and Android, and a centralized Fastify-based modular monolith API. The platform handles clinic operations, patient portals, staff dashboards, and waiting-room displays.

Sources: README.md:1-5, README.md:15-18

The project is currently in Phase 0 (Foundations), featuring multi-tenancy with Postgres row-level security (RLS), audit logging, and specialized authentication flows for both patients (OTP) and staff (Password + MFA).

Sources: README.md:11-13, packages/contracts/src/openapi.ts:114-140

Repository Architecture

The platform uses pnpm workspaces and Turborepo to manage its monorepo structure. Shared logic is isolated in packages/, while deployment targets reside in apps/. Lint rules prevent apps from importing directly from each other to maintain modularity.

Sources: README.md:15-16, package.json:3-5

Core Components

Component	Path	Technology Stack
API	apps/api	Fastify, REST v1, Prisma
Workers	apps/workers	BullMQ, Redis
Web App	apps/web	Next.js
Mobile App	apps/mobile	Expo (React Native)
Database	packages/db	Postgres 16 (via Prisma)
Contracts	packages/contracts	Zod, OpenAPI 3.1

Sources: README.md:18-30, apps/web/package.json:20-30

System Data Flow

The following diagram illustrates the high-level relationship between the different monorepo workspaces and external services.

This diagram shows how applications depend on internal packages for database access and API contracts, and how the system interacts with Postgres and Redis.

Sources: README.md:18-40

Getting Started

To run the platform locally, you must meet the following software requirements:

• Node.js: version 22 or higher (enforced via .nvmrc)
• pnpm: version 10 (enabled via corepack)
• Docker: For running Postgres 16 and Redis 7 services

Sources: README.md:44-46, package.json:4-6

Local Setup Procedure

1. Install dependencies:

   pnpm install
   

2. Environment Configuration: Create a .env file from the example and generate secrets for JWT_SECRET and FIELD_ENCRYPTION_KEY.

   cp .env.example .env
   openssl rand -base64 32 # Use for keys
   

3. Start Services: Launch the infrastructure using Docker.

   pnpm db:up
   

4. Prepare Databases: Initialize the main and test databases.

   docker compose exec postgres createdb -U dhc dhc_test
   pnpm db:migrate
   

5. Seed Data: Populate the database with a demo clinic, synthetic patients, and staff invite links.

   pnpm db:seed
   

Sources: README.md:48-56, package.json:17-21

Authentication and Seeding

The platform enforces strict authentication flows. Staff members do not have default passwords; instead, the system generates invite links during seeding or admin creation.

Sources: apps/api/src/scripts/seed.ts:5-8

Staff Invite Flow

The diagram outlines the process of converting a seeded invite into an active staff account with MFA.

Sources: apps/api/src/scripts/seed.ts:40-69, packages/contracts/src/openapi.ts:114-140

Seed Personas

The db:seed script generates the following synthetic staff and patients for development (based on docs/qa/test-plan.md):

• Staff Roles: doctor, front_desk, clinic_admin.
• Demo Clinic: Slug demo-clinic, name "Demo Clinic".
• Patients: Includes personas such as "Asha Verma", "Ravi Mehra", and "Kamla Devi" with fictional phone numbers.
• Clinical Setup: Configures "In-person" and "Video" consultation types and sets a weekly schedule for the demo doctor.

Sources: apps/api/src/scripts/seed.ts:32-36, apps/api/src/scripts/seed.ts:72-80, apps/api/src/scripts/seed.ts:120-135

Development Operations

Common CLI Commands

Task	Command	Description
Verify Project	pnpm check	Runs lint, typecheck, unit tests, and build.
Integration Tests	pnpm test:integration	Runs auth and tenant-isolation suites.
E2E Tests	pnpm test:e2e	Runs Playwright browser tests.
Format	pnpm format	Runs Prettier across the monorepo.
Start API	pnpm --filter @dhc/api dev	Runs the API at localhost:4000.
Start Web	pnpm --filter @dhc/web dev	Runs the Web app at localhost:3000.

Sources: README.md:65-71, package.json:11-23

API Health and Specification

The API exposes a health check and its OpenAPI specification for consumer verification.

• Health Check: GET /v1/health returns service status and version.
• OpenAPI Spec: GET /v1/openapi.json provides the full API documentation in OpenAPI 3.1 format.

Sources: apps/api/src/app.test.ts:28-32, apps/api/src/app.test.ts:45-48

Conclusion

The Digital Healthcare Platform monorepo provides a robust foundation for clinic management. By strictly separating contracts, database logic, and application code, the system ensures type safety across the entire stack. New developers should start by setting up the Docker environment and using the seed script to explore the "Demo Clinic" workflows.

Sources: README.md:11-13, README.md:75-76