# Cancer Patient Management System - Architecture

## System Overview

A comprehensive oncology care platform managing 8 real cancer patient cases with full medication protocols, role-based access, clinical alerting, and automated testing.

## Architecture Layers

```
+--------------------------------------------------+
| PRESENTATION LAYER (Browser)                      |
| Single-page HTML/CSS/JS application               |
| Role-based UI (Admin/Doctor/Nurse/Patient views)  |
+--------------------------------------------------+
           | HTTP/JSON API
+--------------------------------------------------+
| API LAYER (Python HTTP Server)                    |
| REST-like endpoints, session authentication       |
| Role-based access control, audit logging          |
+--------------------------------------------------+
           | SQLite queries
+--------------------------------------------------+
| DATA LAYER (SQLite with WAL)                      |
| 11 tables, 10 indexes, foreign keys               |
| 8 patient cases, 35+ medications, 8 alerts        |
+--------------------------------------------------+
```

## Database Schema (11 Tables)

| Table | Records | Purpose |
|-------|---------|---------|
| users | 17 | User accounts (1 admin, 4 doctors, 4 nurses, 8 patients) |
| patients | 8 | Cancer patient cases with full clinical data |
| medications | 35+ | Medication protocols with dosing, side effects, monitoring |
| treatment_cycles | 9 | Chemotherapy cycle tracking |
| vital_signs | 14+ | Temperature, HR, BP, SpO2, pain scores |
| lab_results | 18+ | Lab values with reference ranges and abnormal flags |
| symptom_reports | 12+ | Patient-reported symptoms with severity |
| alerts | 8 | Clinical alerts (critical/high/medium/low) |
| nurse_patient_assignments | 8 | Staff-patient alignment |
| audit_log | 10+ | System activity tracking |
| test_results | - | Test execution records |

## Cancer Cases Included

| Code | Cancer Type | Stage | Treatment Protocol | Key Medications |
|------|------------|-------|-------------------|-----------------|
| ONC-2024-001 | Breast Cancer (HER2+) | IIB | TCHP | Docetaxel, Carboplatin, Trastuzumab, Pertuzumab |
| ONC-2024-002 | Lung Cancer (NSCLC) | IIIA | CRT + Durvalumab | Cisplatin, Etoposide, Durvalumab |
| ONC-2024-003 | Colorectal Cancer | IIIC | FOLFOX + Bevacizumab | Oxaliplatin, 5-FU, Bevacizumab |
| ONC-2024-004 | Prostate Cancer (mCRPC) | IV | Cabazitaxel | Cabazitaxel, Enzalutamide, Prednisone |
| ONC-2024-005 | Acute Myeloid Leukemia | de novo | 7+3 Induction | Cytarabine, Daunorubicin |
| ONC-2024-006 | Hodgkin Lymphoma | IIB | ABVD | Doxorubicin, Bleomycin, Vinblastine, Dacarbazine |
| ONC-2024-007 | Pancreatic Cancer | IIIB | mFOLFIRINOX | Oxaliplatin, Irinotecan, 5-FU |
| ONC-2024-008 | Ovarian Cancer | IV | Carbo/Paclitaxel + Olaparib | Cisplatin, Paclitaxel, Olaparib |

## Role-Based Access Control

| Role | View Scope | Edit Scope | Special Permissions |
|------|-----------|------------|---------------------|
| Admin | All patients, all data | Users, system settings | Audit log, full control |
| Doctor | Assigned patients | Medications, treatment plans | Prescribing, alert acknowledgment |
| Nurse | Assigned patients | Vitals, symptoms, nursing notes | Vital signs recording |
| Patient | Own records only | Self-reported symptoms | View medications, schedule |

## Clinical Alert System

Automatic alerts trigger on:
- **Critical**: Febrile neutropenia (ANC <500 + temp >=38.3C), anaphylaxis, sepsis
- **High**: SpO2 <94%, cumulative neuropathy Grade >=2, pulmonary symptoms on bleomycin
- **Medium**: Rising tumor markers, LVEF monitoring overdue, bone pain >=7/10
- **Low**: Routine follow-up reminders, medication refill needed

## API Endpoints (17 endpoints)

- `POST /api/login` - Authentication
- `GET /api/patients` - List patients (role-filtered)
- `GET /api/patients/:id` - Patient detail
- `GET /api/patients/:id/medications` - Patient medications
- `GET /api/patients/:id/vitals` - Vital signs
- `GET /api/patients/:id/labs` - Lab results
- `GET /api/patients/:id/symptoms` - Symptom reports
- `GET /api/patients/:id/cycles` - Treatment cycles
- `GET /api/patients/:id/alerts` - Patient alerts
- `GET /api/alerts` - All alerts (filterable)
- `GET /api/users` - User list (admin/doctor)
- `GET /api/nurse-assignments` - Nurse-patient assignments
- `GET /api/audit-log` - Audit log (admin)
- `GET /api/dashboard/stats` - Dashboard statistics
- `POST /api/vitals` - Record vitals
- `POST /api/symptoms` - Report symptoms
- `POST /api/alerts/acknowledge` - Acknowledge alerts

## Testing System

20 automated tests covering:
1. Database connectivity and data integrity
2. All 8 patient cases loaded correctly
3. Medication records with full clinical detail
4. Vital signs, labs, symptoms, cycles populated
5. Alert system with critical/high/medium/low severity
6. User accounts and role assignments
7. Nurse-patient alignment
8. Audit log tracking
9. Authentication enforcement
10. Cross-patient data aggregation

## File Structure

```
CancerPatientSystem/
  database.py          - SQLite schema, connection, password hashing
  seed_data.py         - 8 cancer cases, 35+ medications, vitals, labs, alerts
  api_server.py        - HTTP API server with 17 endpoints
  cancer_patients.db   - SQLite database (auto-created)
  static/
    index.html         - Single-page application UI
  docs/
    SYSTEM_ARCHITECTURE.md  - This file
    README.md               - Setup and usage guide
  tests/
    test_runner.py     - Automated test suite
```

## Deployment

1. No dependencies required (Python standard library only)
2. Run: `python api_server.py`
3. Opens browser at http://127.0.0.1:8080
4. Database auto-creates with demo data on first run

## Data Sources

Patient cases based on published oncology protocols:
- TCHP for HER2+ breast cancer (NCCN guidelines)
- Concurrent chemoradiation + durvalumab for NSCLC (PACIFIC trial)
- FOLFOX + bevacizumab for colorectal (NO16966 trial)
- Cabazitaxel for mCRPC (TROPIC trial)
- 7+3 induction for AML (standard ELN protocol)
- ABVD for Hodgkin lymphoma (standard first-line)
- mFOLFIRINOX for pancreatic (PRODIGE trial)
- Olaparib maintenance for BRCA+ ovarian (SOLO-1 trial)