RT On-Treatment Visit Mini-App

Field	Value
Spec ID	medOS-RT-OTV-1
Status	Draft v0.1
Owner	Ever Medical Technologies
Module	medOS · Radiation Oncology
Companion specs	medOS-RT-DDC-1, medOS-RT-IGRT-1, medOS-RT-PlanCockpit, BIA-RT-1, BIA-RT-2
Targets	Vajira RT clinic rooms (RO workstation), partner sites
Primary user	Radiation Oncologist (RO) at clinic-room workstation
Date	2026-05-07

1. Purpose & scope

medOS-RT-OTV-1 specifies the On-Treatment Visit mini-app: the weekly clinical review screen the radiation oncologist uses during a course of treatment to assess toxicity, verify trajectory, and decide whether to continue, pause, amend, consult, or replan.

The OTV is the central clinical-decision surface of a course of radiation therapy. A typical curative course produces 5–7 OTVs across 5–7 weeks; SBRT courses may have one mid-treatment check; palliative courses often have a single end-of-treatment review. Each OTV captures structured CTCAE toxicity data, dose-to-date trajectory, photo documentation of skin reactions, concurrent-care status, and a documented decision. The data flows into the Plan Cockpit’s toxicity grid and informs the next week of fractions.

Scope covers: pre-visit case packet assembly, CTCAE toxicity capture, photo capture and annotation, vitals and weight, chemoRT concurrent-care surfacing, dose trajectory visualization with genomic-modifier overlays, diff view since last OTV, structured decision capture, education and counseling capture, referral generation, event emission.

It does not cover: the initial consult or treatment-planning visit (separate Treatment Planning workspace spec), survivorship or post-treatment follow-up (separate Survivorship spec), formal CTCAE terminology authoring (uses NCI CTCAE v5.0 vocabulary unchanged).

2. Clinical context

A patient on radiation therapy is in a sustained physiological challenge. Acute toxicities accumulate predictably for most sites and modalities; their pattern, timing, and severity are what the radiation oncologist tracks weekly to ensure (a) the patient is tolerating treatment, (b) the trajectory matches expectations for the prescribed dose and modifiers, © any deviation triggers an appropriate response — supportive care, hold, consult, replan.

For a head-and-neck IMRT/VMAT chemoRT patient, the typical week-by-week toxicity envelope:

• Week 1-2: minimal symptoms, occasional fatigue
• Week 3: mucositis G1-2 emerges, skin G1, dysphagia begins, weight loss begins
• Week 4-5: peak mucositis G2-3, dysphagia G2, weight loss accelerates, may need PEG
• Week 6: plateau or slight improvement, post-treatment recovery begins after EOT

Genomic modifiers shift this curve. ATM heterozygotes show toxicity ~1 week earlier and ~0.5 grade higher at peak. The OTV is where the system’s genomic claims become operationally clinical — the RO sees “tracking to ATM heterozygous predicted curve” and reads G2 mucositis at week 3 as expected rather than alarming.

The OTV is also where decisions to deviate from plan are made. About 5-10% of curative H&N courses require a hold for severe mucositis; about 3-5% require a replan for anatomic change; about 1-2% require treatment abortion. The OTV is the structured surface where these decisions are made, documented, justified, and linked to evidence.

3. User personas & primary task

Radiation Oncologist (primary). Sits with the patient in a clinic room. Reviews the auto-assembled case packet (pre-visit), conducts the patient interview and physical exam, captures CTCAE grades, takes or directs photos, reviews the trajectory visualization, makes the decision, generates referrals as needed, and signs the note. Target visit time: 15-20 minutes for a routine OTV; 30-45 for a complex one (consult, hold decision, replan trigger).

Oncology nurse (assist). Often present at the OTV. Captures vitals (weight, BP, HR), takes skin-reaction photos, administers symptom assessments (e.g., Edmonton Symptom Assessment System — ESAS — common in Thai practice), provides patient education, generates referrals to dental/nutrition/social work. Has authoring access on the OTV note for the assist sections.

Patient (subject). May complete a pre-visit ESAS or similar PROM on a tablet in the waiting room (~5 minutes, optional). May also review summary at end of visit on the same device.

Medical physicist (consult only). Pulled in if a replan trigger is proposed; reviews the plan and dose trajectory and either agrees to the trigger or recommends adaptive measures.

4. Workflow state machine

