# Product Requirements Document — Milestone 1
## AI-Guided CT Surgery Patient Intake System

**Version:** 2.0
**Date:** 2026-05-11
**Status:** Draft

---

## 1. Overview

Milestone 1 delivers a working AI-guided patient intake system for the Cardio Thoracic Surgery department. Medical staff conduct structured patient intake sessions using handheld devices. The AI guides the conversation, transcribes spoken answers, and generates a clean structured patient case summary.

**Milestone 1 goal:** A staff member logs in, sees all patient sessions, starts or continues a patient intake, answers questions verbally through a mic, and receives a structured patient summary within 30 seconds of session submission.

---

## 2. Problem Statement

Junior doctors and medical assistants in Cardio Thoracic Surgery departments struggle to produce clear, structured, and complete patient summaries for senior doctors. Informal intake processes result in:

- Incomplete symptom collection
- Inconsistent documentation quality
- Senior doctors spending consultation time re-collecting basic data instead of making clinical decisions
- Risk of missed critical information during patient inquiry

This system solves the documentation and intake standardization problem — not the diagnosis problem.

---

## 3. Target Users

| User | Role in M1 | Primary Pain |
|---|---|---|
| **Medical Staff** (junior doctors, medical assistants, nurses) | Conducts AI-guided patient intake sessions; views session history and summaries | Spend consultation time re-collecting basic information; no standardized intake protocol |
| **Cardiologist / Consultant Doctor** | Logs in with staff credentials; accesses intake list, reviews summaries, continues sessions | Walk into consultations without a complete patient picture; no tool to query patient data in the 2–3 minute consultation window |
| **Admin** (Hospital Administrator) | Pre-seeded in DB; creates and manages staff accounts with name, email, role, and PIN | No unified system for staff onboarding and account management |

**Note:** Role-based access control is not enforced in M1. All logged-in users access the same screens. RBAC is deferred to M2.

---

## 4. Goals & Success Metrics

| Goal | Metric |
|---|---|
| Accurate patient summary generated | Within 30 seconds of session submission |
| LLM presents all standard CT Surgery questions at session start | All questions listed in LLM's first message before adaptive Q&A begins |
| Adaptive question response | Next question returned within 2 seconds of answer submission |
| System availability | 99.9% uptime during hospital operating hours |
| Interface usability | Staff can operate without any training |

---

## 5. Scope

### In Scope — Milestone 1

- Intake list screen — all patient sessions visible to all logged-in users
- New patient intake — basic patient info entry; LLM starts session with question overview then adaptive Q&A one question at a time
- Patient ID validation — if a manually entered ID already has an active session in the retention window, system throws an error and directs staff to continue the existing session
- Audio recording via browser mic (Web Speech API — browser-native, free); staff speaks in English, Hindi, or Telugu; transcription output converted to English before being sent to the LLM
- Transcription displayed on screen for staff to review and correct before sending
- Text input fallback — staff can type or edit the transcribed text manually
- Completion signal — LLM signals done; displays flagged questions (those answered with "no", "I don't know", "NA", or equivalent); staff chooses to continue or submit
- Patient case summary generation (≤ 30 seconds, structured for review)
- "Ask More?" available only for the same patient's existing session — continues Q&A, appends responses to conversation history, no new session or patient ID created; for a new patient, staff uses "New Intake" from the list
- Full conversation history preserved in the session so any logged-in user can continue from exactly where it was left off
- Session data and conversation history retained for a configurable period (env var `DATA_RETENTION_HOURS`, default 48 hours); auto-purged after expiry
- Session auto-save on every response — no data loss on interruption
- Admin account seeded in DB; admin creates staff accounts (name, email, role attached at creation time, 6-digit PIN)
- Email + PIN login; JWT issued; 30-minute inactivity timeout
- Department-aware data model — schema designed to support multiple departments from day one

### Out of Scope — Milestone 1

- Role-based access control enforcement (deferred to M2)
- Separate view per role (all users see the same screens in M1)
- Senior consultation alerting (deferred to M2)
- Audit logging (deferred to M2)
- Administrative management UI (deferred to M3)
- Doctor training and protocol configuration module (deferred to M3)
- Permanent patient data storage
- Integration with hospital EMR/EHR systems
- Offline functionality
- Multi-hospital or multi-department deployment

---

## 6. Core User Flows

### Flow 1 — Admin Creates Staff Accounts
Admin account is pre-seeded in the database. Admin logs in → opens account management → creates a staff account (name, email, department) → selects a role → sets a 6-digit PIN → sees and shares that PIN with the staff member directly.

### Flow 2 — Staff Logs In
Staff enters email + PIN → system validates → JWT issued → staff lands on Intake List screen.

