This issue tracks the **systems and workflow documentation** for the Sonador platform — architecture, data-flow, use-case, sequence, component, and deployment diagrams plus the supporting systems documentation that surrounds the ACL/security work. Its goal is to move beyond *test-coverage tracking* and build a **comprehensive systems/workflow picture of the application** suitable for Software-as-a-Medical-Device (SaMD) documentation practices. > **Provenance:** Split out of oak-tree/medical-imaging/sonador#55 ("Sonador ACL MS1: Test Coverage Tracking"), where the documentation checklist originally lived alongside the functional-test inventory. The original checklist is preserved verbatim (converted to a plain itemized list) as a comment on #55 for traceability, and #55 now links here. Keeping documentation separate lets #55 close on test completion while documentation work continues here. --- ### Why a dedicated systems-documentation set (SaMD framing) Sonador is medical-imaging software; its documentation should align with the artifact expectations of the relevant SaMD standards/guidance so the system is auditable and submission-ready: - **IEC 62304** (medical-device software lifecycle): software **architecture** and **detailed-design** descriptions, decomposition into software items/units, and a **SOUP / third-party** inventory. - **FDA premarket cybersecurity guidance**: a **system/architecture diagram**, **data-flow diagrams** (especially PHI and credential/token flows), a **threat model** with trust boundaries, and a **Software Bill of Materials (SBOM)**. - **ISO 14971** (risk management) & **IEC 62366** (usability/use specification): **use-case** definition of actors and intended use (the ACL roles map directly to this). - **HIPAA accountability**: documentation of **audit logging** / access-event recording. The diagram set below is the practical, consolidated expression of those requirements. ### Inventory of Endpoints https://docs.google.com/spreadsheets/d/1tiRgj75Dgm1yyI2c1PVXacLIt-AJP-tzxGc-5Po3kHk/edit?usp=sharing --- ### Required documentation artifacts — current coverage Assessed against the local docs wiki (`oaktree-env/docs`, the GitLab platform-docs wiki). Status legend: ✅ diagram exists · 🟡 partial / prose-only / needs a real diagram · ❌ absent. | Artifact | SaMD rationale | Current coverage | Status | |---|---|---|---| | **High-Level System Architecture Diagram** | IEC 62304 architecture; FDA system diagram | `sonador.production-deployment.svg` (`prod.deployment-guide`, `prod.istio-networking`) is deployment-centric; OHIF viewer has its own architecture diagram (`dev.architecture-sonador.ohif`). No single *logical* diagram spanning all subsystems (Sonador web, Orthanc + plugin, OHIF viewer, IdP/Cognito, Kafka). | 🟡 | | **Data Flow Diagrams (DFD)** | FDA cybersecurity — PHI & token flows | Kafka producer ASCII flow (`dev.kafka`); authorization-engine SVG (`security.authorization`). No integrated diagram of PHI moving DICOM upload → Orthanc → viewer, nor of credential/token validation at each hop. | 🟡 | | **Use Case Diagrams** | IEC 62366 actors/intended use | Reviewer-worklist use case described in prose only (`workflow.reviewer-worklists`). No actor diagram for the ADMIN / REVIEWER / TECHNICIAN / REFERRING roles. | ❌ | | **Sequence Diagrams** | Interaction design / traceability | None. Auth-engine evaluation, OIDC login + IdP group sync, token validation against ACL, and authorized-upload chain are all prose-only (`security.authorization`, `dev.credentials-management`, `security.index`). | ❌ | | **Component Diagrams** | IEC 62304 software-item decomposition | OHIF viewer architecture diagram + repo structure (`dev.architecture-sonador.ohif`); Orthanc-plugin module/startup structure (`dev.orthanc-plugin`, ASCII-ish); Kafka module table (`dev.kafka`). Backend (Django/FastAPI/Sonador) decomposition is prose. | 🟡 | | **Deployment Diagrams** | FDA system/deployment context | `sonador.production-deployment.svg` (k8s pods, DBs, PVs, ingress) plus Istio PeerAuthentication / AuthorizationPolicy config (`prod.deployment-guide`, `prod.istio-networking`). | ✅ | | **Hans Extras** | (placeholder) | @hans.deraad to enumerate additional required items. | ❌ | | **Accreditation** | Regulatory mapping | No accreditation/standards-mapping document. | ❌ | ### Recommended additions (SaMD gaps not in the original list) | Artifact | SaMD rationale | Current coverage | Status | |---|---|---|---| | **Threat model / security architecture** | FDA cybersecurity — trust boundaries & attack surface | Hierarchical patient→study→series trust-check ASCII (`security.orthanc-authorization-plugin`) + authorization SVG; no attack-surface / threat-scenario / trust-boundary model. | 🟡 | | **SBOM / SOUP inventory** | IEC 62304 SOUP; FDA SBOM | Dependencies mentioned inline only (SQLAlchemy, Guru client, Sonador IO client, confluent_kafka, OHIF extensions). No formal manifest. | ❌ | | **Entity/ER diagram** | Design clarity | Data models well-documented in tables (`dev.data-models`: ImagingPatient/Study/Series/DcmInstance, ACL models, worklist, comments) but no ER diagram. | 🟡 | | **Audit-logging / access-event documentation** | HIPAA accountability | Not documented. | ❌ | | **Machine-readable API spec (OpenAPI/Swagger)** | Validation & submission | API documented in prose + inline JSON (`security.authorization`, `dev.credentials-management`, `dev.kafka`, `workflow.reviewer-worklists`); no OpenAPI. | 🟡 | --- ### Diagram / documentation checklist Core set (from the original #55 documentation checklist): - [ ] High-Level System Architecture Diagram — *consolidate a logical all-subsystem view; deployment SVG + OHIF diagram exist as starting points* - [ ] Data Flow Diagrams (DFD) — *priority: integrated PHI + credential/token flow across upload → Orthanc → viewer* - [ ] Use Case Diagrams — *actors = ADMIN / REVIEWER / TECHNICIAN / REFERRING; reviewer-worklist prose can seed this* - [ ] Sequence Diagrams — *auth-engine evaluation, OIDC login + IdP group sync, token→ACL validation, authorized upload* - [ ] Component Diagrams — *extend beyond OHIF/Orthanc-plugin to the Django/FastAPI backend decomposition* - [ ] Deployment Diagrams — *largely complete (`sonador.production-deployment.svg` + Istio); confirm currency* - [ ] Hans Extras — @hans.deraad please add any additional items here - [ ] Accreditation — *standards/regulatory mapping document* SaMD-recommended additions: - [ ] Threat model / security architecture (trust boundaries, attack surface) - [ ] SBOM / SOUP third-party component inventory - [ ] Entity/ER diagram for the data models - [ ] Audit-logging / access-event documentation - [ ] Machine-readable API specification (OpenAPI/Swagger) --- ### Notes - Coverage assessed June 2026 against the platform docs wiki checkout (`oaktree-env/docs`). Re-verify before submission as the docs evolve. - Deployment documentation is the most mature; **sequence diagrams, use-case diagrams, an integrated PHI/credential DFD, a threat model, and an SBOM** are the highest-value gaps for SaMD readiness. #### Project Tracking OP#75 OP#135