# mkmahmud/meditech_backend architecture

> Architecture diagram of the GitHub repository mkmahmud/meditech_backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mkmahmud/meditech_backend
- Repository: https://github.com/mkmahmud/meditech_backend

## Overview

1. **Overall shape**
   - This is a **NestJS modular monolith** backend, not a microservice system.
   - The application exposes a versioned HTTP API under `/api/v1`, with Swagger/OpenAPI docs for contract discovery.
   - Domain logic is split by feature modules under `src/modules`, while reusable infrastructure lives under `src/common`.

2. **Request lifecycle**
   - Incoming requests enter through `main.ts` and are processed by Nest middleware/pipes/guards/interceptors.
   - Validation is handled with a **global Zod validation pipe** rather than class-validator DTOs.
   - Responses are normalized through a **global response interceptor**, and audit logging is injected via a dedicated interceptor in the audit module.

3. **Security boundary**
   - Authentication is JWT-based with **access and refresh tokens**.
   - Authorization uses **role-based guards** and decorators; roles are modeled around healthcare staff and patients.
   - `current-user` and `auth` decorators provide request-scoped identity data to controllers.
   - A dedicated **JWT strategy** and guards form the main auth boundary around protected endpoints.

4. **Persistence layer**
   - The primary datastore is **PostgreSQL**, accessed through **Prisma**.
   - `prisma/schema.prisma`, migrations, and `seed.ts` define the schema evolution and bootstrap data.
   - The Prisma service/module is a shared infrastructure dependency used across feature modules.

5. **Shared infrastructure services**
   - **Redis** is available as a cross-cutting service for caching/session-like state and fast ephemeral data.
   - **AWS S3** is used for file storage, especially medical documents; the S3 module exposes both service and controller surfaces.
   - **Encryption** is a shared service for protecting sensitive PHI-like fields at rest, separate from transport security.

6. **Core identity and master-data modules**
   - `auth`, `users`, `patients`, and `doctors` form the identity and profile layer.
   - `users` is the central system account model; `patients` and `doctors` are role-specific clinical profiles layered on top.
   - These modules are likely the hub for authorization checks and user-facing profile retrieval.

7. **Clinical workflow modules**
   - `appointments`, `prescriptions`, `vitalsigns`, and `lab-results` represent the main healthcare workflow surfaces.
   - `appointments` manages scheduling and is likely one of the highest-throughput transactional paths.
   - `prescriptions` and `vitalsigns` each include Zod schemas, indicating structured input validation for clinical data capture.
   - `lab-results` exists as a module boundary even though the tree shows it as relatively thin, suggesting a planned or partially implemented domain.

8. **Administrative and summary views**
   - `overview` appears to aggregate cross-domain data for dashboards or role-based landing pages.
   - `insurance` exists as its own module boundary, likely supporting verification and coverage metadata rather than core clinical flow.
   - These modules sit above the data model, combining outputs from patients, appointments, billing, and clinical records.

9. **Payments subsystem**
   - Payments are isolated in a dedicated module with a separate webhook controller/service pair.
   - Provider abstraction is explicit: there are separate adapters for **card**, **PayPal**, and **Stripe**.
   - A payment migration was added in Prisma, so billing is persisted in the same relational store as the rest of the platform.
   - This module is designed around external gateway integration plus asynchronous webhook reconciliation.

10. **Notifications and realtime events**
   - `notifications` includes both a controller and a **WebSocket gateway**, so it supports both request/response and push-style delivery.
   - The module likely bridges application events to clinicians/patients for reminders, status changes, or operational alerts.
   - This is the main realtime boundary in the repo.

11. **Audit and compliance**
   - `audit` is a standalone module with an interceptor, service, and controller, reflecting HIPAA-style traceability requirements.
   - The audit interceptor is the key mechanism for recording PHI access and mutations across the app.
   - This is a compliance boundary rather than a business feature: it cross-cuts multiple modules and is designed to observe, not own, domain data.

12. **Schema and validation conventions**
   - Each major feature tends to define a `schemas/*.schema.ts` file using Zod.
   - That makes the runtime contract explicit at the module boundary and keeps validation close to the feature.
   - Swagger support is layered on top, so the repo has both runtime validation and generated API documentation.