### Flow 3 — Intake List
Staff sees a table of all patient sessions: patient ID, name, age, gender, created date, department, status. "New Intake" button starts a new session. Clicking an existing row opens that session.

### Flow 4 — New Patient Session
Staff enters patient ID (manually), name, age, gender → taps "Start Session". If the patient ID already has an active session in the retention window, system shows an error and directs to that session — no duplicate created. Otherwise, the LLM's first response lists all standard CT Surgery questions it will cover, then immediately begins adaptive Q&A with question 1.

### Flow 5 — Q&A Loop
LLM presents one question at a time. Staff selects language (English / Hindi / Telugu), taps mic, speaks the patient's answer, taps send. Web Speech API transcribes the answer; the system converts it to English before sending to the LLM. Staff can review and correct the transcription before hitting enter. LLM analyzes the response and returns the next clinically relevant question. Cycle repeats.

### Flow 6 — Completion
LLM signals INTAKE_COMPLETE. Screen shows "Intake complete" and lists any flagged questions — those where the patient or staff responded with "no", "I don't know", "NA", or equivalent. Staff can continue answering those specific questions or submit for summary.

### Flow 7 — Summary and Ask More
Summary generated within 30 seconds and displayed in structured sections. Full conversation history is preserved in the session. "Ask More?" button on the summary screen continues the same session — full conversation history passed as context so the LLM picks up from exactly where it left off. No new patient record or ID is created. For a different patient, staff goes to Intake List and clicks "New Intake". Session data and conversation history are wiped after the retention window.

---

## 7. User Stories

### Medical Staff / Cardiologist

| ID | User Story | Priority |
|---|---|---|
| US-001 | As a staff user, I want to see all patient intakes in a list so I can find and continue any session | High |
| US-002 | As a staff user, I want to start a new patient intake by entering the patient's basic information | High |
| US-003 | As a staff user, I want the LLM to show me all standard questions it will cover when the session starts so I know the full scope | High |
| US-004 | As a staff user, I want to tap a mic button, speak the patient's answer, and have it transcribed automatically | High |
| US-005 | As a staff user, I want to read the transcription, correct it if needed, and submit it | High |
| US-006 | As a staff user, I want the next question to appear based on what was just answered so the intake flows naturally | High |
| US-007 | As a staff user, I want to see which questions were flagged when intake completes and choose to continue answering or submit | High |
| US-008 | As a staff user, I want to receive a structured patient summary within 30 seconds of submitting the session | High |
| US-009 | As a staff user, I want an "Ask More?" button after the summary so I can continue the same patient's session without creating a new one | High |
| US-010 | As a staff user, I want the session to auto-save so I don't lose data if the device or network fails | High |
| US-011 | As a staff user, I want to resume an interrupted session from exactly where it was left off, with the full conversation history intact | High |
| US-012 | As a staff user, I want to type an answer manually if the mic is not working | Medium |

### Admin

| ID | User Story | Priority |
|---|---|---|
| US-013 | As an Admin, I want to log in and create staff accounts with a role attached so my team can access the system | High |
| US-014 | As an Admin, I want to set a 6-digit PIN for each staff account, see it when I set it, and share it with them directly | High |
| US-015 | As an Admin, I want to reset a staff member's PIN when they forget it, and share the new PIN with them | High |
| US-016 | As an Admin, I want to deactivate a staff account when someone leaves the team | Medium |

---

## 8. Functional Requirements