stateDiagram-v2
    [*] --> CasePacketAssembling : OTV scheduled
    CasePacketAssembling --> ReadyForVisit : Auto-data populated
    ReadyForVisit --> InVisit : RO opens
    InVisit --> ToxicityCapture : Tab: toxicity
    InVisit --> VitalsCapture : Tab: vitals
    InVisit --> PhotoCapture : Tab: photos
    InVisit --> Trajectory : Tab: trajectory
    ToxicityCapture --> InVisit
    VitalsCapture --> InVisit
    PhotoCapture --> InVisit
    Trajectory --> InVisit
    InVisit --> DecisionPending : RO ready to decide
    DecisionPending --> DecisionCaptured : Decision recorded
    DecisionCaptured --> ReferralsGenerating : If consult/referral needed
    ReferralsGenerating --> Signed : All referrals issued
    DecisionCaptured --> Signed : No referrals
    Signed --> [*] : Note finalized, events emitted

The workflow is non-linear within InVisit — RO moves between tabs as the conversation with the patient unfolds. Decision is captured last; signing locks the note (amendments after signing create a new note with amends_id).

5. Data model

otv_session

Column	Type	Notes
id	uuid PK
treatment_plan_id	uuid FK
phase_id	uuid FK
visit_number	integer	ordinal across the course
scheduled_ts	timestamptz
started_ts	timestamptz
signed_ts	timestamptz
fractions_delivered_at_visit	integer
cumulative_dose_gy	numeric
ro_id	uuid FK
nurse_id	uuid FK
state	enum	(states above)
amends_id	uuid FK	if this is an amendment to a prior note
signed_note_text	text	structured + free narrative
created_ts	timestamptz

otv_toxicity

Column	Type	Notes
id	uuid PK
otv_session_id	uuid FK
ctcae_term	string	e.g., “Mucositis oral”
ctcae_meddra_code	string	e.g., “10028124”
grade	integer	0-5
grade_change_from_last	integer	diff
notes	text
attributable_to	enum	rt | chemo | both | neither | unknown

otv_photo

Column	Type	Notes
id	uuid PK
otv_session_id	uuid FK
body_site	string	“anterior neck”, “lateral right neck”, “oral”
image_ref	uri	storage location
annotations_jsonb	jsonb	markup overlay data
ctcae_terms	string[]	which toxicities this photo evidences
taken_ts	timestamptz
taken_by	uuid FK

otv_vitals

Column	Type	Notes
id	uuid PK
otv_session_id	uuid FK
weight_kg	numeric
weight_baseline_pct	numeric	derived: % of baseline
blood_pressure_sys	integer
blood_pressure_dia	integer
heart_rate	integer
performance_status_ecog	integer
pain_score_0_10	integer
taken_by	uuid FK
taken_ts	timestamptz

otv_decision

Column	Type	Notes
id	uuid PK
otv_session_id	uuid FK
decision	enum	continue | hold | amend | consult | replan-propose | abort
rationale_code	string
rationale_free_text	text
hold_until_date	date	if decision=hold
consult_specialties	string[]	if decision=consult
amend_payload	jsonb	if decision=amend
decided_by	uuid FK
cosign_required	boolean
cosigned_by	uuid FK
decided_ts	timestamptz

otv_referral

Column	Type	Notes
id	uuid PK
otv_session_id	uuid FK
specialty	string	“Nutrition”, “Palliative”, “Dental”, “Social work”
reason_code	string
reason_free_text	text
urgency	enum	urgent | routine
generated_ts	timestamptz

otv_education

Column	Type	Notes
id	uuid PK
otv_session_id	uuid FK
topic	string	“Mouthwash protocol”, “Skin care”
given_by	enum	verbal | handout | video
delivered_by	uuid FK	nurse usually

The OTV note is a composition of these rows plus a free-narrative text field. The signed note projects to a FHIR ClinicalImpression (with embedded Observations for each toxicity, plus a careplan-rt-otv extension carrying the decision payload).

6. UX shell

The OTV mini-app uses a clinical workspace layout (not kiosk) — RO is at a desk, has more time and screen real estate than the RTT in the vault. Single-page layout with intra-page sectional navigation; no modal dialogs except for photo capture.

┌──────────────────────────────────────────────────────────────────────────┐
│  patient strip · plan · WEEK 3 OTV · Visit 3 of 6 · last OTV 7d ago      │
├──────────────────────────────────────────────────────────────────────────┤
│  ── TRAJECTORY BAND ──                                                    │
│  Where she is on the dose-vs-toxicity curve, with ATM-het overlay         │
├──────────────────────────────────┬───────────────────────────────────────┤
│  TOXICITY (CTCAE v5.0)            │  VITALS · CHEMO · DOSE TO DATE       │
│   8 terms · 2 changed since last  │   weight, BP, HR, ECOG, pain         │
│                                   │   cisplatin C2 status                │
│  PHOTOS (3 sites)                 │   24.0 → next 26.0 / 60 Gy           │
│   anterior neck, posterior R,     │                                      │
│   oral                            │  DECISION                            │
│                                   │   ⓘ Recommended: Continue            │
│  EDUCATION & REFERRALS            │   [ CONTINUE ]                       │
│   topics covered, referrals       │   [ Hold · Consult · Replan ]        │
├──────────────────────────────────┴───────────────────────────────────────┤
│  Free narrative · structured note preview · sign and submit              │
└──────────────────────────────────────────────────────────────────────────┘

