Travi AI Agent: System Overview

This is the modular form of the MVP Software Architecture Specification. Same decisions, same numbers, reorganized so nobody has to read 47 pages to do one task.

Layout

00-overview.md ← start here (10-minute plain-English read)
adr/ ← 18 one-page Architecture Decision Records
 README.md ← register/index of all ADRs
 ADR-001 … ADR-018.md
modules/ ← one brief per backend module (the unit of work)
 identity-consent.md ingestion.md compiler.md episode.md
 medication.md scheduling.md notification.md brief.md
 agents.md admin.md analytics.md audit.md
reference/ ← cross-cutting contracts
 platform.md (stack, repo layout, CI/CD, cloud, environments, actors)
 data-model.md (entities, fields, invariants, indexing, outbox)
 api.md (conventions + full endpoint catalog + payloads)
 security.md (threat model → controls, crypto, compliance)
 operations.md (alerts, dashboards, config keys, scheduled jobs)
 testing.md (test layers, extraction thresholds, 12 golden scenarios)
 nfr.md (the consolidated non-functional requirements table)
 delivery-plan.md (team, 12 sprints, phase gates, DoD, partner ratification)
 traceability.md (every PRD requirement → owning module → verifying test)
 glossary.md
assets/architecture.png
spec/ ← the original 47-page master spec (PDF), retained in the private repo for §-references

Cross-references: any §N.N you see points to the master spec (retained in the private repo), the modular files were generated from it and stay faithful to it. If the two ever disagree, the ADR files win (they are the decision log).

Reading paths

Using this with AI coding agents (Claude Code, etc.)

The set is deliberately sized so each file fits comfortably in a context window. Recipe per task:

1. Always include: 00-overview.md (or pin it as project memory / CLAUDE.md, section 3 "five hard rules" is the part that must never fall out of context).
2. Include the one module brief you're working in, it states the module's invariants, its data, its API surface, and which ADRs constrain it.
3. Include only the named reference sections the brief points to (e.g., the task_instance table from data-model.md, not the whole file).
4. Cite requirement IDs (e.g., MED-006) in commits/PRs, reference/traceability.md is the checklist that CI mirrors.
5. Never let an agent edit an ADR to make a task easier. Amending an ADR is a human governance decision.

Provenance

Generated July 2026 from Travi AI Agent_MVP_Software_Architecture_Specification_v1_0 (retained in the private repo). Contents: Engineering Review + the Product Requirements Document + Investor Feasibility Plan, consolidated with all open decisions resolved to build defaults (see adr/README.md for which seven remain partner-gated).

The 10-minute read. Everything else in this doc set is detail behind this page. Master spec: spec/ (PDF). Cross-references like §14.4 point there.

1. What this is

Travi AI Agent is a hospital- or payer-sponsored platform that manages the 30 days after a patient leaves the hospital, the window where heart-failure patients miss medications, skip follow-ups, and bounce back as readmissions.

The system reads the patient's final discharge paperwork, turns it into a simple day-by-day action plan, nudges the patient (or their caregiver) to complete each step, quietly fixes routine problems itself (calling the pharmacy, helping schedule a visit), and hands the outpatient doctor a one-screen summary right before the follow-up appointment.

One sentence: it converts discharge instructions into completed actions, with almost zero new work for hospital staff or doctors.

2. Who touches it

3. The five hard rules

These are enforced in code and state machines, not just policy. Breaking any of them is a release-blocking bug.

1. AI never makes clinical decisions. No AI output can create, change, or stop a medication instruction. Only two things can: a fully validated extraction from a signed clinical document, or a doctor confirming with strong authentication.
2. Every instruction traces to a source. Anything the patient or doctor sees links back to the exact sentence in the exact document it came from.
3. Agents gather evidence; the engine decides. Automation (calling pharmacies, booking help) returns structured evidence. A deterministic workflow engine, never the agent, moves state.
4. No PHI in notifications. Texts, pushes, and emails say "you have a new task" plus a link. Nothing medical on a lock screen.
5. Never imply a doctor is watching. No message may suggest continuous clinician monitoring. Emergencies get approved 911/ED language, immediately.

4. How an episode flows (day 0 → 30)

1. Day 0, Discharge. Epic sends a discharge event. Within 15 minutes an episode exists; the patient gets an SMS link, proves who they are (date of birth + having the phone), consents, and lands on their Today screen. Under 2 minutes, no password.
2. Day 0, Plan compilation. The pipeline parses the signed discharge documents, extracts medications/appointments/labs with an LLM, and runs every extracted fact through seven validation gates (schema, terminology, clinical sanity, verbatim source-span proof, similarity check…). Only facts that pass all seven become patient-visible tasks. Anything uncertain becomes a question for a human, never an instruction.
3. Days 1–29, Execution. The patient answers simple prompts ("Were you able to pick up spironolactone?", done / not yet / can't do it / not sure). "Can't do it" triggers automation: the medication-access agent calls the pharmacy; the appointment agent helps schedule. Reminders escalate gently (push → SMS → voice → caregiver) and stop within 60 seconds of completion. A patient who goes silent 48 hours on a critical task triggers a caregiver alert; 72 hours escalates further.
4. Before the follow-up visit. 24 hours before the PCP appointment, the system builds a snapshot brief and sends the doctor a secure link (email code, no account). If anything material changed since, the brief regenerates on open.
5. After the visit. The doctor's new instructions (uploaded note/AVS) reprocess through the same pipeline and update the remaining plan. Old tasks are superseded, never deleted.
6. Day 30, Close. A final handoff summary is generated; unresolved items are reported honestly; analytics freeze with fixed denominators (offered / activated / engaged / completed) so outcome numbers can't be gamed.

5. The system in one picture

Stack in one paragraph: a single Python 3.12 / FastAPI backend (a modular monolith, 13 internal modules with enforced boundaries, one deployable) plus Celery background workers on Redis; PostgreSQL 16 as the only source of truth; S3 for documents; a React PWA for patients/caregivers/clinician briefs; AWS (ECS Fargate, three accounts, Terraform); LLM calls go through AWS Bedrock (Claude, version-pinned, temperature 0, zero data retention under BAA); Twilio for SMS/voice and SES for email.

6. The 13 modules

Each has a brief in modules/ written to be handed to a developer, or an AI coding agent, as the context for a task.

7. Ten decisions that matter most

Full register with context and consequences: adr/.

8. Key numbers (the SLAs everything is built around)

9. Explicitly NOT in the MVP

No open patient–doctor chat. No remote vital-sign monitoring. No autonomous triage or medication advice. No writing orders/medications into the EHR (only a static summary document, and even that ships later behind a flag). No booking at outside health systems. One condition (heart failure), one health system.

10. Where to go next

• New engineer: read this → reference/platform.md → your module's brief in modules/.
• Reviewer / security: reference/security.md → adr/ → reference/testing.md.
• Clinical: modules/compiler.md (the gates) → modules/notification.md → reference/testing.md (golden scenarios).
• AI coding agent: see the recipe in README.md.