Monorepo Structure & Tooling
Relevant source files
The following files were used as context for generating this wiki page:
The Digital Healthcare Platform uses a single TypeScript monorepo to manage its web, mobile, and backend components. This architecture ensures type safety across the entire stack and facilitates code sharing through internal packages while maintaining strict boundaries between applications.
The repository uses pnpm workspaces for package management and Turborepo for task orchestration. Shared business rules, design tokens, and API contracts reside in the packages/ directory, while deployable units such as the Fastify API and Next.js web application are located in apps/.
Sources: README.md:1-15, package.json:1-10
Architecture Overview
The project organizes code into two primary directories: apps/ for deployable services and packages/ for shared libraries. Applications interact with shared code via internal workspace references, but the linting rules prohibit applications from importing each other directly.
Workspace Components
| Category | Path | Description |
|---|---|---|
| Apps | apps/api | Fastify modular monolith providing REST endpoints under /v1. |
apps/web | Next.js application for patient portal, staff dashboard, and public site. | |
apps/workers | Background workers using BullMQ and Redis for async tasks like PDFs and webhooks. | |
apps/mobile | Expo-based React Native app for Patient and Clinic variants. | |
apps/e2e | Playwright browser tests for end-to-end verification. | |
| Packages | packages/db | Prisma schema and migrations with Postgres row-level security. |
packages/contracts | Zod schemas serving as the source of truth for API and OpenAPI 3.1. | |
packages/api-client | Typed fetch client used by web and mobile platforms. | |
packages/domain | Shared business logic (e.g., UHID generation, currency in paise). | |
packages/config | Shared TypeScript and ESLint configurations. |
Sources: README.md:17-43, apps/api/package.json:1-10, apps/web/package.json:1-10
Dependency Graph
The following diagram illustrates the relationship between the core applications and shared packages.
Task Orchestration with Turborepo
Turborepo manages the build pipeline and task execution across the workspace. It optimizes execution by caching outputs and respecting dependency orders defined in turbo.json.
Pipeline Definitions
Turborepo defines tasks that govern how the project builds, tests, and lints.
- Build: Depends on the build and generation tasks of upstream dependencies. It outputs files to
dist/and.next/directories. - Typecheck: Runs TypeScript validation after ensuring generated types (like Prisma or Zod-to-OpenAPI) are present.
- Test:Integration: Executes tests requiring a database, specifically utilizing the
TEST_DATABASE_URLenvironment variable without caching.
{
"tasks": {
"build": {
"dependsOn": ["^build", "generate", "^generate"],
"outputs": ["dist/**", ".next/**", "!.next/cache/**"]
},
"test:integration": {
"dependsOn": ["generate", "^generate"],
"cache": false,
"env": ["TEST_DATABASE_URL"]
}
}
}
Sources: turbo.json:1-35
Development Workflow
The monorepo provides standardized scripts in the root package.json to manage the local development environment.
Core Scripts
pnpm dev: Runsturbo run devto start all applications in development mode.pnpm check: Executes a comprehensive suite including linting, typechecking, unit tests, and builds for every package.pnpm db:up: Uses Docker Compose to start Postgres 16 and Redis 7.pnpm db:seed: Populates the database with a demo clinic, staff invites, and synthetic patients.
Sources: package.json:11-25, README.md:47-65
Contract-Driven API Design
The project uses a "Contract-First" approach where packages/contracts defines the API surface area using Zod. These contracts generate the OpenAPI 3.1 specification and drive the typed @dhc/api-client.
API Definition Structure
The packages/contracts/src/openapi.ts file serves as the registry for all system operations. Each operation defines its method, path, required authentication (public vs. private), and Zod schemas for request bodies and responses.
Technical Requirements
The monorepo enforces specific tool versions to ensure environment parity:
- Node.js: Version 22 or higher (managed via
.nvmrc). - Package Manager: pnpm version 10 (enabled via
corepack). - Database: Postgres 16 and Redis 7 (via Docker).
Sources: package.json:5-9, README.md:45-46
Summary
The Monorepo Structure & Tooling provides a robust foundation for the Digital Healthcare Platform by leveraging pnpm and Turborepo. By centralizing configuration, contracts, and business logic into shared packages, the architecture ensures that breaking changes in the API or data model are immediately caught across the web and mobile applications during the typecheck and build phases of the CI pipeline.