Tabs not used — vertical scroll keeps everything visible and printable. The structured note preview at the bottom assembles the captured data into a readable narrative the RO can edit before signing.

7. Pre-visit case packet (auto-assembled)

When the OTV is scheduled (typically same-day or day-before), the system auto-assembles a case packet:

• All FractionDelivered events since last OTV (count, total dose delivered, any aborts)
• All IGRT setup deviations and replan triggers (if any)
• All Side-effect quick captures from the Daily Delivery Console (between-OTV trend)
• Last labs (CBC, CMP for chemoRT)
• Last chemo administration with dose, holds, premeds
• Patient-reported outcomes from waiting-room intake (if completed)
• Last OTV’s note for diff view
• Genomic modifiers from BIA-RT VC (radiosensitivity class, hereditary syndromes, pharmacogenomics)
• Site-specific expected toxicity curve at this fraction count

The packet pre-fills the OTV draft. The RO reviews and refines rather than enters from scratch — typical entry time drops from 8 minutes to 2-3 minutes when the packet is good.

8. CTCAE toxicity capture

CTCAE v5.0 (NCI) is the canonical vocabulary; v6.0 when published replaces it. Implementation:

• Site-specific toxicity preset for the patient’s tumor site (e.g., “H&N IMRT” preset shows: dermatitis radiation, mucositis oral, dysphagia, dysgeusia, xerostomia, fatigue, pain head/neck, weight loss, nausea, vomiting). Pre-loaded with grade from the last OTV.
• RO updates each grade by tap (0/1/2/3/4/5 buttons) and notes optional. Diff arrow (↑/↓/→) shows change since last OTV.
• “Add toxicity” search box for any CTCAE term not in the preset; autocomplete over the full v5.0 vocabulary (~800 terms).
• Each toxicity has an attributable_to field (RT, chemo, both, neither, unknown) — clinically important when RT and chemo overlap; informs which protocol’s dose-modification rules apply.
• Free-text notes per toxicity for nuance (“worse in evening”, “responds to opioid”, etc.).

Grading rules surface inline: tapping the “?” next to a term shows the CTCAE definition for grades 1-5 (the actual NCI text, not paraphrased) so the RO can grade consistently. Inter-rater reliability matters; surface the source.

9. Photo capture and annotation

Site-specific photo template (e.g., H&N: anterior neck, posterior right neck, posterior left neck, oral cavity if tolerated). Camera capture happens on a tablet or wall-mounted camera in the clinic room. Photos:

• Auto-tagged with body site, CTCAE term(s), patient ID, timestamp.
• Annotation tools: pen markup for circling areas, distance measurement, comparison-to-last-OTV side-by-side viewer.
• Compared against the last OTV’s photos at the same site by default — the diff view is automatic.
• Photo metadata stripped of GPS / device-identifying tags before storage; PHI policy compliant.

Photos are clinical evidence and must be preserved with chain-of-custody. They join the patient’s record under otv_photo rows; reproducible by FHIR Media resource references in the projected ClinicalImpression.

10. Dose-to-date and trajectory

The trajectory band at the top of the screen renders three overlaid curves:

1. Dose-delivered curve: cumulative Gy across fractions delivered.
2. Expected dose curve: the prescribed accumulation (linear in most cases).
3. Predicted toxicity envelope for the patient’s site, modality, and genomic modifiers.

For an ATM-heterozygous H&N IMRT patient, the predicted toxicity envelope is shifted left (earlier onset) and elevated (higher peak) compared to the baseline. The OTV trajectory band shows both curves so the RO can see which envelope the patient is tracking to.

If the patient’s actual toxicity (composite of CTCAE captures across recent OTVs) is below the predicted envelope, that’s a positive signal worth noting. If above, it warrants attention and may inform the decision (hold, consult).

The trajectory model behind the predicted envelope is statistical (population data, refined per protocol) — not deterministic. Confidence intervals are rendered as a band, not a line. The label is “predicted envelope” not “expected”.

11. Diff view — what changed since last week

