# duskwillow/ris-multisite architecture

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

- Interactive diagram: https://gitdiagram.com/duskwillow/ris-multisite
- Repository: https://github.com/duskwillow/ris-multisite

## Overview

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: [`apps/api`](https://github.com/duskwillow/ris-multisite/tree/main/apps/api) (API app), [`docker-compose.yml`](https://github.com/duskwillow/ris-multisite/blob/main/docker-compose.yml) (Compose stack), [`apps/web`](https://github.com/duskwillow/ris-multisite/tree/main/apps/web) (Web app), [`apps/api/src/pacs`](https://github.com/duskwillow/ris-multisite/tree/main/apps/api/src/pacs) (Imaging stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Runtime apps"]
  node_web["Web app<br/>React/Vite client"]
  node_api["API app<br/>NestJS backend"]
  node_auth["Auth<br/>JWT security"]
  node_clinical["Clinical modules<br/>RIS domains"]
  node_imaging["Imaging stack<br/>PACS/DICOM/HL7"]
  node_opsapi["Ops endpoints<br/>health/metrics/audit"]
  node_data[("Data model<br/>ORM entities")]
  node_patientsui["Patients UI<br/>feature slice"]
  node_worklistui["Worklist UI<br/>feature slice"]
  node_reportui["Reports UI<br/>feature slice"]
  node_adminui["Admin UI<br/>feature slice"]
  node_historyui["History UI<br/>feature slice"]
  node_validationui["Validation UI<br/>feature slice"]
  node_dashboardui["Dashboard UI<br/>feature slice"]
  node_webcore["Shared UI<br/>components/hooks"]
end

subgraph group_infra["Delivery & ops"]
  node_compose["Compose stack<br/>docker-compose<br/>[docker-compose.yml]"]
  node_proxy["NGINX proxy<br/>reverse proxy"]
  node_monitoring["Monitoring<br/>observability stack"]
  node_deployment["Deployment scripts<br/>ops scripts"]
end

subgraph group_tooling["Engineering tooling"]
  node_bmad["BMAD tooling<br/>workflow framework"]
  node_bundles["Web bundles<br/>agent bundles"]
end

subgraph group_test["Test harnesses"]
  node_sim["Simulator<br/>mock PACS/RIS"]
  node_mockpacs["Mock PACS<br/>test assets"]
end

node_web -->|"API calls"| node_api
node_web -->|"login/session"| node_auth
node_web -->|"shared UI"| node_webcore
node_api -->|"security"| node_auth
node_api -->|"domain API"| node_clinical
node_api -->|"integrations"| node_imaging
node_api -->|"observe"| node_opsapi
node_api -->|"persist"| node_data
node_clinical -->|"reads/writes"| node_data
node_imaging -->|"state sync"| node_data
node_sim -->|"emulates"| node_imaging
node_mockpacs -->|"mock target"| node_imaging
node_patientsui -->|"reads patients"| node_api
node_worklistui -->|"worklist flow"| node_api
node_reportui -->|"reports flow"| node_api
node_adminui -->|"admin flow"| node_api
node_historyui -->|"history flow"| node_api
node_validationui -->|"validation flow"| node_api
node_dashboardui -->|"stats"| node_api
node_compose -->|"runs"| node_web
node_compose -->|"runs"| node_api
node_compose -->|"fronts"| node_proxy
node_compose -->|"observes"| node_monitoring
node_deployment -->|"orchestrates"| node_compose
node_bmad -.->|"supports"| node_web
node_bmad -.->|"supports"| node_api
node_bundles -.->|"packaging"| node_bmad

click node_web "https://github.com/duskwillow/ris-multisite/tree/main/apps/web"
click node_api "https://github.com/duskwillow/ris-multisite/tree/main/apps/api"
click node_auth "https://github.com/duskwillow/ris-multisite/tree/main/apps/api/src/auth"
click node_clinical "https://github.com/duskwillow/ris-multisite/tree/main/apps/api/src"
click node_imaging "https://github.com/duskwillow/ris-multisite/tree/main/apps/api/src/pacs"
click node_opsapi "https://github.com/duskwillow/ris-multisite/tree/main/apps/api/src/health"
click node_data "https://github.com/duskwillow/ris-multisite/tree/main/apps/api/src/patients/entities"
click node_patientsui "https://github.com/duskwillow/ris-multisite/tree/main/apps/web/src/features/Patients"
click node_worklistui "https://github.com/duskwillow/ris-multisite/tree/main/apps/web/src/features/worklist"
click node_reportui "https://github.com/duskwillow/ris-multisite/tree/main/apps/web/src/features/reports"
click node_adminui "https://github.com/duskwillow/ris-multisite/tree/main/apps/web/src/features/Admin"
click node_historyui "https://github.com/duskwillow/ris-multisite/tree/main/apps/web/src/features/patientHistory"
click node_validationui "https://github.com/duskwillow/ris-multisite/tree/main/apps/web/src/features/validation/sansCr"
click node_dashboardui "https://github.com/duskwillow/ris-multisite/tree/main/apps/web/src/features/dashboard"
click node_webcore "https://github.com/duskwillow/ris-multisite/tree/main/apps/web/src/components"
click node_sim "https://github.com/duskwillow/ris-multisite/tree/main/apps/api/src/simulator"
click node_mockpacs "https://github.com/duskwillow/ris-multisite/tree/main/test/mock-pacs"
click node_compose "https://github.com/duskwillow/ris-multisite/blob/main/docker-compose.yml"
click node_proxy "https://github.com/duskwillow/ris-multisite/tree/main/config/nginx"
click node_monitoring "https://github.com/duskwillow/ris-multisite/tree/main/config/prometheus"
click node_deployment "https://github.com/duskwillow/ris-multisite/tree/main/scripts"
click node_bmad "https://github.com/duskwillow/ris-multisite/tree/main/_bmad"
click node_bundles "https://github.com/duskwillow/ris-multisite/tree/main/web-bundles"

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_web,node_api,node_auth,node_clinical,node_imaging,node_opsapi,node_data,node_patientsui,node_worklistui,node_reportui,node_adminui,node_historyui,node_validationui,node_dashboardui,node_webcore toneBlue
class node_compose,node_proxy,node_monitoring,node_deployment toneAmber
class node_bmad,node_bundles toneMint
class node_sim,node_mockpacs toneRose
```

## Components

### Runtime apps

Primary application runtimes for the RIS product.

- [Web app](https://github.com/duskwillow/ris-multisite/tree/main/apps/web): React/Vite client · Browser RIS UI with feature-sliced workflows and hook-driven data flow. · `apps/web`
- [API app](https://github.com/duskwillow/ris-multisite/tree/main/apps/api): NestJS backend · Main RIS backend with feature modules, relational persistence, and external integrations. · `apps/api`
- [Auth](https://github.com/duskwillow/ris-multisite/tree/main/apps/api/src/auth): JWT security · Login, refresh tokens, roles, guards, and protected session flow. · `apps/api/src/auth`
- [Clinical modules](https://github.com/duskwillow/ris-multisite/tree/main/apps/api/src): RIS domains · Patients, worklists, reports, exams, procedures, workitems, dashboard, admin, and related operational features. · `apps/api/src`
- [Imaging stack](https://github.com/duskwillow/ris-multisite/tree/main/apps/api/src/pacs): PACS/DICOM/HL7 · PACS, DICOM, MLLP/MPPS, and simulator boundaries for imaging-system integration. · `apps/api/src/pacs`
- [Ops endpoints](https://github.com/duskwillow/ris-multisite/tree/main/apps/api/src/health): health/metrics/audit · Health checks, metrics, logging middleware, and audit interceptors/logs. · `apps/api/src/health`
- [Data model](https://github.com/duskwillow/ris-multisite/tree/main/apps/api/src/patients/entities): ORM entities · Relational domain entities, query builders, and persistence-facing services. · `apps/api/src/patients/entities`
- [Patients UI](https://github.com/duskwillow/ris-multisite/tree/main/apps/web/src/features/Patients): feature slice · Patient browsing and patient-centric workflow views. · `apps/web/src/features/Patients`
- [Worklist UI](https://github.com/duskwillow/ris-multisite/tree/main/apps/web/src/features/worklist): feature slice · Worklist and PACS/study handling for radiology workflow actions. · `apps/web/src/features/worklist`
- [Reports UI](https://github.com/duskwillow/ris-multisite/tree/main/apps/web/src/features/reports): feature slice · Report editing, templates, dosimetry, and workitem-driven report flows. · `apps/web/src/features/reports`
- [Admin UI](https://github.com/duskwillow/ris-multisite/tree/main/apps/web/src/features/Admin): feature slice · Administration screens for PACS config, radiologues, users, procedures, assignments, and audit logs. · `apps/web/src/features/Admin`
- [History UI](https://github.com/duskwillow/ris-multisite/tree/main/apps/web/src/features/patientHistory): feature slice · Patient history and imaging/diagnostic history orchestration. · `apps/web/src/features/patientHistory`
- [Validation UI](https://github.com/duskwillow/ris-multisite/tree/main/apps/web/src/features/validation/sansCr): feature slice · Sans CR validation workflow with modality and salle selection. · `apps/web/src/features/validation/sansCr`
- [Dashboard UI](https://github.com/duskwillow/ris-multisite/tree/main/apps/web/src/features/dashboard): feature slice · Operational summary, activity charts, and recent exam views. · `apps/web/src/features/dashboard`
- [Shared UI](https://github.com/duskwillow/ris-multisite/tree/main/apps/web/src/components): components/hooks · 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](https://github.com/duskwillow/ris-multisite/blob/main/docker-compose.yml): docker-compose · Environment-specific runtime composition for dev, test, staging, and production. · `docker-compose.yml`
- [NGINX proxy](https://github.com/duskwillow/ris-multisite/tree/main/config/nginx): reverse proxy · Edge proxy configs for web/API routing across environments. · `config/nginx`
- [Monitoring](https://github.com/duskwillow/ris-multisite/tree/main/config/prometheus): observability stack · Prometheus, Alertmanager, and postgres-exporter configuration. · `config/prometheus`
- [Deployment scripts](https://github.com/duskwillow/ris-multisite/tree/main/scripts): ops scripts · Backup, SSL, and deployment automation scripts. · `scripts`

### Engineering tooling

Non-runtime workflow and agent tooling bundled in the repo.

- [BMAD tooling](https://github.com/duskwillow/ris-multisite/tree/main/_bmad): workflow framework · Embedded agent/workflow framework for documentation, planning, testing, and engineering process support. · `_bmad`
- [Web bundles](https://github.com/duskwillow/ris-multisite/tree/main/web-bundles): agent bundles · Packaged agent and team bundles used for workflow orchestration. · `web-bundles`

### Test harnesses

Local simulation and automated test infrastructure.

- [Simulator](https://github.com/duskwillow/ris-multisite/tree/main/apps/api/src/simulator): mock PACS/RIS · Local/test simulation of PACS, modality, and RIS interactions. · `apps/api/src/simulator`
- [Mock PACS](https://github.com/duskwillow/ris-multisite/tree/main/test/mock-pacs): test assets · Mock imaging endpoint and DICOM sample assets for local integration testing. · `test/mock-pacs`

## Connections

- 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.
