SYSTEM_BREAKDOWN.md · Workspace

# System Breakdown

Project: HAD Digital Version: 1.0.0 Date: 2026-09-05 Owner: Dr Kais Aldabbagh

System Overview

HAD Digital is a coordinated digital platform for Hospitalisation a Domicile (HAD) in oncology. It provides structured toxicity monitoring, clinical alerting, and care coordination for home-care cancer patients.

Subsystems

1. Frontend Subsystem

Component	Description	Files
HTML Interface	Main web page	static/index.html
CSS Styles	Responsive design	static/app.css
JavaScript Logic	Application logic	static/app.js

Dependencies: None (self-contained)

Interfaces:

IF-01: Patient UI (HTTP/HTML)

IF-02: Clinician UI (HTTP/HTML)

2. Backend Subsystem

Component	Description	Files
HTTP Server	Main server	app.py
Configuration	Config management	config_manager.py
Database	Data persistence	database.py
Authentication	User auth	user_store.py
CTCAE Engine	Toxicity grading	ctcae_engine.py
Alert Engine	Alert routing	alert_engine.py
Audit Logger	Audit trail	audit_logger.py
Demo Data	Demo seeder	seed_demo.py

Dependencies: Frontend Subsystem, Database Subsystem

Interfaces:

IF-03: REST API (HTTP/JSON)

IF-05: CTCAE Engine (Python)

IF-06: Alert Engine (Python)

IF-09: Audit Logger (Python)

3. Database Subsystem

Component	Description	Files
SQLite Database	Data storage	data/had.db
CTCAE Rules	Grading rules	data/ctcae_rules.json
Guidance Content	Patient guidance	guidance/guidance.json

Dependencies: None (self-contained)

Interfaces:

IF-04: SQLite Database (SQL)

4. AI Adapter Subsystem

Component	Description	Files
Base Adapter	Interface	adapters/base.py
Stub Adapter	Offline demo	adapters/stub.py
GLM Adapter	Online AI	adapters/glm.py

Dependencies: Backend Subsystem

Interfaces:

IF-07: AI Adapter (HTTP/JSON)

Data Flow

Patient/Clinician
       │
       ▼
   Frontend (HTML/CSS/JS)
       │
       ▼
   HTTP Server (app.py)
       │
       ├──► CTCAE Engine (ctcae_engine.py)
       │         │
       │         ▼
       │    Alert Engine (alert_engine.py)
       │
       ├──► Database (database.py)
       │         │
       │         ▼
       │    SQLite (had.db)
       │
       ├──► Audit Logger (audit_logger.py)
       │
       └──► AI Adapter (adapters/)

Integration Points

From	To	Interface	Protocol
Frontend	HTTP Server	IF-03	HTTP/JSON
HTTP Server	Database	IF-04	SQL
HTTP Server	CTCAE Engine	IF-05	Python
HTTP Server	Alert Engine	IF-06	Python
HTTP Server	AI Adapter	IF-07	HTTP/JSON
HTTP Server	Audit Logger	IF-09	Python

Dependencies

External Dependencies

None (pure Python standard library)

Internal Dependencies

Component	Depends On
app.py	config_manager, database, user_store, ctcae_engine, alert_engine, audit_logger, seed_demo, adapters
database.py	config_manager
user_store.py	database
ctcae_engine.py	database
alert_engine.py	database
audit_logger.py	database
seed_demo.py	database