Three diffs surface automatically:

1. Toxicity diff: each CTCAE term graded last OTV, with this OTV’s grade and a directional arrow. Items unchanged are deprioritized; items that worsened are highlighted; items that improved are noted.
2. Vitals diff: weight change in kg and % of baseline; BP and HR trends; ECOG.
3. Photo diff: side-by-side at each body site, last OTV vs this OTV.

The diff is the cognitive scaffolding. Most weekly OTVs are routine and the RO’s job is to confirm “things are progressing as expected.” The diff lets that confirmation happen in seconds, leaving cognitive bandwidth for the patient interview itself.

12. Structured decision capture

Six decision options:

• Continue — proceed as planned. Default for routine OTV.
• Hold — pause treatment for N days. Reason captured (most common: severe mucositis allowing recovery); hold_until_date recorded; affected fractions auto-rescheduled.
• Amend — modify prescription mid-course (rare; usually a partial-dose-reduction). Triggers a Plan Amend workflow (separate spec) that produces a new plan version pinned to remaining fractions.
• Consult — refer to another specialty without pausing RT. Specialties surfaced as multi-select: Dental, Nutrition, Palliative care, Social work, Speech-language pathology, Pain medicine, Psychiatry/psychology.
• Replan-propose — anatomic change requires a new plan. Triggers the Replan workflow; current treatment continues against the existing plan until the new plan is approved (usually 2-3 fractions of overlap).
• Abort — stop the course. Very rare; requires RO + physicist co-sign.

Each decision carries a rationale code (closed list per decision type) plus free text. The decision is the pivot point of the OTV note and is the event that drives downstream actions.

AI assistance (AI Safety Gate–gated): the system suggests a decision based on the captured data. For routine cases this is “Continue”; for elevated toxicity above the predicted envelope it might suggest “Consult: Nutrition” or “Hold: 3 days for mucositis recovery.” The suggestion is advisory and gated — the RO sees it, considers it, and decides. The AI Safety Gate filters suggestions that pattern-match to approval-seeking (“Looks great, continue!” when the data shows otherwise). Suggestion provenance (model, confidence, gate decision) is recorded against the OTV note.

13. Education and counseling capture

Structured fields for what the patient was educated on this visit:

• Topic (preset list: skin care, mouth care, nutrition, hydration, pain management, what to call about, sexual health for pelvic patients, etc.)
• Delivery method: verbal, printed handout, video shown
• Delivered by: RO, nurse, both
• Patient understanding confirmed: yes / partial / no
• Family member present: yes / no / interpreter used

This data is light but matters — Thai government hospital QI metrics include “patient education delivered” as a quality measure, and PDPA / NHSO audit asks for it. Logging it structurally beats embedding it in narrative.

14. Patient-reported outcomes (intake, optional)

When configured, the patient completes a brief PROM on a waiting-room tablet before the visit. Default instrument: ESAS-r (Edmonton Symptom Assessment System, Thai-validated version) — 10 symptoms graded 0-10. Takes ~3 minutes.

PROM data appears in the OTV mini-app pre-populated; the RO reviews it before the patient interview and may discuss notable scores. PROM does not substitute for CTCAE grading; the RO’s CTCAE assessment is authoritative for the medical record. PROM provides patient-perspective signal.

15. Event payloads

// Visit started
{
  "type": "OTVStarted",
  "otv_session_id": "...",
  "treatment_plan_id": "...",
  "visit_number": 3,
  "fractions_delivered_at_visit": 12,
  "actor_id": "ro-...",
  "ts": "..."
}

// Toxicity captured
{
  "type": "OTVToxicityCaptured",
  "otv_session_id": "...",
  "captures": [
    {"term": "Mucositis oral", "grade": 2, "change_from_last": 1, "attributable": "rt"},
    {"term": "Dermatitis radiation", "grade": 2, "change_from_last": 0, "attributable": "rt"},
    {"term": "Dysphagia", "grade": 1, "change_from_last": 0, "attributable": "rt"}
  ],
  "ts": "..."
}

// Photos captured
{
  "type": "OTVPhotoCaptured",
  "otv_session_id": "...",
  "photo_count": 3,
  "body_sites": ["anterior_neck", "posterior_right_neck", "oral_cavity"],
  "ts": "..."
}

// Decision
{
  "type": "OTVDecisionRecorded",
  "otv_session_id": "...",
  "decision": "continue",
  "rationale_code": "tracking-to-predicted-envelope",
  "ai_suggestion": "continue",
  "ai_confidence": 0.91,
  "ai_safety_gate_status": "pass",
  "ts": "..."
}

