# alagu006/hms-part-2 architecture

> Architecture diagram of the GitHub repository alagu006/hms-part-2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alagu006/hms-part-2
- Repository: https://github.com/alagu006/hms-part-2

## Overview

1. This is a two-tier monorepo for a hospital management system: a React/Vite single-page client in `client/` and an Express/Node API in `server/`. The architecture is domain-driven, with both sides split into feature modules that map to hospital roles and workflows.

2. The client is organized around role-specific screens rather than generic pages. The `client/src/modules/` tree contains dashboards and workflows for admin, doctor, nurse, patient, lab, pharmacy, billing, inventory, telemedicine, security, HR, IT, and other roles. `App.jsx` and React Router provide the route-level shell that swaps these module views in and out.

3. Shared client UI lives in `client/src/shared/components/`, and it acts as the cross-cutting presentation layer: app layout, sidebar/navbar, tables, breadcrumbs, search, notifications, session timeout warnings, encrypted upload/download controls, and mobile navigation. This keeps role modules focused on business UI rather than chrome and utility behavior.

4. The client also has shared runtime logic in `client/src/shared/hooks/` and `client/src/shared/utils/`. These handle concerns like dark mode, auth/session handling, inactivity timeout, keyboard shortcuts, notifications, CSRF/header setup, socket URL selection, and client-side crypto/session key management. State is centralized through `client/src/shared/store/`.

5. The client-side data flow is typical SPA API consumption: React components issue requests through shared API utilities, TanStack Query manages server-state caching/fetching, and Socket.io is used for live events. Session-based auth is browser-managed, with JWT and encryption keys stored in session/sessionStorage as indicated in the README and utility layout.

6. The server is a modular Express application with one folder per business capability under `server/src/modules/`. Each domain generally follows a controller → service → routes → schema pattern, which makes the backend easy to diagram as a set of bounded contexts rather than a single layered blob.

7. Core backend domains include auth, patients, appointments, doctors, vitals, prescriptions, discharge, billing, inventory, blood bank, departments, leaves, shifts, visitors, incidents, lab orders, nursing assignments, handover notes, telemedicine, messaging, analytics, admin, and more. This mirrors the clinical and operational workflows exposed in the client and is the primary business surface of the system.

8. Cross-cutting backend behavior sits in `server/src/shared/`: authentication, RBAC, ownership checks, audit logging, validation, rate limiting, Redis access, email/mailer, notification delivery, web push, PDF generation, UUID helpers, and PostgreSQL pool/encryption helpers. These are the main architectural boundaries around all domain modules.

9. Persistence is centered on PostgreSQL. Database structure is managed through SQL migrations in `server/src/db/migrations/`, schema files, seed scripts, and shared DB helpers. The README also indicates `pgcrypto`-backed field-level encryption, which is important for the data boundary in any diagram.

10. Async and realtime work are separate concerns. Redis plus BullMQ-backed job infrastructure supports queued tasks such as notifications, report generation, and other background processing, while Socket.io handles live updates for messaging, notifications, and telemedicine-related interactions. The server also has a telemedicine worker module, reinforcing that some workflows are offloaded from request/response handling.

11. External integrations materially shape the system: SMTP/Mailhog for email, Razorpay for billing/payment flows, browser Web Push for notifications, and configurable AI providers for the chatbot/CDS features. The telemedicine and messaging modules also imply encrypted, realtime communication channels rather than purely synchronous APIs.

12. Security is a first-class architectural layer. The system uses RS256 JWTs, Argon2id passwords, CSRF protection, RBAC for 19 roles, audit middleware, and encryption for files and selected database fields. This means most request paths are gated by auth/role/ownership middleware before they reach business services.

13. Operationally, the repo includes Docker Compose for local infrastructure, a Vite build for the client, and a separate Node server runtime. The presence of `client/dist/`, service workers, manifests, and offline-related assets shows the client is also packaged as a PWA-like app, while the server remains the source of truth for data, security, and background processing.

14. For an architecture diagram, the clearest boundaries are: browser UI modules on the left, Express API and middleware in the center, PostgreSQL/Redis/Mailhog and external services on the right, with Socket.io and BullMQ crossing the request boundary for realtime and async work. The system is best drawn as a role-based clinical/operational SPA backed by a modular, security-heavy API.

