Architecture
Date: 2026-05-14
Scope: Rōvn platform as deployed, rovn.to, passport.rovn.to, app.rovn.to.
1. System Overview
Rōvn is a healthcare workforce trust platform with three product surfaces (Passport, facility workflow layer, Verified API) sharing one backend, one verified credential rail, and one hash-chained audit log.
┌───────────────────────────────┐
│ Public marketing + product │
│ rovn.to (Cloudflare Pages) │
└─────────────┬─────────────────┘
│
┌───────────────────────┼───────────────────────┐
│ │ │
┌────────▼─────────┐ ┌────────▼─────────┐ ┌────────▼────────┐
│ Passport (worker)│ │ facility workflow layer (facility)│ │ Verified API │
│ /start /wallet │ │ /portal │ │ /api/* │
│ /network /p/ │ │ (WorkOS SSO) │ │ (token auth) │
└────────┬──────────┘ └────────┬──────────┘ └────────┬────────┘
│ │ │
└───────────────┬───────┴─────────────────────────┘
│
┌────────▼────────┐
│ FastAPI on ECS │
│ Fargate us-east-2 │
│ passport.rovn.to │
└────────┬────────┘
│
┌────────────────┬───────┼───────────────┬──────────────────┐
│ │ │ │ │
┌──────▼─────┐ ┌───────▼────┐ │ ┌───────▼────────┐ ┌──────▼──────┐
│ PostgreSQL │ │ S3 (PHI / │ │ │ AWS Bedrock │ │ MCP server │
│ on RDS │ │ audit) │ │ │ Claude exec │ │ /mcp tool │
│ (private │ │ Object │ │ │ (Haiku 4.5) │ │ (token- │
│ VPC) │ │ Lock 7yr │ │ │ + Opus advisor │ │ gated) │
└────────────┘ └────────────┘ │ │ (BAA, ZDR) │ └─────────────┘
│ └────────────────┘
│
┌────────────────────┴─────────────────────┐
│ │
┌───────▼──────┐ ┌────────▼──────┐
│ Source │ │ Vendor SDKs │
│ Authority │ │ Persona │
│ Adapters (36)│ │ Checkr │
│ NPDB DEA │ │ WorkOS │
│ Nursys OIG │ │ Drata │
│ SAM 25 BONs │ │ Stripe │
│ 5 payers │ │ Sentry │
└──────────────┘ └───────────────┘
2. Components
Frontend
- rovn.to: Cloudflare Pages (marketing + Next.js app routes for product surfaces)
- passport.rovn.to: FastAPI HTML routes serving worker Passport app (
/start,/wallet,/network,/p/{slug}) - app.rovn.to: Cloudflare Pages alias for product routes (redundant with rovn.to per 2026-05-11 unified domain note)
API Tier
- FastAPI on AWS ECS Fargate, us-east-2AWS region07.2 AWS Infrastructure Memo · single-region ECS / RDS / S3 in us-east-2
- 80+ routers registered (
app/main.py:69-157) - Static assets served from
STATIC_DIRfor HTML product surfaces - CORS allowed origins driven by env (
frontend_origins) - OpenAPI docs disabled in production (
docs_url=Nonewhenenvironment == "production")
Database
- PostgreSQL on AWS RDS in private VPC subnets
- 75+ migrations applied
pgcryptoextension for PHI column encryption- Connection pool with read-replicas roadmap (not yet shipped)
- Backup: AWS RDS automated daily snapshots, 30-day retention; point-in-time recovery (PITR) enabled
Auth
- Worker auth: AWS Cognito + AuthKit (migrations 073, 075)
- Hospital auth: WorkOS SSO (migration 074) + legacy email/password (
hospital_auth.py) - Admin auth: dedicated
admin_auth.pyrouter - API auth (MCP / partner): Bearer token (
mcp_server.py:137) - JWKS endpoint exposed at
/jwks/*for token verification by third parties
AI Layer
- AI chain: AWS BedrockAI provider chain07.3 AI Architecture · AWS Bedrock under BAA → Anthropic Claude Haiku 4.5 under BAA → Rōvn ECS under BAA → Anthropic Claude (Haiku 4.5)Model identity07.3 AI Architecture · Haiku 4.5 chosen for cost + latency + BAA chain under BAA → Rōvn backend on ECS.
- Executor: Anthropic Claude Haiku 4.5 via AWS BedrockAI provider chain07.3 AI Architecture · AWS Bedrock under BAA → Anthropic Claude Haiku 4.5 under BAA → Rōvn ECS under BAA.
- Advisor: Opus 4.7 via beta
advisor-tool-2026-03-01header (Anthropic BAA). ZDR-eligible. - Gateway:
app/services/ai_gateway.pyabstracts model selection and routes between executor and advisor. - Ledger:
ai_runstable (migration 029) captures every executor + advisor call with token cost, PARTIAL coverage as of 2026-05-14.
Storage
- S3 (audit bucket): Object Lock enabled, 7-year retention, COMPLIANCE mode
- S3 (source receipts): standard bucket for verification source artifacts (migrations 062, 068)
- S3 (PHI documents): encrypted at rest with AWS KMS customer-managed keys
Monitoring
- Sentry: error tracking, configured at app boot (
app/main.py:1-9) - CloudWatch: logs + metrics + alarms
- Health endpoint
/healthfor ECS health checks - Sentry smoke route
/debug/sentry(admin-only) for wiring verification
Static
- Cloudflare Pages projects:
rovn-design(marketing + app routes),rovn-portal(alias)
3. Sequence Diagram: Credentialing Verification Flow
Worker Passport UI FastAPI AI Gateway Source Adapter PostgreSQL S3 (audit)
│ │ │ │ │ │ │
│ Upload license │ │ │ │ │ │
├─────────────────►│ │ │ │ │ │
│ │ POST /documents │ │ │ │
│ ├──────────────►│ │ │ │ │
│ │ │ doc.upload │ │ │ │
│ │ ├───────────────►│ │ │ │
│ │ │ │ OCR / extract │ │ │
│ │ │ │ (Claude exec) │ │ │
│ │ │ │ │ │ │
│ │ │ extracted fields │ │ │
│ │ │◄───────────────┤ │ │ │
│ │ │ enqueue verify │ │ │
│ │ ├────────────────────────────────►│ │ │
│ │ │ │ Query state BON│ │
│ │ │ ├────────►(ext)───┤ │
│ │ │ │ response + URL + ts│ │
│ │ │ │ + hash │ │
│ │ │ source_receipt write │ │ │
│ │ ├──────────────────────────────────────────────────►│ │
│ │ │ hash-chain append │ │ │
│ │ ├──────────────────────────────────────────────────────────────────►│
│ │ │ decision rollup │ │ │
│ │ ├──────────────────────────────────────────────────►│ │
│ │ Verified + │ │ │ │
│ │ tier-labeled │ │ │ │
│◄─────────────────┤ receipt │ │ │ │
Truth tier (per master strategy §3): output of this flow is labeled Tier 5 (Source-verified), the receipt shows source, URL, timestamp, hash, and tier.
4. Sequence Diagram: Privileging Decision Flow
CMO / Committee facility workflow layer UI FastAPI Privileging Engine PostgreSQL Audit Log
│ │ │ │ │ │
│ Open packet │ │ │ │ │
├───────────────────►│ │ │ │ │
│ │ GET /privileging/packet/{worker_id} │ │ │
│ ├───────────────►│ │ │ │
│ │ │ Build packet │ │ │
│ │ ├──────────────────────►│ │ │
│ │ │ │ Pull verified │ │
│ │ │ │ Passport facts │ │
│ │ │ ├────────────────►│ │
│ │ │ │ Pull OPPE/FPPE │ │
│ │ │ ├────────────────►│ │
│ │ │ │ Build advisory │ │
│ │ │ │ recommendation │ │
│ │ │ Packet │ (Opus advisor) │ │
│ │ Render │◄──────────────────────┤ │ │
│ Review + │ │ │ │ │
│ approve / deny │ │ │ │ │
├───────────────────►│ │ │ │ │
│ │ POST /privileging/decision │ │ │
│ ├───────────────►│ │ │ │
│ │ │ Write decision (HUMAN actor) │ │
│ │ ├────────────────────────────────────────►│ │
│ │ │ Hash-chain append (HUMAN actor + AI advisory ref) │
│ │ ├──────────────────────────────────────────────────────►│
│ │ Confirmed │ │ │ │
│◄───────────────────┤ │ │ │ │
Critical: human (committee member) is the actor on every privileging decision write. AI advisory is referenced but never the actor. Doctrine: "Humans make every credentialing, privileging, hiring, and clinical decision."
5. Sequence Diagram: Audit Chain Replay
Auditor FastAPI PostgreSQL S3 (Object Lock)
│ │ │ │
│ GET /audit/chain-head │ │
├────────────────────►│ │ │
│ │ Read latest chain head │
│ ├──────────────────────►│ │
│ │ Return head + hash │ │
│ │◄──────────────────────┤ │
│ Head hash │ │ │
│◄────────────────────┤ │ │
│ │ │ │
│ GET /audit/events/recent?since={ts} │ │
├────────────────────►│ │ │
│ │ Read events │ │
│ ├──────────────────────►│ │
│ │ Return events │ │
│ │◄──────────────────────┤ │
│ Replay each event hash → verify chain link │ │
│ Optionally fetch source receipt artifact │ │
│ │ GET artifact │ │
│ ├──────────────────────────────────────────────────►│
│ │ S3 read │ │
│ │◄──────────────────────────────────────────────────┤
│ Verified chain │ │ │
│◄────────────────────┤ │ │
Posture: hash-chained audit log is append-only, S3 Object Lock makes it tamper-evident over 7-year retention window (HIPAA 6-year + 1).
6. Deployment
S3 → CodeBuild → ECR → ECS pattern (memory log reference_rovn_deploy_mechanic.md):
Local commit → S3 source zip → CodeBuild (Docker image) → ECR (prod-* tag)
↓
ECS task definition (new revision) ←┘
↓
ECS service updates → blue/green
↓
Health check passes → traffic shifts
Note: force-new-deployment alone is a no-op, every prod deploy registers a new task definition revision.
End of architecture.