# Jira Stories — Milestone 1 ## AI-Guided CT Surgery Patient Intake System 4 Epics · 18 Stories --- ## Epic 1 — FOUNDATION --- **NIMS-1 | Development environment is set up and running** *As a developer, I can run the entire stack locally with one command so I can start building.* Subtasks - Create monorepo structure (`frontend/`, `backend/`, `docs/`) - Set up Docker Compose with 4 services (frontend, fastapi, postgres, redis) - Create FastAPI skeleton with `/health` endpoint - Create database models and run first Alembic migration - Seed CT Surgery department, question bank, and admin account Acceptance Criteria - [ ] `docker compose up --build` starts all services without errors - [ ] `GET /health` returns 200 - [ ] `http://localhost:3000` loads in browser - [ ] All 8 database tables exist after migration - [ ] Seed data present: 1 department, 1 protocol (12 questions), 1 admin account --- **NIMS-2 | Staff can log in with email and PIN** *As a medical staff, I can log in using my email and 6-digit PIN so I can access the intake system.* Subtasks - Implement `POST /auth/login` - Implement `POST /auth/logout` - Implement account lockout after 5 failed attempts Acceptance Criteria - [ ] Valid credentials → access granted, redirected to session list - [ ] Wrong PIN → "Invalid email or PIN" shown - [ ] 5 wrong PINs → account locked → "Account locked. Contact Admin." - [ ] Inactive account → "Account deactivated. Contact Admin." - [ ] System at max 5 users → "System at capacity. Try again shortly." - [ ] Closing the tab ends the session — re-login required --- **NIMS-3 | Admin can create and manage staff accounts** *As an Admin, I can create staff accounts and manage access so my team can use the system.* Subtasks - Implement `POST /staff` - Implement `PATCH /staff/{id}` (update, deactivate, unlock, reset PIN) - Build account management screen in React Acceptance Criteria - [ ] Admin can create an account with name, role, email, and PIN - [ ] PIN shown once at creation — "Share with staff. Won't show again." - [ ] Duplicate email → "This email is already registered." - [ ] Admin can reset a staff member's PIN — new PIN shown once - [ ] Admin can deactivate an account — that staff can no longer log in - [ ] Admin can unlock a locked account — staff can attempt login again --- ## Epic 2 — PATIENT INTAKE --- **NIMS-4 | Staff can view all intake sessions for their department** *As a medical staff, I can see a list of all patient sessions so I know what's in progress and what's done.* Subtasks - Implement `GET /sessions` - Build intake list screen in React Acceptance Criteria - [ ] All sessions for the department shown on load - [ ] Each session shows patient name, daily ID, and status (In Progress / Completed) - [ ] Tapping a session opens it - [ ] Empty state shown when no sessions exist - [ ] Sessions from other departments are never shown --- **NIMS-5 | Staff can start a new intake session for a patient** *As a medical staff, I can enter a patient's details to begin a new intake session.* Subtasks - Implement `POST /sessions` — new session path - Build patient info form in React (Daily ID, Name, Age, Gender) Acceptance Criteria - [ ] Staff enters daily patient ID, name, age, gender and submits - [ ] New session created → AI's opening question appears immediately - [ ] Daily patient ID already has a session today → directed to existing session - [ ] Session currently in use by another staff → "In use by [name]. Try again shortly." --- **NIMS-6 | Staff can resume an interrupted intake session** *As a medical staff, I can re-enter a patient's daily ID and pick up exactly where another staff left off.* Subtasks - Implement `POST /sessions` — resume path - Build resume state in Q&A screen showing intake history Acceptance Criteria - [ ] Entering an existing patient's daily ID resumes the session, not creates a new one - [ ] All previously captured answers visible - [ ] AI continues from where the session left off - [ ] Intake history panel shows who contributed to the session, in order - [ ] Same staff re-entering → no duplicate in intake history --- **NIMS-7 | Staff can answer intake questions using voice or text** *As a medical staff, I can speak or type the patient's answers so the AI can guide me to the next question.* Subtasks - Implement `POST /sessions/{id}/respond` - Build Q&A screen — mic button, transcription field, language selector, submit - Wire `useSpeechRecognition` hook (English / Hindi / Telugu) Acceptance Criteria - [ ] One question shown at a time - [ ] Tapping mic starts recording; transcribed text appears in an editable field - [ ] Staff can correct transcription before submitting - [ ] Language can be switched between English, Hindi, and Telugu - [ ] If mic unavailable → text input shown automatically - [ ] Next question loads within 2 seconds of submitting an answer - [ ] Each answer saved immediately — no data lost if interrupted --- **NIMS-8 | Staff can complete intake and see flagged answers** *As a medical staff, I know when intake is complete and I can review any weak or missing answers before submitting.* Subtasks - Implement `is_flagged` scan at INTAKE_COMPLETE - Build completion screen showing flagged answers list Acceptance Criteria - [ ] AI signals when all required questions are covered - [ ] Completion screen lists all flagged answers (vague or non-answers like "no", "NA", "I don't know") - [ ] Each flagged item shows the question and sequence number - [ ] Staff reviews the list and submits to generate the summary - [ ] Submit button only available after AI signals completion --- **NIMS-9 | Staff can view the patient summary after intake** *As a medical staff or surgeon, I can read a structured patient summary generated from the intake conversation.* Subtasks - Implement `POST /sessions/{id}/complete` with summary generation - Implement `GET /sessions/{id}/summary` - Build summary screen in React Acceptance Criteria - [ ] Summary generated and displayed within 30 seconds of submit - [ ] Summary has clearly labelled sections: Chief Complaint, Cardiac Symptoms, Respiratory Symptoms, History, Medications, Lifestyle, Investigations - [ ] All captured information present — nothing missing - [ ] No diagnostic language or treatment suggestions in summary - [ ] Summary loadable from the session list (completed sessions) --- **NIMS-10 | Staff can re-open a completed session to ask more questions** *As a medical staff, I can go back into a completed session to capture additional information the patient just shared.* Subtasks - Implement `POST /sessions/{id}/ask-more` - Build Ask More button on summary screen Acceptance Criteria - [ ] Ask More button visible on summary screen - [ ] Clicking it reopens the session and shows the next question from AI - [ ] AI has full context of everything already asked — no repetition - [ ] If different staff re-opens → they are added to the intake history - [ ] Completing again generates an updated summary (previous one replaced) - [ ] System at capacity → "System at capacity. Try again shortly." --- ## Epic 3 — AI ENGINE --- **NIMS-11 | AI asks the next most clinically relevant question** *As a medical staff, I receive the next question from AI based on what the patient just said so the intake is thorough and adaptive.* Subtasks - Create `app/services/claude.py` - Implement `get_next_question()` using Anthropic SDK - Wire into `POST /sessions/{id}/respond` Acceptance Criteria - [ ] First question includes a brief overview of what will be covered - [ ] Each question follows logically from the patient's previous answer - [ ] All required CT Surgery base questions covered before AI signals completion - [ ] AI handles Hindi and Telugu answers — always responds in English - [ ] Next question appears within 2 seconds - [ ] No diagnostic language in any AI output ("diagnose", "heart attack", "emergency") --- **NIMS-12 | AI generates a structured patient summary** *As a surgeon, I receive a clean structured summary of the patient's intake so I can prepare for consultation.* Subtasks - Implement `generate_summary()` using Anthropic SDK - Wire into `POST /sessions/{id}/complete` Acceptance Criteria - [ ] Summary generated within 30 seconds - [ ] Contains all sections: Chief Complaint, Cardiac Symptoms, Respiratory Symptoms, Cardiac History, Medications, Allergies, Lifestyle, Family History, Investigations - [ ] All information from the intake conversation is reflected in the summary - [ ] No diagnosis or treatment language in summary - [ ] Summary generation time recorded for monitoring --- ## Epic 4 — PLATFORM --- **NIMS-13 | Patient data is automatically deleted after the retention period** *As a system, patient data is wiped after the configured retention window so the hospital stays compliant.* Subtasks - Implement `purge_expired_patients()` hourly APScheduler task - Set `patients.expires_at` at session creation based on `DATA_RETENTION_HOURS` Acceptance Criteria - [ ] Patient rows deleted automatically when `expires_at` passes - [ ] All child data deleted: sessions, responses, summary (cascade delete) - [ ] Redis keys expire automatically via TTL — no manual cleanup - [ ] Retention window configurable via `DATA_RETENTION_HOURS` env var (default 48h) --- **NIMS-14 | System enforces maximum 5 concurrent sessions** *As a system, no more than 5 staff can be active at the same time so the system stays stable.* Subtasks - Implement concurrent session count check at login - Implement concurrent session count check at Ask More Acceptance Criteria - [ ] 6th login attempt → "System at capacity. Try again shortly." - [ ] Slot freed automatically when a staff logs out - [ ] Slot freed automatically when a session is completed - [ ] Slot freed automatically when JWT expires (30 min inactivity) - [ ] Ask More also blocked when at capacity --- **NIMS-15 | Session lock prevents two staff writing to the same patient at once** *As a medical staff, I won't accidentally overwrite another staff member's work on the same patient.* Subtasks - Implement Redis `patient_lock` — acquire on session start, release on complete/logout - Refresh lock TTL on every response submission Acceptance Criteria - [ ] Opening a session held by another staff → "In use by [name]. Try again shortly." - [ ] Lock auto-releases after 30 min of inactivity - [ ] Lock refreshed on every submitted answer — active sessions don't time out - [ ] Lock released immediately on logout or session complete --- **NIMS-16 | App is installable and works on hospital tablets** *As a medical staff, I can install the app on a tablet like a native app and use the mic without issues.* Subtasks - Configure PWA manifest (`display: standalone`, icons, start_url) - Set up HTTPS with self-signed or Let's Encrypt cert - Update nginx for HTTPS + HTTP redirect - Test mic on hospital tablet in Chrome Acceptance Criteria - [ ] Chrome shows "Add to Home Screen" prompt on first visit - [ ] App opens full screen with no browser bar when launched from home screen - [ ] Mic works — Web Speech API activates in Chrome on the hospital tablet - [ ] App served over HTTPS — plain HTTP redirects to HTTPS - [ ] Works on both tablet and mobile screen sizes --- **NIMS-17 | Every code change is automatically validated** *As a developer, I know immediately if a change breaks the build so nothing broken reaches main.* Subtasks - Create `.github/workflows/ci.yml` - Configure `main` branch protection (require PR + CI pass) - Add `ANTHROPIC_API_KEY` to GitHub secrets Acceptance Criteria - [ ] Pipeline runs automatically on every PR to `main` - [ ] Build failure → PR is blocked from merging - [ ] Health check failure → pipeline fails - [ ] API key not exposed in any pipeline logs --- **NIMS-18 | All intern branches are merged and the full app is validated before go-live** *As a team, we verify the complete system works end-to-end before handing it to the hospital.* Subtasks - Merge all feature branches to main - Run full intake session end-to-end in Docker - Verify 5 concurrent sessions under load - Sign off from TL Acceptance Criteria - [ ] Full intake session works: log in → start → answer all questions → complete → view summary → ask more → complete again - [ ] 5 staff can use the system simultaneously without errors - [ ] Patient data deleted after retention window expires - [ ] App works on hospital tablet — mic activates, summary renders - [ ] No console errors or API errors during a clean session