Main entry points: [`server/src/modules`](https://github.com/alagu006/hms-part-2/tree/main/server/src/modules) (Ops domains), [`server/src/shared`](https://github.com/alagu006/hms-part-2/tree/main/server/src/shared) (Shared services), [`server/src/app.js`](https://github.com/alagu006/hms-part-2/blob/main/server/src/app.js) (API app), [`client/src/modules`](https://github.com/alagu006/hms-part-2/tree/main/client/src/modules) (Role modules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_client_app["App shell<br/>React router shell<br/>[App.jsx]"]
  node_client_modules["Role modules<br/>feature screens"]
  node_client_shared_ui["Shared UI<br/>presentation kit"]
  node_client_shared_logic["Shared runtime<br/>hooks/utils/store"]
  node_client_pwa["PWA assets<br/>service worker<br/>[manifest.json]"]
end

subgraph group_server["Server"]
  node_server_app["API app<br/>Express bootstrap<br/>[app.js]"]
  node_server_authz["Security layer<br/>middleware"]
  node_server_domains_a["Core domains<br/>business modules"]
  node_server_domains_b["Ops domains<br/>support modules"]
  node_server_shared["Shared services<br/>infrastructure code"]
  node_server_jobs["Async jobs<br/>BullMQ workers"]
  node_server_socket(("Realtime socket<br/>Socket.io<br/>[socket.js]"))
end

subgraph group_data["Data & Integrations"]
  node_db[("PostgreSQL<br/>primary database<br/>[schema.sql]")]
  node_redis[("Redis<br/>cache/queue<br/>[redis.service.js]")]
  node_external_email["Email/Push<br/>external delivery<br/>[mailer.js]"]
  node_external_payments["Razorpay<br/>payment gateway<br/>[billing.service.js]"]
  node_external_ai["AI providers<br/>llm integration<br/>[chatbot.service.js]"]
end

node_client_app -->|"routes to"| node_client_modules
node_client_app -->|"composes"| node_client_shared_ui
node_client_modules -->|"uses"| node_client_shared_ui
node_client_modules -->|"uses"| node_client_shared_logic
node_client_shared_logic -->|"API calls"| node_server_app
node_client_shared_logic -->|"connects"| node_server_socket
node_client_pwa -->|"packages"| node_client_app
node_server_app -->|"guards with"| node_server_authz
node_server_app -->|"mounts"| node_server_domains_a
node_server_app -->|"mounts"| node_server_domains_b
node_server_domains_a -->|"depends on"| node_server_shared
node_server_domains_b -->|"depends on"| node_server_shared
node_server_domains_b -->|"enqueues"| node_server_jobs
node_server_domains_b -->|"emits"| node_server_socket
node_server_shared -->|"reads/writes"| node_db
node_server_shared -->|"uses"| node_redis
node_server_shared -->|"delivers"| node_external_email
node_server_domains_a -->|"charges via"| node_external_payments
node_server_domains_b -->|"calls"| node_external_ai
node_server_jobs -->|"persists"| node_db
node_server_jobs -->|"notifies"| node_external_email

click node_client_app "https://github.com/alagu006/hms-part-2/blob/main/client/src/App.jsx"
click node_client_modules "https://github.com/alagu006/hms-part-2/tree/main/client/src/modules"
click node_client_shared_ui "https://github.com/alagu006/hms-part-2/tree/main/client/src/shared/components"
click node_client_shared_logic "https://github.com/alagu006/hms-part-2/tree/main/client/src/shared"
click node_client_pwa "https://github.com/alagu006/hms-part-2/blob/main/client/public/manifest.json"
click node_server_app "https://github.com/alagu006/hms-part-2/blob/main/server/src/app.js"
click node_server_authz "https://github.com/alagu006/hms-part-2/tree/main/server/src/shared/middleware"
click node_server_domains_a "https://github.com/alagu006/hms-part-2/tree/main/server/src/modules"
click node_server_domains_b "https://github.com/alagu006/hms-part-2/tree/main/server/src/modules"
click node_server_shared "https://github.com/alagu006/hms-part-2/tree/main/server/src/shared"
click node_server_jobs "https://github.com/alagu006/hms-part-2/tree/main/server/src/shared/jobs"
click node_server_socket "https://github.com/alagu006/hms-part-2/blob/main/server/src/socket.js"
click node_db "https://github.com/alagu006/hms-part-2/blob/main/server/src/db/schema.sql"
click node_redis "https://github.com/alagu006/hms-part-2/blob/main/server/src/shared/services/redis.service.js"
click node_external_email "https://github.com/alagu006/hms-part-2/blob/main/server/src/shared/services/mailer.js"
click node_external_payments "https://github.com/alagu006/hms-part-2/blob/main/server/src/modules/billing/billing.service.js"
click node_external_ai "https://github.com/alagu006/hms-part-2/blob/main/server/src/modules/chatbot/chatbot.service.js"

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_client_app,node_client_modules,node_client_shared_ui,node_client_shared_logic,node_client_pwa toneBlue
class node_server_app,node_server_authz,node_server_domains_a,node_server_domains_b,node_server_shared,node_server_jobs,node_server_socket toneAmber
class node_db,node_redis,node_external_email,node_external_payments,node_external_ai toneMint
```

## Components

### Client

React/Vite SPA and shared UI/runtime

- [App shell](https://github.com/alagu006/hms-part-2/blob/main/client/src/App.jsx): React router shell · Route-level SPA entry that swaps role screens and public views. · `client/src/App.jsx`
- [Role modules](https://github.com/alagu006/hms-part-2/tree/main/client/src/modules): feature screens · Role-specific dashboards and workflows for clinical and operational users. · `client/src/modules`
- [Shared UI](https://github.com/alagu006/hms-part-2/tree/main/client/src/shared/components): presentation kit · Reusable chrome and widgets such as layout, nav, tables, search, uploads, and warnings. · `client/src/shared/components`
- [Shared runtime](https://github.com/alagu006/hms-part-2/tree/main/client/src/shared): hooks/utils/store · Cross-cutting client logic for auth, dark mode, inactivity, shortcuts, sockets, crypto, and state. · `client/src/shared`
- [PWA assets](https://github.com/alagu006/hms-part-2/blob/main/client/public/manifest.json): service worker · Manifest, service worker, and offline packaging for the built client. · `client/public/manifest.json`

### Server

Express API, domains, and shared infrastructure

- [API app](https://github.com/alagu006/hms-part-2/blob/main/server/src/app.js): Express bootstrap · Server composition root that wires middleware, routes, and runtime services. · `server/src/app.js`
- [Security layer](https://github.com/alagu006/hms-part-2/tree/main/server/src/shared/middleware): middleware · Authentication, RBAC, ownership, audit, validation, and rate limiting boundaries. · `server/src/shared/middleware`
- [Core domains](https://github.com/alagu006/hms-part-2/tree/main/server/src/modules): business modules · Primary clinical and operational bounded contexts such as patients, appointments, doctors, vitals, prescriptions, discharge, billing, inventory, and departments. · `server/src/modules`
- [Ops domains](https://github.com/alagu006/hms-part-2/tree/main/server/src/modules): support modules · Supporting workflows including auth, admin, analytics, lab orders, nursing, telemedicine, messaging, leaves, shifts, visitors, incidents, blood bank, and OT scheduling. · `server/src/modules`
- [Shared services](https://github.com/alagu006/hms-part-2/tree/main/server/src/shared): infrastructure code · Common services for Redis, email, notifications, web push, PDF generation, UUIDs, and PostgreSQL helpers. · `server/src/shared`
- [Async jobs](https://github.com/alagu006/hms-part-2/tree/main/server/src/shared/jobs): BullMQ workers · Queued and scheduled background processing such as midnight flush, notifications, and report jobs. · `server/src/shared/jobs`
- [Realtime socket](https://github.com/alagu006/hms-part-2/blob/main/server/src/socket.js): Socket.io · Live event channel for messaging, notifications, and telemedicine interactions. · `server/src/socket.js`

### Data & Integrations

Persistence, realtime, async jobs, and external services

- [PostgreSQL](https://github.com/alagu006/hms-part-2/blob/main/server/src/db/schema.sql): primary database · System of record with migrations, schema, seeds, and pgcrypto-backed encryption. · `server/src/db/schema.sql`
- [Redis](https://github.com/alagu006/hms-part-2/blob/main/server/src/shared/services/redis.service.js): cache/queue · Shared backing store for caching, rate limiting, realtime support, and job coordination. · `server/src/shared/services/redis.service.js`
- [Email/Push](https://github.com/alagu006/hms-part-2/blob/main/server/src/shared/services/mailer.js): external delivery · SMTP/Mailhog and browser web push delivery for notifications and alerts. · `server/src/shared/services/mailer.js`
- [Razorpay](https://github.com/alagu006/hms-part-2/blob/main/server/src/modules/billing/billing.service.js): payment gateway · External payment provider used by billing flows. · `server/src/modules/billing/billing.service.js`
- [AI providers](https://github.com/alagu006/hms-part-2/blob/main/server/src/modules/chatbot/chatbot.service.js): llm integration · Configurable chatbot and CDS integrations for decision support features. · `server/src/modules/chatbot/chatbot.service.js`

## Connections

- App shell → Role modules: routes to · Router swaps role screens and public views.
- App shell → Shared UI: composes · App shell uses shared layout and controls.
- Role modules → Shared UI: uses · Feature screens reuse common presentation components.
- Role modules → Shared runtime: uses · Modules depend on shared client hooks, utils, and state.
- Shared runtime → API app: API calls · Client utilities issue authenticated requests to the backend.
- Shared runtime → Realtime socket: connects · Client subscribes to live events over Socket.io.
- PWA assets → App shell: packages · Client is delivered as an installable/offline-capable web app.
- API app → Security layer: guards with · Requests pass through security and validation middleware.
- API app → Core domains: mounts · Express routes expose core business domains.
- API app → Ops domains: mounts · Express routes expose supporting operational domains.
- Core domains → Shared services: depends on · Domains use shared DB, notification, and helper services.
- Ops domains → Shared services: depends on · Supporting modules share common infrastructure services.
- Ops domains → Async jobs: enqueues · Some workflows are deferred to background processing.
- Ops domains → Realtime socket: emits · Messaging, telemedicine, and alerts use realtime events.
- Shared services → PostgreSQL: reads/writes · PostgreSQL is the system of record.
- Shared services → Redis: uses · Redis backs caching, coordination, and queue support.
- Shared services → Email/Push: delivers · Notifications and mail are sent through SMTP/web push paths.
- Core domains → Razorpay: charges via · Billing workflows integrate with the payment gateway.
- Ops domains → AI providers: calls · Chatbot and CDS features can use external AI providers.
- Async jobs → PostgreSQL: persists · Background workers update or generate database-backed outputs.
- Async jobs → Email/Push: notifies · Queued jobs can trigger email and push delivery.
