How duskwillow/ris-multisite works
1. This is a monorepo for a multisite RIS (Radiology Information System) with two runtime applications: a NestJS backend in apps/api and a React/Vite frontend in apps/web. Everything else is supporting infrastructure, tests, deployment, or documentation/workflow tooling.
2. The backend is organized as feature modules around clinical and administrative domains: authentication, patients, worklists, reports, exams, procedures, dashboard, admin, audit, PACS, DICOM, MLLP/MPPS, radiologues, salles, acts, TB, template CR, RIS sites, and workitems. Each module typically has a controller/service split, DTOs, entities, and query-builder helpers, which suggests a layered API over a relational datastore.
3. The main external integration boundary on the backend is the medical imaging stack. pacs, dicom, mllp, mpps, and simulator folders indicate the API talks to PACS/DICOM systems and HL7-style messaging endpoints, not just a conventional CRUD database. The test/mock-pacs directory and DICOM sample assets show that these integrations are supported locally for development and testing.
4. The backend also exposes operational endpoints for health and observability. There are dedicated health and metrics modules, plus middleware for logging and an audit subsystem with decorators, interceptors, and audit log entities. That means request handling is not just business logic; it also emits operational and compliance-related traces.
5. Auth is a distinct boundary. The backend has JWT auth, refresh-token DTOs, roles, and guards; the frontend mirrors this with a protected route component, an auth store, and token refresh hooks. So authentication state flows from login on the web app to JWT-protected API calls and then back into route/session control on the client.
6. The frontend is feature-sliced rather than page-sliced. Major feature areas are auth, dashboard, patients, TB, patientHistory, reports, validation/sansCr, worklist, and Admin. Each feature owns its components, hooks, utilities, and tests, which keeps UI logic and data-fetching orchestration near the domain it serves.
7. The UI data flow is hook-driven. Feature hooks such as useWorklistFetch, useReportData, usePatientHistoryManager, useStatistic, and useAuthLogin encapsulate API interaction and state management, while components stay presentation-focused. Shared UI primitives live under components/ui, and cross-feature layout concerns are handled by reusable layout components and protected routing.
8. Several frontend screens are direct consumers of backend operational domains rather than generic UI. For example, Admin includes PACS configuration, radiologue management, user assignment, and audit log views; reports and worklist handle radiology workflow actions; patient history combines imaging and diagnostic data; validation screens manage work items and modality/salle selection. This implies the UI is a workflow client for the RIS backend, not a general portal.
9. There is a clear persistence and domain-model layer on the API side, but the database technology is not explicit in the tree. The presence of entities, query-builder files, and connection-test scripts strongly suggests a relational database with ORM-backed models, and the check-db.js plus backup scripts reinforce that the backend depends on database connectivity and operational maintenance.
10. The repo includes simulation and test harnesses beyond unit tests. Backend simulator code can emulate PACS/RIS/modality behavior, and the web app has Playwright end-to-end coverage for authentication, dashboard, patients, and patient history flows. That means the architecture is validated at both API and browser levels, with mocked imaging infrastructure where needed.
11. Deployment is containerized and environment-specific. There are Dockerfiles for API and web, plus root docker-compose files for dev, test, staging, and production. NGINX configs, Prometheus, Alertmanager, and postgres-exporter configs indicate a runtime stack that likely front-ends the web app, proxies the API, and exposes monitoring for the database and services.
12. The repository also carries OHIF config and scripts for SSL, backups, and deployment, which signals that the system is meant to live in a radiology environment with imaging viewer integration and operational automation. The image-viewing concern is adjacent to the RIS app but still part of the deployment architecture.
13. The _bmad and web-bundles trees are not product runtime code; they are an embedded agent/workflow framework for analysis, planning, architecture, testing, and documentation generation. They form a separate tooling subsystem that supports engineering processes, but they do not participate in the application request/data path.
14. For an architecture diagram, the main boxes should be: browser-based React client, NestJS API, relational database, PACS/DICOM/HL7 external imaging systems, and observability/deployment infrastructure. Around that, show auth/token flow, audit logging, and the simulator/mock-PACS path used for local/test environments.
Main entry points: api API app · docker-compose.yml Compose stack · web Web app · pacs Imaging stack
Components 23
Runtime apps
Primary application runtimes for the RIS product.
- Web app · Browser RIS UI with feature-sliced workflows and hook-driven data flow.
apps/web - API app · Main RIS backend with feature modules, relational persistence, and external integrations.
apps/api - Auth · Login, refresh tokens, roles, guards, and protected session flow.
apps/api/src/auth - Clinical modules · Patients, worklists, reports, exams, procedures, workitems, dashboard, admin, and related operational features.
apps/api/src - Imaging stack · PACS, DICOM, MLLP/MPPS, and simulator boundaries for imaging-system integration.
apps/api/src/pacs - Ops endpoints · Health checks, metrics, logging middleware, and audit interceptors/logs.
apps/api/src/health - Data model · Relational domain entities, query builders, and persistence-facing services.
apps/api/src/patients/entities - Patients UI · Patient browsing and patient-centric workflow views.
apps/web/src/features/Patients - Worklist UI · Worklist and PACS/study handling for radiology workflow actions.
apps/web/src/features/worklist - Reports UI · Report editing, templates, dosimetry, and workitem-driven report flows.
apps/web/src/features/reports - Admin UI · Administration screens for PACS config, radiologues, users, procedures, assignments, and audit logs.
apps/web/src/features/Admin - History UI · Patient history and imaging/diagnostic history orchestration.
apps/web/src/features/patientHistory - Validation UI · Sans CR validation workflow with modality and salle selection.
apps/web/src/features/validation/sansCr - Dashboard UI · Operational summary, activity charts, and recent exam views.
apps/web/src/features/dashboard - Shared UI · Reusable layout, protected routing, UI primitives, stores, and shared hooks/services.
apps/web/src/components
Delivery & ops
Deployment, proxying, monitoring, and environment support.
- Compose stack · Environment-specific runtime composition for dev, test, staging, and production.
docker-compose.yml - NGINX proxy · Edge proxy configs for web/API routing across environments.
config/nginx - Monitoring · Prometheus, Alertmanager, and postgres-exporter configuration.
config/prometheus - Deployment scripts · Backup, SSL, and deployment automation scripts.
scripts
Engineering tooling
Non-runtime workflow and agent tooling bundled in the repo.
- BMAD tooling · Embedded agent/workflow framework for documentation, planning, testing, and engineering process support.
_bmad - Web bundles · Packaged agent and team bundles used for workflow orchestration.
web-bundles
Connections 27
- Web app → API app: API calls · Frontend fetches domain data and performs workflow actions through the backend.
- Web app → Auth: login/session · Client login, token refresh, and protected route handling.
- Web app → Shared UI: shared UI · Feature screens use common layout, UI primitives, stores, and hooks.
- API app → Auth: security · JWT strategy, guards, roles, and refresh-token handling.
- API app → Clinical modules: domain API · Clinical and administrative REST endpoints are organized as feature modules.
- API app → Imaging stack: integrations · Backend communicates with PACS/DICOM/HL7 systems and modality workflows.
- API app → Ops endpoints: observe · Health, metrics, logging, and audit concerns are exposed alongside business routes.
- API app → Data model: persist · Modules map to entities and query builders over the relational datastore.
- Clinical modules → Data model: reads/writes · Domain services and query builders operate on persisted RIS entities.
- Imaging stack → Data model: state sync · Integration modules store PACS, workitem, and imaging-related state.
- Simulator → Imaging stack: emulates · Simulator mimics PACS, modality, and RIS messaging behavior for development and tests.
- Mock PACS → Imaging stack: mock target · Mock PACS assets support local DICOM and integration testing.
- Patients UI → API app: reads patients · Patient screens consume patient, history, and workflow endpoints.
- Worklist UI → API app: worklist flow · Worklist screens drive study, PACS, and workflow actions through the API.
- Reports UI → API app: reports flow · Reporting UI fetches and saves report content and workitem state.
- Admin UI → API app: admin flow · Administration screens manage users, PACS config, radiologues, procedures, and audit views.
- History UI → API app: history flow · Patient history combines imaging and diagnostic data from backend services.
- Validation UI → API app: validation flow · Validation screens coordinate workitems, modalities, and salle selection.
- Dashboard UI → API app: stats · Dashboard metrics and recent activity are loaded from backend summary endpoints.
- Compose stack → Web app: runs · Containerized environment brings up the frontend runtime.
- Compose stack → API app: runs · Containerized environment brings up the backend runtime.
- Compose stack → NGINX proxy: fronts · Compose stack is wired to NGINX routing and environment-specific configs.
- Compose stack → Monitoring: observes · Compose stack includes monitoring and exporter services/configuration.
- Deployment scripts → Compose stack: orchestrates · Scripts manage deployment, backups, and environment setup around compose-based delivery.
- BMAD tooling → Web app: supports · Workflow tooling documents and tests the web app and repository processes.
- BMAD tooling → API app: supports · Workflow tooling documents and tests the backend architecture and implementation.
- Web bundles → BMAD tooling: packaging · Packaged agent bundles mirror the embedded workflow framework.