| ID | Requirement | User Story |
|---|---|---|
| FR-001 | System displays all patient intake sessions in a list (patient ID, name, age, gender, created date, department, status) with a "New Intake" button | US-001 |
| FR-002 | System collects patient basic info (patient ID entered manually by staff, name, age, gender); if the entered patient ID already has an active session in the retention window, system shows an error and directs staff to continue that session | US-002 |
| FR-003 | When a session starts, the LLM's first response is an overview of all standard CT Surgery intake questions it will cover; adaptive Q&A begins immediately after | US-003 |
| FR-004 | System guides staff through AI-adaptive Q&A — one question at a time; LLM decides the next question based on the patient's response and full conversation history | US-004, US-006 |
| FR-005 | System captures audio via browser mic (Web Speech API); supports English, Hindi, Telugu; transcription displayed for staff review; transcription converted to English before being sent to the LLM | US-004, US-005 |
| FR-006 | Staff can manually type or edit transcribed text before submitting | US-005, US-012 |
| FR-007 | LLM generates only clinically relevant follow-up questions; does not ask irrelevant or repetitive questions | US-006 |
| FR-008 | System signals INTAKE_COMPLETE; displays flagged questions (answered with "no", "I don't know", "NA", or equivalent); staff can continue answering or submit for summary | US-007 |
| FR-009 | System generates a structured patient summary within 30 seconds of session submission | US-008 |
| FR-010 | Summary screen includes "Ask More?" button; clicking it re-enters Q&A for the same session with full conversation history as context; no new patient record or session created | US-009 |
| FR-011 | System auto-saves session data on every response submission | US-010 |
| FR-012 | System resumes interrupted sessions from the exact last saved response; full conversation history available to any logged-in user who opens the session | US-011 |
| FR-013 | Session data and conversation history are retained for a configurable period (env var `DATA_RETENTION_HOURS`, default 48 hours); automatically purged after expiry | US-001 |
| FR-014 | Admin account is pre-seeded; admin creates staff accounts with name, email, role (attached at creation), department, and 6-digit PIN; admin can update and deactivate accounts | US-013, US-016 |
| FR-015 | Admin sets a 6-digit PIN per staff account — the PIN is visible to the Admin at the time of setting so it can be shared with the staff member; once saved, the PIN is stored as a bcrypt hash and cannot be retrieved from the system | US-014 |
| FR-016 | Admin can reset a staff member's PIN — new PIN is visible to Admin at the time of reset for sharing; replaces the old hash in the system | US-015 |

---

## 9. Non-Functional Requirements

| Category | Requirement |
|---|---|
| **Performance** | Patient summary generation ≤ 30 seconds |
| **Performance** | Adaptive question response ≤ 2 seconds |
| **Performance** | Standard UI operations ≤ 2 seconds |
| **Security** | Email + PIN login; PIN stored as bcrypt hash |
| **Security** | JWT issued on login; 30-minute inactivity timeout |
| **Security** | 5 consecutive failed PIN attempts locks account; Admin must unlock |
| **Security** | Data encrypted in transit (HTTPS, standard TLS enforced by nginx) |
| **Reliability** | System uptime 99.9% during hospital operating hours |
| **Reliability** | Session auto-saved on every response — no data loss on interruption |
| **Data** | Session data and conversation history retained for `DATA_RETENTION_HOURS` (default 48 hours); purged automatically after expiry |
| **Data** | No permanent patient data stored beyond the retention window |
| **Usability** | Zero-training interface — staff can operate immediately |
| **Concurrency** | Maximum 5 simultaneous active sessions |

---

## 10. Acceptance Criteria

### FR-001 — Intake List
- All patient sessions visible to all logged-in users
- Table shows: patient ID, name, age, gender, created date, department, status (In Progress / Summary Ready)
- "New Intake" button navigates to patient info entry
- Clicking any row opens that session — in-progress opens in Q&A; completed opens in summary view

### FR-002 — Patient Info and Duplicate Check
- Staff manually enters patient ID, name, age, gender
- If entered patient ID already has an active session in the retention window, system shows an error and presents an option to continue that session
- No duplicate session is created for an existing active patient ID

### FR-003 — LLM Question Overview
- LLM's first message lists all standard CT Surgery questions it will cover
- Overview displayed before the first adaptive question is asked
- Q&A begins immediately after the overview

### FR-004 / FR-007 — Adaptive Q&A
- LLM returns exactly one question per response
- Follow-up questions asked only when clinically warranted by the patient's answer
- LLM does not repeat questions already answered in the session
- LLM never uses diagnostic or emergency language

### FR-005 — Audio Input and Transcription
- Mic button visible and activates on a single tap
- Web Speech API captures and transcribes speech in selected language (English / Hindi / Telugu)
- Transcription displayed for staff review; editable before submission
- Transcription converted to English before being sent to LLM
- If mic is unavailable or Web Speech API fails, staff can type directly

### FR-008 — Completion and Flagged Questions
- LLM signals INTAKE_COMPLETE when all required questions are covered
- System displays flagged questions: those answered with "no", "I don't know", "NA", or equivalent
- Two options: "Continue Answering" or "Submit for Summary"

### FR-009 — Patient Summary
- Summary generated within 30 seconds of submission
- Structured sections: Chief Complaint, Cardiac Symptoms, Respiratory Symptoms, Medical History, Family History, Medications & Allergies, Lifestyle, Prior Investigations, Additional Notes
- All captured information included — nothing omitted
- No diagnostic language or treatment suggestions
- Sections with no captured data show: "Not reported"

### FR-010 — Ask More
- "Ask More?" button visible on summary screen
- Clicking it opens Q&A for the same session — no new patient ID or session created
- Full conversation history passed to LLM as context

