Technical & Architecture

Architecture Decision Records

AI Diligence Console

Architecture Decision Records: Index

Date: 2026-05-14

Architecture Decision Records (ADRs) capture the reasoning behind core platform choices. Each ADR follows the Michael Nygard format: Status / Context / Decision / Consequences / Alternatives considered. Procurement-grade.

ADR-001: AWS HIPAA-eligible over GCP / Azure

Status: Accepted (2025-Q3)

Context: Healthcare buyers require a BAA-eligible cloud. Three options: AWS, GCP, Azure. All three offer HIPAA-eligible services. Choice was driven by (a) breadth of HIPAA-eligible services already needed (RDS, S3 with Object Lock, ECS Fargate, KMS, Cognito, Secrets Manager, Bedrock), (b) platform engineering partner under NDA ops familiarity, (c) AWS Bedrock as the production Claude executor path inside the AWS BAA boundary.

Decision: AWS, us-east-2, BAA executed at account level.

Consequences: - ✅ Full HIPAA-eligible service catalog (ECS, RDS, S3, KMS, Secrets Manager, Cognito, Bedrock) - ✅ platform engineering ops can operate without retraining - ✅ AWS Bedrock is the production AI chain (AWS Bedrock under BAA → Anthropic Claude (Haiku 4.5) under BAA → Rōvn backend on ECS), Claude model traffic stays inside the AWS BAA boundary - ⚠ Vendor concentration: cloud + AI both AWS-adjacent - ✅ us-east-2 chosen for HIPAA-eligible posture, full Bedrock model availability, and separation from us-east-1 outage correlation

Alternatives considered: GCP (less mature HIPAA story for some services we needed); Azure (Microsoft healthcare relationships exist but platform engineering unfamiliarity added 6-9 months of ramp).

ADR-002: AWS Cognito over Auth0 for Worker Auth

Status: Accepted (2025-Q4)

Context: Worker auth needs to support phone + email, magic links, MFA, and federation. Both Cognito and Auth0 cover this. Pricing differs at scale.

Decision: AWS Cognito.

Consequences: - ✅ Already inside AWS BAA, no separate vendor BAA required - ✅ Per-MAU cost ~$0.0055 vs Auth0 ~$0.027, 5x cost differential at 100K MAUs - ✅ Native integration with API Gateway and ECS task IAM - ⚠ Cognito DX rougher than Auth0; AuthKit (migration 075) sits in front to smooth worker flows - ⚠ Federation surface narrower than Auth0; not yet a constraint

Alternatives considered: Auth0 (better DX, higher cost, separate BAA), Clerk (newer, less healthcare deployment track record), WorkOS (used for hospital SSO, not worker auth, different access patterns).

ADR-003: WorkOS over Okta for Hospital SSO

Status: Accepted (2026-Q1)

Context: Hospital IT teams ship SSO via SAML / OIDC. facility workflow layer needs to onboard each hospital identity provider per pilot. Per-hospital pricing matters because Pilot is a $12K one-time 90-day engagement (not an annual ACV), Okta enterprise per-connection pricing breaks unit economics at that envelope.

Decision: WorkOS, per-hospital SSO connection.

Consequences: - ✅ Pricing model matches sales motion (per-connection vs platform fee) - ✅ Connection ramp speed: hours not weeks - ✅ Healthcare customers familiar (WorkOS used by Mercury, Vercel, Rippling) - ✅ BAA terms in standard agreement (no special carve-out needed) - ⚠ Less mature than Okta for very large IDN deals, Platform tier may swap to Okta when needed

Alternatives considered: Okta (enterprise gold standard, pricing breaks Pilot economics), Auth0 SAML add-on (same cost issue), self-hosted Keycloak (operational burden inappropriate at this stage).

ADR-004: Drata over Vanta for SOC 2 Compliance

Status: Accepted (2026-Q1)

Context: SOC 2 Type II audit needs continuous evidence platform. Vanta and Drata both lead the category. Differentiation: integrations, pricing for pre-Series A, and auditor network.

Decision: Drata.

Consequences: - ✅ Pricing tier for pre-Series A stage cheaper at platform tier - ✅ Faster onboarding for AWS-centric stacks - ✅ Auditor network includes BAA-friendly firms - ⚠ Vanta arguably has wider integration catalog; Drata coverage sufficient for current stack

Alternatives considered: Vanta (wider category share, marginally pricier at our tier), Secureframe (slower onboarding from our reference checks), self-managed (does not scale to SOC 2 Type II evidence at our team size).

ADR-005: Persona over CLEAR for Identity Verification

Status: Accepted (2026-Q1)

Context: Worker identity verification needs IAL2-level assurance for healthcare credentialing. Options: Persona, CLEAR, ID.me, Stripe Identity, Plaid Identity.

Decision: Persona at IAL2.

Consequences: - ✅ Free tier covers initial verification volume during Pilot ramp - ✅ NCQA cadence-matched re-verification supported - ✅ BAA signed - ✅ Pricing scales with us, not against us - ⚠ Document fraud detection sufficient but not best-in-class for high-stakes clinical credentials, flagged for re-evaluation at Series A trigger