// Note signed
{
  "type": "OTVNoteSigned",
  "otv_session_id": "...",
  "ro_id": "...",
  "fhir_clinical_impression_id": "ClinicalImpression/...",
  "ts": "..."
}

The signed note projects to a FHIR ClinicalImpression resource referencing the EverOncologyRTCarePlan and the BIA-RT genomic claims that informed any decision (e.g., the ATM heterozygous claim that justified the “tracking to predicted envelope” rationale).

16. Bilingual & accessibility

• All CTCAE terms displayed in both English and Thai. The English term is canonical for storage (per NCI vocabulary); the Thai is a translation layer maintained against the official Thai-language CTCAE adaptation (when available — for v5.0 some terms are hospital-translated).
• ESAS-r and patient-facing materials in Thai by default with English toggle.
• Free-text notes accept both Thai and English; the system does not translate; whatever the RO writes is what the record holds.
• Photo annotations support Thai labels.

17. Regulatory & safety

• The OTV note is a clinical record entry — protected, audited, signed.
• Signed notes are append-only; amendments create new linked notes.
• Decision events that set holds, replans, aborts, or referrals require the RO’s authenticated signature.
• AI-suggested decisions are advisory; the RO is the decision-maker and the audit trail records both the suggestion and the human action.
• PDPA / HIPAA / APPI: photos are PHI; the photo storage system enforces encryption-at-rest, access controls, and access logging.
• The AI Safety Gate decision is recorded as a Provenance resource on the resulting ClinicalImpression.

18. Performance & failure modes

Performance budget:

• Case packet assembly: < 5 s when triggered (overnight pre-build for next-day OTVs; same-day adds latency).
• Photo capture to viewable: < 3 s.
• Decision recorded to signed note: < 30 s.
• Total RO entry time goal (with case packet): 2–3 minutes for routine; 8–10 minutes for complex.

Failure modes:

• Case packet incomplete (e.g., last OTV note unavailable) — mini-app shows partial state; RO can complete manually.
• Photo capture fails — fallback to upload from a secondary device; visit completes without photo in extreme cases (with explicit acknowledgment).
• AI suggestion service unavailable — decision capture proceeds without suggestion; rationale rests entirely on RO.
• Network partition (air-gapped Vajira) — local mode allows full visit completion; sync on recovery.

19. Open questions for v0.2

• Late toxicity vs acute toxicity boundary. CTCAE separates them; current spec assumes acute (during treatment). Late toxicity (post-treatment) belongs to the Survivorship mini-app.
• Pediatric OTV. Different toxicity expectations, different vocabulary; needs a pediatric mode.
• Brachytherapy OTV. Different rhythm — often once after a single insertion rather than weekly. Needs different visit-number logic.
• Hospice or comfort transition. Some patients in palliative RT decompensate; the OTV may pivot to a goals-of-care conversation. Should the mini-app surface a goals-of-care-shift workflow?
• Multi-disciplinary OTV. Some institutions co-schedule RO + medical oncologist + nutritionist for chemoRT patients. Should the mini-app support multi-clinician shared editing in real time?
• PROM beyond ESAS-r. Additional instruments (FACT-H&N for head and neck, EORTC QLQ-C30 generic) — should they be configurable per protocol?
• Survivorship handoff. At the final OTV, the survivorship plan is initiated. The handoff workflow needs spec’d separately.

20. Implementation notes for medOS

1. Mini-app shell. Renders inside DynamicContentRenderer; enum value RT_OTV. Reads treatment_plan_id and otv_session_id from URL params.
2. CTCAE v5.0 — embed the full vocabulary as a static JSON in the bundle; ~800 terms × ~150 KB. Updates published when NCI publishes new versions.
3. Photo capture component — webcam API for laptop, hardware-camera API for tablet, with file-upload fallback. Annotation built on Konva for performance.
4. Trajectory model — population-derived predicted envelope per (site × modality × genomic modifier). Stored as a parameterized curve set in protocol_registry. Initial models from RTOG/EORTC published toxicity curves; refined per institution as Vajira data accumulates.
5. Diff rendering — pure functional; given two otv_session rows, compute the diff at render time. No persisted diff state.
6. Note serialization — the structured-to-FHIR projection runs at sign time; the projection function is well-defined and unit-testable.
7. Voice dictation (Thai) — for narrative free text, integrate a Thai ASR service. Keeps the RO heads-up with the patient; less typing during the visit.
8. Patient companion handoff — at end of visit, the patient companion app receives a summary push (next appointment, side-effect tips, what to call about). Local-first, sovereign, with explicit consent.

---

End of medOS-RT-OTV-1 v0.1