### FR-013 — Session Retention
- `DATA_RETENTION_HOURS` env var controls the retention window (default 48)
- Sessions and conversation history automatically purged after the window closes
- Cron job runs hourly to purge expired data

### FR-014 / FR-015 / FR-016 — Admin and Auth
- Admin account exists in DB before any staff login
- Admin creates staff accounts: name, email, role (attached at creation), department, 6-digit PIN
- Admin sees the PIN at the time of setting and can write it down to share with staff
- Once saved, PIN is stored as bcrypt hash — not retrievable from the system
- Staff logs in with email + PIN; receives JWT valid for 30 minutes
- 5 failed PIN attempts locks the account; admin must unlock
- Admin can reset a staff member's PIN; new PIN visible at reset time for sharing

---

## 11. UX — Screens

### Screen 1 — Intake List (Home after login)
- Table: patient ID, name, age, gender, created date, department, status (In Progress / Summary Ready)
- "New Intake" button — top right
- Tap any row to open that session

### Screen 2 — Intake Session

**Step A — Patient Info Entry**
- Form: patient ID (manual entry), name, age, gender
- Validation: if patient ID already has an active session, show error with option to navigate to that session
- "Start Session" button

**Step B — Chat Interface (Q&A)**
- On session start, LLM's first message lists all standard CT Surgery questions it will cover, then asks question 1
- Chat-style layout — LLM messages on one side, staff responses on the other
- Language selector: English / Hindi / Telugu
- Large mic button at the bottom — single tap to start, single tap to stop
- Transcription appears in editable text area
- Send button to submit and trigger next LLM question
- Progress indicator: questions answered out of total base questions

**Step C — Completion**
- "Intake complete" message from LLM
- List of flagged questions if any
- Two buttons: "Continue Answering" / "Submit for Summary"

### Screen 3 — Summary
- Patient info header: ID, name, age, gender, date
- Structured summary in labelled sections
- "Ask More?" button — for the same patient's session only

### Screen 4 — Account Management (Admin)
- List of staff accounts with status (Active / Deactivated)
- "Add Staff" form: name, email, role (dropdown), department, 6-digit PIN field
- PIN is shown to Admin during creation and reset — not masked at the time of entry so Admin can note it for sharing
- Once saved, PIN is not retrievable from the system
- Actions per account: Edit, Reset PIN, Deactivate

---

## 12. Language Support

**Supported languages:** English (default), Hindi, Telugu

Staff select their input language before or during the session via the language selector. Web Speech API captures and transcribes speech in the selected language. The system converts the transcription to English before sending to the LLM. The LLM always receives context and responds in English.

Staff can change the language mid-session — the selector applies per response.

---

## 13. Dependencies

| Dependency | Owner | Risk |
|---|---|---|
| CT Surgery question protocol content | Cardiothoracic Surgeon | High — sample available; final protocol to be provided by hospital |
| Claude API access and quota | Anthropic | Low |
| Web Speech API browser support | Browser (Chrome / Chromium recommended) | Medium — accuracy and language support varies by browser and network |
| Hospital network infrastructure (5G / WiFi) | Hospital IT | Medium — Web Speech API requires active internet connection |
| Handheld device procurement | Hospital | Medium |

---

## 14. Open Questions

No open questions remaining.

---

## 15. Authentication

Admin account is pre-seeded in the database before deployment. All other accounts are created by the Admin.

### Login Flow

```
Staff opens app
     ↓
Enters registered email
     ↓
Enters 6-digit PIN (set by Admin at account creation)
     ↓
System validates email + PIN
     ↓
JWT issued (30-minute expiry) → Staff lands on Intake List
```

### Account Creation (Admin)

```
Admin logs in
     ↓
Opens Account Management screen
     ↓
Creates staff account: name, email, role (selected at creation), department
     ↓
Sets 6-digit PIN — Admin sees the PIN on screen at this point
     ↓
Admin notes and shares the PIN with staff directly (verbally or in writing)
     ↓
PIN is saved as a bcrypt hash — not retrievable from system after this point
     ↓
Staff logs in with email + PIN
```

### PIN Reset

```
Staff cannot access account
     ↓
Admin opens Account Management
     ↓
Sets a new 6-digit PIN for that account — Admin sees the new PIN on screen
     ↓
Admin shares the new PIN with staff
     ↓
New PIN replaces old hash in the system — not retrievable after this point
```

### Rules
- PIN is 6 digits; set and reset only by Admin — staff cannot self-set
- Admin sees the PIN at the time of setting or resetting and is responsible for sharing it
- Once saved, PIN is stored as a bcrypt hash — the system cannot display it again
- 5 consecutive failed attempts locks the account — Admin must unlock
- JWT expires after 30 minutes of inactivity — re-login required