How mkmahmud/meditech_backend works
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: app.module.ts App module · payments.module.ts Payments · prisma.module.ts Prisma · auth.module.ts Auth
Components 25
App runtime
NestJS bootstrap and request pipeline
- main.ts · Application entrypoint and global HTTP setup
src/main.ts - App module · Wires global modules and feature modules together
src/app.module.ts
Shared infrastructure
Cross-cutting services and HTTP helpers
- Zod pipe · Global request validation using Zod schemas
src/common/pipes/zod-validation.pipe.ts - Response interceptor · Normalizes API responses
src/common/interceptors/response.interceptor.ts - Auth decorators · Helpers for current user and auth metadata
src/common/decorators/auth.decorator.ts - Current user · Injects request-scoped identity into handlers
src/common/decorators/current-user.decorator.ts - Encryption · Shared field encryption for sensitive data
src/common/encryption/encryption.module.ts
Domain modules
Feature modules for identity, clinical workflows, and operations
- Auth · JWT auth, guards, and role-based access control
src/modules/auth/auth.module.ts - Users · Central account model and user-facing profile logic
src/modules/users/users.module.ts - Patients · Patient profile and related access surface
src/modules/patients/patients.module.ts - Doctors · Doctor profile and staff-specific logic
src/modules/doctors/doctors.module.ts - Appointments · Scheduling and visit coordination
src/modules/appointments/appointments.module.ts - Prescriptions · Prescription capture and management
src/modules/prescriptions/prescriptions.module.ts - Vital signs · Structured clinical measurements and capture
src/modules/vitalsigns/vitalsigns.module.ts - Lab results · Boundary for lab result handling
src/modules/lab-results/lab-results.module.ts - Overview · Cross-domain dashboard and landing views
src/modules/overview/overview.module.ts - Insurance · Coverage and verification boundary
src/modules/insurance/insurance.module.ts - Payments · Payment processing and webhook reconciliation
src/modules/payments/payments.module.ts - Notifications · API and websocket delivery for alerts and reminders
src/modules/notifications/notifications.module.ts - Audit · Traceability and access logging boundary
src/modules/audit/audit.module.ts
Data and externals
Primary datastore, storage, and third-party integrations
- Prisma · Shared PostgreSQL data access layer
src/common/prisma/prisma.module.ts - Redis · Shared ephemeral state and caching layer
src/common/redis/redis.module.ts - S3 storage · Shared object storage module with controller surface
src/common/s3/s3.module.ts - Schema · Prisma schema and migrations for relational persistence
prisma/schema.prisma - Gateway providers · Card, PayPal, and Stripe provider implementations
src/modules/payments/providers/stripe.provider.ts
Connections 48
- 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