reference/platform.mdEngineering, reference~7 min read

Platform: Architecture, Stack, Cloud & Actors

4. System Architecture

Figure 1, MVP system architecture. One deployable API, one async plane, one canonical store. Figure 1, MVP system architecture. One deployable API, one async plane, one canonical store.

4.1 Module Inventory (Monolith Internal Boundaries)

Each module is a Python package under app/modules/ with a public interface (api.py router + service.py facade) and private internals. Cross-module calls go through service facades only; import-linter contracts in CI fail the build on any deeper import. Modules share the database but own their tables (write access enforced by convention + code review; the audit schema is enforced by a separate INSERT-only DB role).

Module Responsibility Key Requirements Owned
identity Activation tokens, patient/caregiver/clinician sessions, grants, step-up, recovery, revocation lists. ENR-003/004/005, CLN-001, CGV-001/004
consent Consent records, versions, scopes (program, caregiver, recording-optional), withdrawal cascade. SEC-010, CGV-007
ingestion EHR adapter, ADT listener, FHIR client, document fingerprinting, source versioning. INT-001, DPC-001
compiler Discharge plan compiler + seven-gate LLM pipeline; extracted-fact publication. DPC-003/004/007/008, DQS-004/011
episode Episode & Universal Task state machines, transitions, idempotency, prioritization engine. PAT-001/003/005, ENR-001/002
medication Medication plan items, status events (8 states), barriers, verification labeling. MED-003/005/006/010
scheduling Appointment requirements, appointments, matching, assisted-scheduling flows, result completion. APT-001/004/010
notification Channel selection, escalation ladders, quiet hours, suppression outbox, templates, silent-deterioration detector. ENG-002/004/012, EDU-002/007
brief Brief snapshots, precompute triggers, staleness checks, post-visit update loop. VIS-002/005/007, CLN-004/008
agents Agent orchestrator, policy envelopes, tool registry, evidence records, kill switches. AUT-001/006/009
admin Tenant/cohort/config management, versioned publication, RBAC administration. ADM-004 config side
analytics Event projections, denominators, execution & outcome reports, coverage flags. ADM-004/007
audit Append-only audit writer + query API; S3 WORM archiver. SEC-003, DQS-001

4.2 Runtime Topology

Process Scale (pilot) Notes
api 2–4 tasks, 1 vCPU/2 GB FastAPI + Uvicorn behind ALB; stateless; readiness = DB+Redis ping.
worker-default 2 tasks Celery queues: episode, ingest, analytics. Prefetch 1, acks-late, visibility 300 s.
worker-llm 1–2 tasks Queue llm; concurrency 4; per-task Bedrock budget caps (§11.7); isolates latency.
worker-notify 2 tasks Queues notify, outbox; drains suppression outbox every 5 s to meet the 60 s SLA.
beat 1 task (singleton) Celery beat: schedules in §16.5. Leader lock in Redis.
migrator on deploy Alembic upgrade head as ECS one-off task; deploy gate.

4.3 Technology Stack (pinned)

Layer Choice (version) Notes
Language / API Python 3.12 · FastAPI 0.115 · Uvicorn 0.30 OpenAPI generated; /v1 prefix; Pydantic v2 models shared with workers.
ORM / migrations SQLAlchemy 2.0.32 · Alembic 1.13 One migration lineage; no auto-generated DDL in prod without review.
Async jobs Celery 5.4 · Redis 7.2 Priorities via dedicated queues, not priority flag.
Frontend React 18.3 · TypeScript 5.5 · Vite 5 · Workbox 7 PWA manifest; bundle budget 250 KB gz initial for patient routes.
UI kit Radix UI + Tailwind 3.4 44 px min touch targets; WCAG 2.2 AA tokens; EN/ES i18n via i18next.
LLM Bedrock: anthropic.claude-sonnet pinned model ID; Titan embed v2 IDs live in model registry table (§11.6), never in code.
Telephony Twilio SMS + Voice (Studio flows) BAA signed; status callbacks → /webhooks/twilio.
Email AWS SES Transactional only; DKIM/DMARC enforced.
Observability OpenTelemetry SDK → ADOT collector → CloudWatch; Sentry (PHI-scrubbed) Trace ID propagated into Celery headers and audit rows.
Testing pytest 8 · Playwright 1.45 · schemathesis · Locust Layer mapping in §17.1.

4.4 Repository & Conventions

travi ai agent/ # single monorepo
 app/ # FastAPI monolith
 modules/{identity,consent,ingestion,compiler,episode,medication,
 scheduling,notification,brief,agents,admin,analytics,audit}/
 api.py service.py models.py schemas.py tasks.py tests/
 core/ # settings, db, security, llm_gateway, ehr_adapter, outbox
 main.py
 web/ # React PWA (patient/caregiver/clinician routes)
 infra/ # Terraform: modules/ + envs/{dev,stage,prod}
 ops/ # runbooks, dashboards-as-code, oncall
 docs/adr/ # ADR-001..018 as markdown, this doc's source
 .github/workflows/ # ci.yml, deploy.yml, nightly-golden.yml
  • Branching: trunk-based; short-lived feature branches; squash merge; Conventional Commits; release tags v0.x.y.
  • Quality gates (CI-blocking): ruff + mypy --strict, eslint + tsc, import-linter contracts, pytest ≥85% line coverage on modules/, schemathesis against OpenAPI, Playwright smoke, Trivy image scan (no HIGH/CRITICAL), tfsec.
  • Code review: 1 approval; 2 for identity, compiler gates, audit, Terraform, or any migration touching PHI tables.
  • PHI hygiene: no PHI in logs, traces, Sentry, commit messages, or fixtures, synthetic data only outside prod (§15.6).

