Project: HAD Digital MVP Skeleton

Architecture

System Architecture Overview

The HAD Digital MVP (Hospitalisation à Domicile Oncology Care Platform) is designed as a zero-dependency, local-first standalone Windows application.

+-------------------------------------------------------------------------+
|                  HAD Digital MVP - Standalone Architecture              |
+-------------------------------------------------------------------------+
| [Client Browser] (Chrome / Edge / Firefox)                              |
|        ^                                                                |
|        | HTTP / REST (127.0.0.1:8080) - HttpOnly Session Cookies       |
|        v                                                                |
| [ThreadingHTTPServer] (Pure Python Stdlib, zero external dependencies)  |
|    ├── Static Asset Handler (serves bundled HTML5 / CSS3 / Vanilla JS)  |
|    ├── REST API Router (19 endpoints: auth, reports, timeline, etc.)   |
|    └── Security Headers (CSP, X-Content-Type-Options, X-Frame-Options)  |
|        │                                                                |
|        ├──> [CTCAE Grading Engine] <── [ctcae_rules.json] (Bundled)     |
|        ├──> [Alert Engine] (Routine / Urgent / Emergency routing)       |
|        ├──> [Audit Logger] (Immutable append-only audit trail)          |
|        └──> [User Store & Auth] (scrypt password hashing + salt)        |
|                 │                                                       |
|                 v                                                       |
|        [Database Manager] (SQLite with WAL mode, foreign keys, thread-local)
|                 │                                                       |
|                 v                                                       |
|        [Persistent Data Storage] (Outside sys._MEIPASS)                 |
|        ├── data/had.db (Users, Patients, Reports, Grades, Timeline)     |
|        └── logs/audit.log                                               |
+-------------------------------------------------------------------------+

Storage Decoupling Architecture

To prevent the PyInstaller _MEIPASS ephemeral data-loss bug:

• get_bundle_dir(): Resolves to sys._MEIPASS when frozen (or project root when in dev mode) for read-only bundled assets (static/, data/ctcae_rules.json, guidance/guidance.json).

• get_data_dir(): Resolves to persistent storage outside sys._MEIPASS:
• Portable mode: Path(sys.executable).parent / "data" (if writable).
• Installed fallback: %LOCALAPPDATA%\HAD Digital\data.
• Configurable override: HAD_DB_PATH environment variable.

Feature Inventory

Milestones

Interface Contracts

Client Frontend ↔ Backend REST API (/api)

• Authentication: POST /api/login
• Request: {"username": "...", "password": "..."}
• Response (200): {"ok": true, "message": "Login successful", "user": {"id": 1, "username": "...", "role": "...", "display_name": "..."}}
• Cookie: Set-Cookie: HAD_SESSION=<uuid>; Path=/; HttpOnly; SameSite=Lax

• Session Check: GET /api/whoami
• Response (200): {"authenticated": true, "user": {...}} or (401): {"authenticated": false}

• Toxicity Report Submission: POST /api/reports
• Request format A (Flat): {"patient_id": 1, "symptom_id": "nausea", "symptom_category": "gastrointestinal", "severity_score": 2, "notes": "..."}
• Request format B (Questionnaire Map): {"patient_id": 1, "symptoms": {"nausea": 2, "fatigue": 1}, "notes": "..."}
• Response (201): {"ok": true, "message": "Report submitted", "report_id": 8, "grading": {...}, "alert": {...}}

• Care Timeline: GET /api/timeline?patient_id=<id>
• Response (200): {"events": [{"id": 1, "patient_id": 1, "event_type": "toxicity_report", "event_date": "...", "title": "...", "description": "...", "severity": "...", "metadata": {...}}, ...]}

Server Runtime ↔ Storage Engine

• get_bundle_dir(): Returns root directory of read-only assets (static/, data/ctcae_rules.json, guidance/guidance.json).

• get_data_dir(): Returns writable directory for had.db and logs. If had.db is missing, triggers idempotent seed_demo_data().

Code Layout

c:\AI Projects\Kais Project\
├── 00_Governance/                 # Governance & Project Status
├── 01_System/                     # System specifications & architecture docs
├── 02_Requirements/               # Functional requirements & CTCAE rules
├── 03_Architecture/               # Architecture documents & API contracts
├── 04_Build/                      # Automated build scripts & PyInstaller spec
│   ├── build_exe.py              # Automated build script packaging single-file .exe
│   └── HAD Digital.spec          # Single-file PyInstaller specification
├── 05_Test/                       # Comprehensive E2E test suite & verification harness
│   ├── verify_mvp.py             # Standalone programmatic verification script
│   ├── test_e2e_tier1.py         # Tier 1: Feature coverage tests
│   ├── test_e2e_tier2.py         # Tier 2: Boundary & corner cases
│   ├── test_e2e_tier3.py         # Tier 3: Cross-feature combination tests
│   ├── test_e2e_tier4.py         # Tier 4: Clinical workflow scenarios
│   └── test_e2e_tier5_adversarial.py # Tier 5: Adversarial hardening & stress tests
├── MVP/                           # Application source code
│   ├── app.py                    # ThreadingHTTPServer & REST API routing
│   ├── config_manager.py         # Storage path decoupling & configuration
│   ├── database.py               # SQLite WAL thread-local database manager
│   ├── user_store.py             # Scrypt authentication & session management
│   ├── ctcae_engine.py           # CTCAE v5.0 rule evaluation
│   ├── alert_engine.py           # Triage & alert routing
│   ├── audit_logger.py           # Immutable audit logging
│   ├── seed_demo.py              # Demo patient & user data seeder
│   ├── static/                   # Frontend assets
│   │   ├── index.html            # Single Page Application HTML shell
│   │   ├── app.css               # Responsive design & component styling
│   │   └── app.js                # Frontend routing, auth, form & timeline logic
│   ├── data/                     # ctcae_rules.json
│   └── guidance/                 # guidance.json
├── dist/                          # Output directory for compiled standalone .exe
│   └── HAD Digital.exe           # Single-file standalone Windows executable (9.78 MB)
└── PROJECT.md                     # Living project scope & architecture index