Alternatives considered: CLEAR (consumer-grade identity, weaker for clinical document verification, more expensive), ID.me (federal-government oriented), Stripe Identity (lighter IAL coverage), Plaid Identity (better for finance KYC, not healthcare).

ADR-006: Hash-Chained Audit Log Self-Built over Vendor

Status: Accepted (2026-Q1)

Context: Every credentialing action, AI executor call, source verification, and human decision must be tamper-evident for 7 years. Options: vendor (e.g., Streamiotics, immutable database vendors), build on AWS QLDB, build on S3 Object Lock + PostgreSQL with hash-chain.

Decision: Self-built, PostgreSQL append-only table with per-row SHA-256 hash chained to previous row, mirrored to S3 with Object Lock (COMPLIANCE mode, 7-year retention).

Consequences: - ✅ Tamper-evidence at row + at archive level - ✅ Proprietary moat, receipt design is part of our trust UX; vendor-coupled audit ties us to their pricing forever - ✅ Replay endpoint (/audit/chain-head, /audit/events/recent) is a primitive other parts of Rōvn build on - ✅ S3 Object Lock COMPLIANCE mode: even AWS root account cannot delete during retention window - ⚠ Self-built requires ongoing care, covered by platform engineering partner under NDA - ⚠ QLDB sunset notice (AWS deprecated 2024) validates self-built decision in hindsight

Alternatives considered: AWS QLDB (deprecated by AWS), vendor audit ledgers (price + lock-in), append-only Postgres alone without chain (insufficient tamper evidence).

ADR-007: Anthropic Claude via AWS Bedrock over OpenAI for Executor

Status: Accepted (2026-Q1, BAA chain executed)

Context: The AI executor must be BAA-eligible and reliable for clinical-context document extraction, anomaly summarization, and source crosswalk. Critical buyer requirement: BAA + ZDR. The production AI chain must keep Claude model traffic inside an AWS BAA boundary.

Decision: Anthropic Claude Haiku 4.5 via AWS Bedrock (executor) + Opus 4.7 advisor via beta tool. AI chain: AWS Bedrock under BAA → Anthropic Claude (Haiku 4.5) under BAA → Rōvn backend on ECS.

Consequences: - ✅ Dual BAA stack: AWS Bedrock BAA + Anthropic BAA both executed - ✅ ZDR (Zero Data Retention) eligibility for executor and advisor tiers - ✅ Opus 4.7 advisor pattern via advisor-tool-2026-03-01 beta header lets executor escalate hard cases without bouncing through user UX - ✅ Bedrock-resident invocation keeps model traffic inside the AWS BAA boundary - ⚠ Anthropic / Bedrock concentration risk, mitigated by ai_gateway.py abstraction that allows model swap across Bedrock-eligible models - ⚠ Beta header for advisor tool can change; monitored

Alternatives considered: OpenAI (BAA requires special tier and slower exec on advisor patterns; ZDR posture less clean for our use case), Google Vertex Gemini (BAA-eligible but no Opus-equivalent advisor pattern at the time of decision), self-hosted Llama (operational burden inappropriate).

ADR-008: Cached-Replay Pricing Model

Status: Accepted (2026-Q1)

Context: Every Rōvn source verification (NPDB $7.50, DEA $4, ABMS $30, AMA $75) is a pass-through cost. Two pricing models considered: (a) cost + flat margin every time, (b) cached-replay, first query is pass-through + margin, subsequent queries within source-validity window are served from cache at margin-only price.

Decision: Cached-replay pricing. Fresh NPDB $7.50 → cached replay $0.50 (margin ~15x). Inventory grows with the network; competitor at month 0 of inventory cannot match unit economics.

Consequences: - ✅ Compounding gross margin curve (40% Y1 → 86% Y5 base case per 3_CASE_MODEL_SUMMARY.md) - ✅ Pricing wedge versus incumbents (symplr, Modio, CertifyOS) who do not have a network-shared cache - ✅ Network effect: customer N+1 makes margin higher than customer N - ⚠ Requires source-validity windows to be tracked correctly, operational discipline, not technical risk - ⚠ Optical risk: cached price may look "too cheap" to procurement, sales narrative emphasizes verified depth + source URL + timestamp on every cached result

Alternatives considered: Flat margin (leaves money on the table, cedes pricing wedge), free + ads (incompatible with HIPAA + buyer trust), bundled-only (loses the standalone Verified API surface).

ADR registry (additional ADRs to draft post-close)

These are tracked as TARGET ADRs to write during the SOC 2 Type II evidence cycle:

ADR-009: PostgreSQL on RDS over Aurora (cost vs Aurora Serverless v2 reliability)
ADR-010: ECS Fargate over EKS (operational burden trade)
ADR-011: Cloudflare Pages over Vercel for marketing surface
ADR-012: pgcrypto column encryption pattern for PHI fields
ADR-013: WorkOS SSO connection lifecycle pattern
ADR-014: MCP server zero-PHI surface as integration primitive

End of ADR index.

Ask the AI agent about this section, the raise, compliance posture, or any cross-document question. Grounded in Rōvn's deep context, with on-page source citations.

AI queries route through AWS Bedrock under BAA · Anthropic Claude (Haiku 4.5) under BAA · zero-data-retention posture · no PHI in prompts.