5. Environments, Cloud & Delivery Infrastructure

5.1 Accounts & Environments

Env AWS Account Purpose / Data Policy
dev tai-dev Ephemeral stacks per PR optional; synthetic data only; relaxed sizes; nightly teardown of previews.
stage tai-stage Production-shaped; Epic sandbox connectivity; synthetic + partner test patients only; load & DR drills here.
prod tai-prod Live PHI. Change only via pipeline; console read-only except break-glass role (audited).

5.2 Network & Core Services

  • VPC per env: 3 AZs; public subnets = ALB + NAT only; private subnets = ECS, RDS, ElastiCache; no public IPs on tasks; VPC endpoints for S3, ECR, Secrets Manager, Bedrock, CloudWatch.
  • Hospital connectivity: site-to-site IPsec VPN (or partner-preferred private link) terminating in a dedicated integration subnet; ADT listener reachable only from partner interface-engine CIDR; all inbound mTLS where the engine supports it.
  • Edge: CloudFront serves the static PWA bundle (no PHI cached; Cache-Control: no-store on all API responses); AWS WAF managed rules + rate rules (/v1/patient/activate: 10/min/IP) in front of ALB.
  • Data: RDS PostgreSQL 16 Multi-AZ (db.m7g.large pilot), PITR 15-min granularity, 35-day backups; ElastiCache Redis 7 (cluster mode off, multi-AZ); S3 buckets tai-{env}-sources, -briefs, -exports, -audit-archive (Object Lock compliance 6 y on audit), all SSE-KMS with per-purpose CMKs, versioning + access logs on.
  • Secrets: AWS Secrets Manager; 90-day rotation for DB/Twilio/Epic client credentials; no secrets in env files or Terraform state (state in S3 + DynamoDB lock, KMS-encrypted).
  • IAM: task roles per process (api / workers / migrator); Bedrock invoke restricted to registry model IDs; deny s3:DeleteObject on audit archive to all runtime roles.

5.3 CI/CD

  1. PR → CI gates (§4.4) on GitHub Actions; preview deploy to dev on label.
  2. Merge to main → build multi-arch image → push ECR → auto-deploy stage (migrator → blue/green ECS via CodeDeploy, 10% canary 10 min, auto-rollback on alarm).
  3. Manual approval (CTO or delegate) → prod deploy, same shape; release notes auto-generated from Conventional Commits.
  4. Nightly: golden-scenario suite + extraction benchmark against pinned models; regression fails page the on-call and block the next prod deploy.

5.4 Resilience, DR & Retention

Item Commitment / Mechanism
Availability target ≥99.9% monthly, Multi-AZ RDS/Redis, ≥2 tasks/service across AZs, ALB health checks, graceful drains.
RPO / RTO RPO ≤15 min (PITR + Redis is rebuildable); RTO ≤4 h via Terraform re-provision runbook; quarterly restore test in stage is a release-blocking control.
Degradation modes Bedrock down → pipeline pauses at Gate 2, tasks stay pending_extraction, ops alert (no unvalidated publishing). Twilio down → channel ladder skips to next channel; safety-tier failures page. Epic down → ingestion retries with backoff; episodes continue on last-known plan.
Data retention PHI: contract term + 6 y (audit) unless partner policy stricter; Twilio/SES message bodies not stored at vendor beyond delivery (config); LLM: Bedrock zero-retention, no training use (SEC-010); voice recordings: not stored in MVP.
Environments parity Stage = prod Terraform with size overrides only; drift detection nightly (terraform plan must be empty).

2. Scope & Requirements Baseline

The functional baseline is the Product Requirements Document. All requirement IDs referenced in this document (e.g., MED-006, ENG-012) are normative and their acceptance criteria are the test oracle. Section 20 provides the full requirement-to-component traceability matrix; no MVP requirement is unowned. Where the PRD says “configurable,” this specification names the configuration key, its default value, and its owner.

2.1 Actors and Trust Levels

Actor Authentication Trust / Authorization Scope
Patient Activation token → session JWT (Section 9.1) Own episode only. Can report status, respond to tasks, manage consent & caregivers.
Caregiver Own invitation token → own session JWT Patient-granted scope on one episode; read + report; never sees other episodes; revocable instantly.
Clinician Magic link + email OTP; step-up OTP for confirmations One patient, one episode, time-boxed grant. Read brief; confirm/clarify material items with step-up.
Hospital admin Design-partner IdP via OIDC SSO + MFA Tenant-scoped configuration, cohorts, reports, kill switches per RBAC matrix (Section 9.5).
Travi AI Agent operator Internal IdP (Google Workspace OIDC) + MFA Break-glass PHI access is separately authorized, reasoned, time-boxed, and audited.
System agents Service identity (IAM role) + policy envelope Least-privilege tool allowlists; can never transition clinical state directly (Section 12).

2.2 Configuration Ownership Model

Every tunable named in this document lives in the tenant_config service (Section 16.4) with three tiers: platform defaults (owned by Travi AI Agent engineering, changeable by release), tenant policy (owned by the design partner, changeable via admin console with versioning per ADM requirements), and cohort overrides (owned by the clinical lead). Configuration changes never retroactively alter active episodes; a new config_version applies only to episodes created after publication, satisfying the enterprise immutability constraint.