13. **Operational and testing surfaces**
   - `load-tests/prescriptions-loadtest.artillery.yml` shows the repo includes performance testing for at least one clinical workflow.
   - `users.service.spec.ts` indicates unit testing is in place for core service logic.
   - Nest CLI and TypeScript build configs define the compilation/runtime boundary; this is a backend-only codebase with no frontend app in the tree.

14. **Architecture diagram guidance**
   - Draw the app as a central NestJS API layer with domain modules around it.
   - Put **PostgreSQL/Prisma** at the core persistence layer, with **Redis**, **S3**, and **external payment providers** as adjacent infrastructure.
   - Show **auth/guards/audit/encryption/validation** as cross-cutting concerns spanning multiple domain modules.
   - Mark `notifications` as the realtime edge and `payments` as the main integration-heavy boundary with third parties.

Main entry points: [`src/app.module.ts`](https://github.com/mkmahmud/meditech_backend/blob/main/src/app.module.ts) (App module), [`src/modules/payments/payments.module.ts`](https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/payments/payments.module.ts) (Payments), [`src/common/prisma/prisma.module.ts`](https://github.com/mkmahmud/meditech_backend/blob/main/src/common/prisma/prisma.module.ts) (Prisma), [`src/modules/auth/auth.module.ts`](https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/auth/auth.module.ts) (Auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["App runtime"]
  node_main["main.ts<br/>bootstrap<br/>[main.ts]"]
  node_app_module["App module<br/>composition root<br/>[app.module.ts]"]
end

subgraph group_grp_common["Shared infrastructure"]
  node_zod_pipe["Zod pipe<br/>validation pipe"]
  node_resp_interceptor["Response interceptor<br/>response wrapper"]
  node_auth_decorators["Auth decorators<br/>request context<br/>[auth.decorator.ts]"]
  node_current_user["Current user<br/>request context"]
  node_encryption_module["Encryption<br/>secret service"]
end

subgraph group_grp_domain["Domain modules"]
  node_auth_module["Auth<br/>security module<br/>[auth.module.ts]"]
  node_users_module["Users<br/>identity module<br/>[users.module.ts]"]
  node_patients_module["Patients<br/>clinical profile<br/>[patients.module.ts]"]
  node_doctors_module["Doctors<br/>clinical profile<br/>[doctors.module.ts]"]
  node_appointments_module["Appointments<br/>workflow module"]
  node_prescriptions_module["Prescriptions<br/>clinical workflow"]
  node_vitalsigns_module["Vital signs<br/>clinical workflow"]
  node_lab_results_module["Lab results<br/>clinical module"]
  node_overview_module["Overview<br/>summary module<br/>[overview.module.ts]"]
  node_insurance_module["Insurance<br/>coverage module"]
  node_payments_module["Payments<br/>billing module<br/>[payments.module.ts]"]
  node_notifications_module["Notifications<br/>realtime module"]
  node_audit_module["Audit<br/>compliance module<br/>[audit.module.ts]"]
end

subgraph group_grp_data["Data and externals"]
  node_prisma_module[("Prisma<br/>db access<br/>[prisma.module.ts]")]
  node_redis_module[("Redis<br/>cache service<br/>[redis.module.ts]")]
  node_s3_module["S3 storage<br/>file storage<br/>[s3.module.ts]"]
  node_prisma_schema["Schema<br/>[schema.prisma]"]
  node_payments_providers["Gateway providers<br/>payment adapters<br/>[stripe.provider.ts]"]
end

node_main -->|"bootstraps"| node_app_module
node_main -->|"installs"| node_zod_pipe
node_main -->|"installs"| node_resp_interceptor
node_main -->|"routes to"| node_auth_module
node_app_module -->|"imports"| node_prisma_module
node_app_module -->|"imports"| node_redis_module
node_app_module -->|"imports"| node_s3_module
node_app_module -->|"imports"| node_encryption_module
node_app_module -->|"imports"| node_auth_module
node_app_module -->|"imports"| node_users_module
node_app_module -->|"imports"| node_patients_module
node_app_module -->|"imports"| node_doctors_module
node_app_module -->|"imports"| node_appointments_module
node_app_module -->|"imports"| node_prescriptions_module
node_app_module -->|"imports"| node_vitalsigns_module
node_app_module -->|"imports"| node_lab_results_module
node_app_module -->|"imports"| node_overview_module
node_app_module -->|"imports"| node_insurance_module
node_app_module -->|"imports"| node_payments_module
node_app_module -->|"imports"| node_notifications_module
node_app_module -->|"imports"| node_audit_module
node_auth_module -->|"uses"| node_prisma_module
node_auth_module -->|"authenticates"| node_users_module
node_auth_module -->|"exposes"| node_auth_decorators
node_auth_module -->|"exposes"| node_current_user
node_users_module -->|"uses"| node_prisma_module
node_patients_module -->|"extends"| node_users_module
node_doctors_module -->|"extends"| node_users_module
node_appointments_module -->|"references"| node_patients_module
node_appointments_module -->|"references"| node_doctors_module
node_prescriptions_module -->|"references"| node_patients_module
node_vitalsigns_module -->|"captures for"| node_patients_module
node_overview_module -->|"aggregates"| node_appointments_module
node_overview_module -->|"aggregates"| node_patients_module
node_overview_module -->|"aggregates"| node_payments_module
node_overview_module -->|"aggregates"| node_prescriptions_module
node_payments_module -->|"persists"| node_prisma_module
node_payments_module -->|"adapts"| node_payments_providers
node_payments_module -->|"evolves"| node_prisma_schema
node_payments_module -.->|"signals"| node_notifications_module
node_payments_module -->|"webhooks"| node_payments_module
node_notifications_module -->|"uses"| node_redis_module
node_notifications_module -.->|"observes"| node_audit_module
node_audit_module -->|"logs to"| node_prisma_module
node_audit_module -.->|"intercepts"| node_main
node_s3_module -.->|"metadata"| node_prisma_module
node_encryption_module -.->|"protects"| node_prisma_module
node_prisma_module -->|"implements"| node_prisma_schema

click node_main "https://github.com/mkmahmud/meditech_backend/blob/main/src/main.ts"
click node_app_module "https://github.com/mkmahmud/meditech_backend/blob/main/src/app.module.ts"
click node_zod_pipe "https://github.com/mkmahmud/meditech_backend/blob/main/src/common/pipes/zod-validation.pipe.ts"
click node_resp_interceptor "https://github.com/mkmahmud/meditech_backend/blob/main/src/common/interceptors/response.interceptor.ts"
click node_auth_decorators "https://github.com/mkmahmud/meditech_backend/blob/main/src/common/decorators/auth.decorator.ts"
click node_current_user "https://github.com/mkmahmud/meditech_backend/blob/main/src/common/decorators/current-user.decorator.ts"
click node_prisma_module "https://github.com/mkmahmud/meditech_backend/blob/main/src/common/prisma/prisma.module.ts"
click node_redis_module "https://github.com/mkmahmud/meditech_backend/blob/main/src/common/redis/redis.module.ts"
click node_s3_module "https://github.com/mkmahmud/meditech_backend/blob/main/src/common/s3/s3.module.ts"
click node_encryption_module "https://github.com/mkmahmud/meditech_backend/blob/main/src/common/encryption/encryption.module.ts"
click node_auth_module "https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/auth/auth.module.ts"
click node_users_module "https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/users/users.module.ts"
click node_patients_module "https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/patients/patients.module.ts"
click node_doctors_module "https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/doctors/doctors.module.ts"
click node_appointments_module "https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/appointments/appointments.module.ts"
click node_prescriptions_module "https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/prescriptions/prescriptions.module.ts"
click node_vitalsigns_module "https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/vitalsigns/vitalsigns.module.ts"
click node_lab_results_module "https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/lab-results/lab-results.module.ts"
click node_overview_module "https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/overview/overview.module.ts"
click node_insurance_module "https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/insurance/insurance.module.ts"
click node_payments_module "https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/payments/payments.module.ts"
click node_notifications_module "https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/notifications/notifications.module.ts"
click node_audit_module "https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/audit/audit.module.ts"
click node_prisma_schema "https://github.com/mkmahmud/meditech_backend/blob/main/prisma/schema.prisma"
click node_payments_providers "https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/payments/providers/stripe.provider.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_app_module toneBlue
class node_zod_pipe,node_resp_interceptor,node_auth_decorators,node_current_user,node_encryption_module toneAmber
class node_auth_module,node_users_module,node_patients_module,node_doctors_module,node_appointments_module,node_prescriptions_module,node_vitalsigns_module,node_lab_results_module,node_overview_module,node_insurance_module,node_payments_module,node_notifications_module,node_audit_module toneMint
class node_prisma_module,node_redis_module,node_s3_module,node_prisma_schema,node_payments_providers toneRose
```

## Components

### App runtime

NestJS bootstrap and request pipeline

- [main.ts](https://github.com/mkmahmud/meditech_backend/blob/main/src/main.ts): bootstrap · Application entrypoint and global HTTP setup · `src/main.ts`
- [App module](https://github.com/mkmahmud/meditech_backend/blob/main/src/app.module.ts): composition root · Wires global modules and feature modules together · `src/app.module.ts`

### Shared infrastructure

Cross-cutting services and HTTP helpers

- [Zod pipe](https://github.com/mkmahmud/meditech_backend/blob/main/src/common/pipes/zod-validation.pipe.ts): validation pipe · Global request validation using Zod schemas · `src/common/pipes/zod-validation.pipe.ts`
- [Response interceptor](https://github.com/mkmahmud/meditech_backend/blob/main/src/common/interceptors/response.interceptor.ts): response wrapper · Normalizes API responses · `src/common/interceptors/response.interceptor.ts`
- [Auth decorators](https://github.com/mkmahmud/meditech_backend/blob/main/src/common/decorators/auth.decorator.ts): request context · Helpers for current user and auth metadata · `src/common/decorators/auth.decorator.ts`
- [Current user](https://github.com/mkmahmud/meditech_backend/blob/main/src/common/decorators/current-user.decorator.ts): request context · Injects request-scoped identity into handlers · `src/common/decorators/current-user.decorator.ts`
- [Encryption](https://github.com/mkmahmud/meditech_backend/blob/main/src/common/encryption/encryption.module.ts): secret service · Shared field encryption for sensitive data · `src/common/encryption/encryption.module.ts`

### Domain modules

Feature modules for identity, clinical workflows, and operations

- [Auth](https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/auth/auth.module.ts): security module · JWT auth, guards, and role-based access control · `src/modules/auth/auth.module.ts`
- [Users](https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/users/users.module.ts): identity module · Central account model and user-facing profile logic · `src/modules/users/users.module.ts`
- [Patients](https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/patients/patients.module.ts): clinical profile · Patient profile and related access surface · `src/modules/patients/patients.module.ts`
- [Doctors](https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/doctors/doctors.module.ts): clinical profile · Doctor profile and staff-specific logic · `src/modules/doctors/doctors.module.ts`
- [Appointments](https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/appointments/appointments.module.ts): workflow module · Scheduling and visit coordination · `src/modules/appointments/appointments.module.ts`
- [Prescriptions](https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/prescriptions/prescriptions.module.ts): clinical workflow · Prescription capture and management · `src/modules/prescriptions/prescriptions.module.ts`
- [Vital signs](https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/vitalsigns/vitalsigns.module.ts): clinical workflow · Structured clinical measurements and capture · `src/modules/vitalsigns/vitalsigns.module.ts`
- [Lab results](https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/lab-results/lab-results.module.ts): clinical module · Boundary for lab result handling · `src/modules/lab-results/lab-results.module.ts`
- [Overview](https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/overview/overview.module.ts): summary module · Cross-domain dashboard and landing views · `src/modules/overview/overview.module.ts`
- [Insurance](https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/insurance/insurance.module.ts): coverage module · Coverage and verification boundary · `src/modules/insurance/insurance.module.ts`
- [Payments](https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/payments/payments.module.ts): billing module · Payment processing and webhook reconciliation · `src/modules/payments/payments.module.ts`
- [Notifications](https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/notifications/notifications.module.ts): realtime module · API and websocket delivery for alerts and reminders · `src/modules/notifications/notifications.module.ts`
- [Audit](https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/audit/audit.module.ts): compliance module · Traceability and access logging boundary · `src/modules/audit/audit.module.ts`

### Data and externals

Primary datastore, storage, and third-party integrations

- [Prisma](https://github.com/mkmahmud/meditech_backend/blob/main/src/common/prisma/prisma.module.ts): db access · Shared PostgreSQL data access layer · `src/common/prisma/prisma.module.ts`
- [Redis](https://github.com/mkmahmud/meditech_backend/blob/main/src/common/redis/redis.module.ts): cache service · Shared ephemeral state and caching layer · `src/common/redis/redis.module.ts`
- [S3 storage](https://github.com/mkmahmud/meditech_backend/blob/main/src/common/s3/s3.module.ts): file storage · Shared object storage module with controller surface · `src/common/s3/s3.module.ts`
- [Schema](https://github.com/mkmahmud/meditech_backend/blob/main/prisma/schema.prisma): postgres schema · Prisma schema and migrations for relational persistence · `prisma/schema.prisma`
- [Gateway providers](https://github.com/mkmahmud/meditech_backend/blob/main/src/modules/payments/providers/stripe.provider.ts): payment adapters · Card, PayPal, and Stripe provider implementations · `src/modules/payments/providers/stripe.provider.ts`

## Connections

- main.ts → App module: bootstraps · Starts the Nest application through the composition root
- main.ts → Zod pipe: installs · Registers global validation behavior
- main.ts → Response interceptor: installs · Registers response normalization globally
- main.ts → Auth: routes to · Publishes protected API endpoints
- App module → Prisma: imports · Shares database access across feature modules
- App module → Redis: imports · Provides cross-cutting cache/state services
- App module → S3 storage: imports · Exposes object storage to the app
- App module → Encryption: imports · Makes field encryption available to domains
- App module → Auth: imports · Composes security boundary
- App module → Users: imports · Composes identity module
- App module → Patients: imports · Composes clinical profile module
- App module → Doctors: imports · Composes clinical profile module
- App module → Appointments: imports · Composes scheduling workflow
- App module → Prescriptions: imports · Composes clinical workflow
- App module → Vital signs: imports · Composes clinical workflow
- App module → Lab results: imports · Composes lab result boundary
- App module → Overview: imports · Composes dashboard views
- App module → Insurance: imports · Composes coverage module
- App module → Payments: imports · Composes billing integration
- App module → Notifications: imports · Composes realtime delivery
- App module → Audit: imports · Composes compliance tracing
- Auth → Prisma: uses · Persists and reads identity data
- Auth → Users: authenticates · Validates user accounts and roles
- Auth → Auth decorators: exposes · Provides auth-related request helpers
- Auth → Current user: exposes · Provides request-scoped identity injection
- Users → Prisma: uses · Stores central user accounts
- Patients → Users: extends · Builds patient profile on top of user accounts
- Doctors → Users: extends · Builds doctor profile on top of user accounts
- Appointments → Patients: references · Schedules visits for patients
- Appointments → Doctors: references · Assigns clinicians to visits
- Prescriptions → Patients: references · Associates prescriptions with patients
- Vital signs → Patients: captures for · Records measurements against patient profiles
- Overview → Appointments: aggregates · Summarizes scheduling data
- Overview → Patients: aggregates · Summarizes patient data
- Overview → Payments: aggregates · Summarizes billing status
- Overview → Prescriptions: aggregates · Summarizes clinical activity
- Payments → Prisma: persists · Stores billing records in PostgreSQL
- Payments → Gateway providers: adapts · Delegates to gateway-specific providers
- Payments → Schema: evolves · Adds payment tables through Prisma migrations
- Payments → Notifications: signals · Can trigger payment-related notifications
- Payments → Payments: webhooks · Webhook controller and service handle asynchronous reconciliation
- Notifications → Redis: uses · Supports fast ephemeral delivery state
- Notifications → Audit: observes · Notification actions can be traced
- Audit → Prisma: logs to · Stores audit records in the shared database
- Audit → main.ts: intercepts · Wraps request processing for traceability
- S3 storage → Prisma: metadata · Can persist storage metadata alongside relational data
- Encryption → Prisma: protects · Encrypts sensitive data before persistence
- Prisma → Schema: implements · Executes schema and migration state