How alagu006/hms-part-2 works
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: src/modules Ops domains · shared Shared services · app.js API app · src/modules Role modules
Components 17
Client
React/Vite SPA and shared UI/runtime
- App shell · Route-level SPA entry that swaps role screens and public views.
client/src/App.jsx - Role modules · Role-specific dashboards and workflows for clinical and operational users.
client/src/modules - Shared UI · Reusable chrome and widgets such as layout, nav, tables, search, uploads, and warnings.
client/src/shared/components - Shared runtime · Cross-cutting client logic for auth, dark mode, inactivity, shortcuts, sockets, crypto, and state.
client/src/shared - PWA assets · Manifest, service worker, and offline packaging for the built client.
client/public/manifest.json
Server
Express API, domains, and shared infrastructure
- API app · Server composition root that wires middleware, routes, and runtime services.
server/src/app.js - Security layer · Authentication, RBAC, ownership, audit, validation, and rate limiting boundaries.
server/src/shared/middleware - Core domains · Primary clinical and operational bounded contexts such as patients, appointments, doctors, vitals, prescriptions, discharge, billing, inventory, and departments.
server/src/modules - Ops domains · 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 · Common services for Redis, email, notifications, web push, PDF generation, UUIDs, and PostgreSQL helpers.
server/src/shared - Async jobs · Queued and scheduled background processing such as midnight flush, notifications, and report jobs.
server/src/shared/jobs - Realtime socket · Live event channel for messaging, notifications, and telemedicine interactions.
server/src/socket.js
Data & Integrations
Persistence, realtime, async jobs, and external services
- PostgreSQL · System of record with migrations, schema, seeds, and pgcrypto-backed encryption.
server/src/db/schema.sql - Redis · Shared backing store for caching, rate limiting, realtime support, and job coordination.
server/src/shared/services/redis.service.js - Email/Push · SMTP/Mailhog and browser web push delivery for notifications and alerts.
server/src/shared/services/mailer.js - Razorpay · External payment provider used by billing flows.
server/src/modules/billing/billing.service.js - AI providers · Configurable chatbot and CDS integrations for decision support features.
server/src/modules/chatbot/chatbot.service.js
Connections 21
- 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.