Skip to content

Architecture Decision Records

Curated index of the platform's key design decisions. Source specs live at docs/superpowers/specs/ and implementation plans at docs/superpowers/plans/.

These are engineering-history artifacts ("ADRs in everything but name"): they record what was decided, why, and the constraints at the time.

Foundational

  • 2026-04-15 — Clinical data model v1: Initial Prisma schema, patient identity, cases, findings, diagnoses, organisations, and products. Defines the core data structures all services build on. spec

  • 2026-04-17 — Encryption at rest and histology ingestion: Per-patient data-encryption-key (DEK) strategy, KMS integration, audit trail, retention policy, and histology report upload flow. spec

  • 2026-04-19 — SA Platform monorepo structure: Extraction of shared packages (@sa-platform/common, @sa-platform/auth-client, etc.); per-service database pattern; Redis Streams event bus. spec

Per-service

auth

  • 2026-04-19 — Auth service design: OAuth 2.0 client-credentials flow, RSA key pairs, JWKS endpoint, API client and secret lifecycle, scope registry. spec

user-management

  • 2026-04-19 — User management design: User identity model, org membership, role-permission system, product access grants, user context resolution. spec
  • 2026-04-20 — Consent service design: Consent type registry, versioned consent text, per-patient consent records, event-driven consent check protocol with orchestrator. spec

notifications

  • 2026-04-21 — Notifications service design: Event fan-out via Redis Pub/Sub pattern subscription, template engine, SES and Slack delivery, suppression lists, preferences. spec

  • 2026-04-22 — Notifications follow-ups: Delivery-attempt retries, BullMQ job configuration, stuck-notification re-enqueue, idempotency inbox refinements. spec

  • 2026-04-22 — Notifications PHI at rest: Per-notification variable encryption so recipient addresses and message bodies are encrypted at rest. spec

ai-review

  • 2026-04-23 — AI review service design: DERM AI integration, BullMQ inference job pipeline, AiReview / AiReviewResult schema, supersession model, ai_review.* event contracts. spec

orchestrator

  • 2026-04-26 — Orchestrator service design: Configurable workflow definition graph, WorkflowInstance lifecycle, dispatcher step-kind-to-event mapping, timeout scheduling, manual interventions. spec

human-review

  • 2026-04-27 — Human review service design: Review queue, claim/unclaim/submit/decline lifecycle, reviewer registry, human_review.* event contracts. spec

Cross-cutting

  • 2026-04-21 — Prisma 6 upgrade: Migration from Prisma 5 to Prisma 6; driver-adapter introduction. spec

  • 2026-04-21 — Prisma 7 upgrade: Migration to Prisma 7; driver-adapter finalisation across all services. spec

  • 2026-04-23 — KMS key provider design: AWS KMS-backed key provider for DEK wrapping; local dev mock. spec

  • 2026-04-23 — Production secret enforcement: CI gates and runtime checks that prevent services from starting with placeholder secrets in production. spec

  • 2026-04-27 — Documentation strategy: Audience-segmented docs architecture, mkdocs setup, CI gates, and this content plan. spec