Sonador ACL/Security: Systems & Workflow Documentation (SaMD diagram coverage)
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 #55 (closed) ("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 (closed) for traceability, and #55 (closed) now links here. Keeping documentation separate lets #55 (closed) 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:
| 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 (closed) 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