NIAMR · National Integrated AMR Surveillance System

System Architecture
Dataflow & Database Design

Full DFD (Level 0 → Level 3), database schema, and tech-stack breakdown for a functional AMR surveillance prototype targeting high-burden districts.

PHP · Web API Layer

Flutter · Mobile App

Python · AI/ML Engine

MySQL · Primary DB

FHIR / HL7 · Interop Layer

Redis · Cache / Queue

DFD · L0 Context Diagram — The Big Picture

Level 0 shows the NIAMR system as a single process bubble, its external entities, and the high-level data flows between them. No internal detail is shown at this level.

LEVEL 0 — CONTEXT DIAGRAM

Health Facilities

Send lab culture results, antibiogram data, and prescription records via the Flutter mobile app (online) or USSD/SMS (offline/low-resource). Data is received by the PHP REST API.

DHIS2 / HMIS Uganda

Bidirectional sync via FHIR R4 compliant API layer built in PHP. NIAMR pushes standardized AMR bundles and pulls aggregate health metrics for context modeling.

AI/ML Engine (Python)

Python microservice receives preprocessed data from the ETL pipeline via internal API. Runs predictive models (scikit-learn, TensorFlow) and returns predictions stored in MySQL.

MoH / WHO GLASS

NIAMR exports surveillance summaries as HL7 FHIR bundles (MeasureReport, DiagnosticReport) mapped with LOINC and SNOMED CT codes for international compliance.

DFD · L1 Major Processes — System Decomposition

Level 1 explodes the single NIAMR bubble into 6 major functional processes. Data stores and inter-process flows become visible.

LEVEL 1 — MAJOR PROCESSES

P1 — Data Collection & Validation (PHP)

REST API endpoints receive lab results, prescriptions, antibiogram data. Validates completeness, range checks, and duplication via PHP validation middleware. Queues records in Redis.

P2 — ETL Pipeline (Python)

Celery workers extract from Redis queue & open datasets. Applies SMOTE for class imbalance, KNN imputation for missing values. Outputs standardised records to DS2: Clean Data.

P3 — Interoperability Layer (PHP)

Maps clean data to FHIR R4 resources: DiagnosticReport, MedicationRequest. Applies LOINC (lab codes), SNOMED CT (organisms), ICD-11 (diagnoses). Syncs with DHIS2.

P4 — ML Analytics Engine (Python)

Scikit-learn Random Forest for resistance prediction. DBSCAN for geographic clustering. ARIMA/Prophet for consumption trend forecasting. Results persisted to DS4.

P5 — Early Warning System (Python + PHP)

Threshold rules + anomaly detection trigger SMS/push alerts via Africa's Talking API. Tracks prescriber behaviour indices and generates non-conformance flags.

P6 — Dashboard & Reporting (PHP)

PHP API serves Chart.js/Leaflet visualizations. Endpoints: /api/resistance-trends, /api/geo-clusters, /api/prescriber-report. Role-based access (DHO, Clinician, Admin).

DFD · L2 Sub-Process Decomposition — P2 ETL & P4 ML Engine

Level 2 decomposes the two most complex processes: the ETL pipeline (P2) and the ML Analytics Engine (P4). Each sub-process maps to a specific module in the Python codebase.

LEVEL 2 — P2: ETL PIPELINE DECOMPOSITION

LEVEL 2 — P4: ML ANALYTICS ENGINE DECOMPOSITION

DFD · L3 Detail Level — P1 Data Collection & P3 Interoperability

Level 3 shows granular internal logic for data ingestion (P1) and the FHIR interoperability layer (P3), including specific API endpoints, transformation rules, and terminology mappings.

LEVEL 3 — P1: DATA COLLECTION & VALIDATION (PHP)

LEVEL 3 — P3: FHIR/HL7 INTEROPERABILITY LAYER (PHP)

LOINC Mapping

Lab tests mapped: 18769-0 (Microbial susceptibility), 664-3 (Culture), 29576-6 (Antimicrobial MIC). Lookup table stored in MySQL with versioning.

SNOMED CT Mapping

Organisms: 59560006 (MRSA), 372687004 (E. coli), 88274000 (Klebsiella). Resistance mechanisms via SNOMED procedure codes.

ICD-11 Mapping

Diagnoses: XN109 (MRSA infection), 1C3Y (resistant bacterial infection). Used in FHIR Condition resources linked to each encounter.

FHIR R4 Resources Built

DiagnosticReport, Observation (MIC values), MedicationRequest, Patient, Encounter, Organization (facility), MeasureReport (aggregates).

DB MySQL Database Schema

All tables use UUID primary keys. Timestamps are stored as TIMESTAMPTZ. FHIR resources are also stored as JSONB for full-fidelity retrieval. Redis handles ephemeral queues and ML result caching.

Core Entities

facilities CORE

Column	Type	Notes
PKid	UUID	Primary key
mfl_code	VARCHAR(20)	Master Facility List code
name	VARCHAR(255)	Facility name
facility_type	ENUM	HC2/HC3/HC4/Hospital
district_id	UUID FK	→ districts
latitude	DECIMAL(9,6)	GPS coordinate
longitude	DECIMAL(9,6)	GPS coordinate
dhis2_org_unit	VARCHAR(100)	DHIS2 UID for sync
fhir_organization_id	VARCHAR(100)	FHIR Organization.id
created_at	TIMESTAMPTZ	Auto-set

patients CORE

Column	Type	Notes
PKid	UUID	Primary key
patient_code	VARCHAR(50)	De-identified code
age_group	ENUM	0-5,6-14,15-49,50+
sex	ENUM	M/F/Unknown
district_id	UUID FK	→ districts
facility_id	UUID FK	→ facilities
fhir_patient_id	VARCHAR(100)	FHIR Patient.id
created_at	TIMESTAMPTZ	Auto-set

districts CORE

Column	Type	Notes
PKid	UUID	Primary key
name	VARCHAR(100)	District name
region	VARCHAR(100)	Region of Uganda
population	INTEGER	Latest census
risk_level	ENUM	green/yellow/red
geom	GEOMETRY	PostGIS polygon

users CORE

Column	Type	Notes
PKid	UUID	Primary key
email	VARCHAR(255)	Unique
phone	VARCHAR(20)	For SMS alerts
role	ENUM	admin/dho/clinician/lab
facility_id	UUID FK	→ facilities
password_hash	VARCHAR(255)	bcrypt
last_login	TIMESTAMPTZ

Lab & Clinical Data

lab_specimens LAB

Column	Type	Notes
PKid	UUID	Primary key
patient_id	UUID FK	→ patients
facility_id	UUID FK	→ facilities
specimen_type	VARCHAR(100)	Blood/Urine/Sputum…
loinc_code	VARCHAR(20)	LOINC specimen code
collection_date	DATE
diagnosis_icd11	VARCHAR(20)	ICD-11 code
fhir_specimen_id	VARCHAR(100)	FHIR Specimen.id
source	ENUM	live/atlas/glass/upload

microbiology_results LAB

Column	Type	Notes
PKid	UUID	Primary key
specimen_id	UUID FK	→ lab_specimens
organism_name	VARCHAR(200)	e.g. E. coli
snomed_organism	VARCHAR(20)	SNOMED CT code
report_date	DATE
fhir_diagnostic_id	VARCHAR(100)	FHIR DiagnosticReport
data_quality_score	DECIMAL(4,2)	0-1 completeness score

susceptibility_tests LAB

Column	Type	Notes
PKid	UUID	Primary key
result_id	UUID FK	→ microbiology_results
antibiotic_id	UUID FK	→ antibiotics
mic_value	DECIMAL(8,3)	Minimum inhibitory conc.
interpretation	ENUM	S/I/R (EUCAST)
test_method	ENUM	disk/MIC/VITEK
loinc_test_code	VARCHAR(20)	LOINC 18769-0
fhir_observation_id	VARCHAR(100)	FHIR Observation.id

antibiotics REFERENCE

Column	Type	Notes
PKid	UUID	Primary key
name	VARCHAR(200)	Generic name
atc_code	VARCHAR(20)	WHO ATC code
class	VARCHAR(100)	e.g. Cephalosporin
who_access_group	ENUM	ACCESS/WATCH/RESERVE
snomed_code	VARCHAR(20)	SNOMED substance code

prescriptions CLINICAL

Column	Type	Notes
PKid	UUID	Primary key
patient_id	UUID FK	→ patients
prescriber_id	UUID FK	→ users
antibiotic_id	UUID FK	→ antibiotics
indication_icd11	VARCHAR(20)	ICD-11 indication
dose_mg	DECIMAL(8,2)
route	ENUM	oral/IV/IM
duration_days	INTEGER
is_empiric	BOOLEAN	Before culture result
guideline_compliant	BOOLEAN	Auto-checked
fhir_med_request_id	VARCHAR(100)	FHIR MedicationRequest
prescription_date	DATE

ETL Pipeline & Data Quality

etl_jobs PIPELINE

Column	Type	Notes
PKid	UUID	Primary key
job_type	ENUM	ingestion/validation/load
source_name	VARCHAR(100)	ATLAS/GLASS/Live
status	ENUM	queued/running/done/failed
records_in	INTEGER	Records processed
records_accepted	INTEGER
records_rejected	INTEGER
started_at	TIMESTAMPTZ
completed_at	TIMESTAMPTZ
error_log	JSONB	Structured error details

data_quality_flags QA

Column	Type	Notes
PKid	UUID	Primary key
record_type	VARCHAR(100)	Table name of flagged row
record_id	UUID	FK to the flagged record
flag_type	ENUM	missing/outlier/duplicate
field_name	VARCHAR(100)	Column with issue
original_value	TEXT
imputed_value	TEXT	After KNN/MICE
resolved	BOOLEAN	Default false

ML Models & Predictions

ml_models ML

Column	Type	Notes
PKid	UUID	Primary key
model_name	VARCHAR(100)	e.g. resistance_rf_v3
model_type	ENUM	classification/cluster/forecast
algorithm	VARCHAR(100)	RandomForest/DBSCAN/Prophet
version	VARCHAR(20)	Semantic version
accuracy	DECIMAL(5,4)	Test set score
auc_roc	DECIMAL(5,4)
artifact_path	VARCHAR(500)	S3/local .pkl path
trained_at	TIMESTAMPTZ
is_active	BOOLEAN	Currently serving

resistance_predictions ML

Column	Type	Notes
PKid	UUID	Primary key
model_id	UUID FK	→ ml_models
organism_snomed	VARCHAR(20)	SNOMED CT code
antibiotic_atc	VARCHAR(20)	ATC code
district_id	UUID FK	→ districts
predicted_resistance_rate	DECIMAL(5,4)	0-1 probability
confidence_interval_low	DECIMAL(5,4)
confidence_interval_high	DECIMAL(5,4)
prediction_period	DATE	Month of prediction
shap_values	JSONB	Feature importance

geo_clusters ML

Column	Type	Notes
PKid	UUID	Primary key
model_id	UUID FK	→ ml_models
cluster_label	INTEGER	-1 = noise
centroid_lat	DECIMAL(9,6)
centroid_lon	DECIMAL(9,6)
radius_km	DECIMAL(8,3)	Cluster extent
resistance_rate	DECIMAL(5,4)	Avg within cluster
organism_snomed	VARCHAR(20)
detected_at	TIMESTAMPTZ

consumption_forecasts ML

Column	Type	Notes
PKid	UUID	Primary key
model_id	UUID FK	→ ml_models
antibiotic_id	UUID FK	→ antibiotics
district_id	UUID FK	→ districts
forecast_month	DATE	First of month
forecasted_ddd_per_1000	DECIMAL(10,3)	WHO DDD metric
lower_bound	DECIMAL(10,3)	95% CI lower
upper_bound	DECIMAL(10,3)	95% CI upper

Alerts, FHIR & Audit

alerts ALERT

Column	Type	Notes
PKid	UUID	Primary key
alert_type	ENUM	outbreak/prescribing/threshold
severity	ENUM	low/medium/high/critical
district_id	UUID FK	→ districts
facility_id	UUID FK	→ facilities (nullable)
trigger_value	DECIMAL(10,4)	Value that triggered
threshold_value	DECIMAL(10,4)	Configured threshold
message	TEXT	Human-readable message
notified_users	UUID[]	Array of user IDs
sms_sent	BOOLEAN
push_sent	BOOLEAN
resolved	BOOLEAN
created_at	TIMESTAMPTZ

fhir_resources FHIR

Column	Type	Notes
PKid	UUID	Internal PK
fhir_id	VARCHAR(100)	FHIR resource ID
resource_type	VARCHAR(50)	DiagnosticReport/Obs…
version_id	INTEGER	FHIR version
resource_json	JSONB	Full FHIR resource
synced_to_dhis2	BOOLEAN
synced_to_glass	BOOLEAN
last_updated	TIMESTAMPTZ

audit_logs AUDIT

Column	Type	Notes
PKid	UUID	Primary key
user_id	UUID FK	→ users (nullable)
action	VARCHAR(100)	CREATE/UPDATE/DELETE/VIEW
resource_type	VARCHAR(100)	Table/endpoint name
resource_id	UUID	Affected record
ip_address	INET
changes	JSONB	Before/after diff
created_at	TIMESTAMPTZ	Indexed

prescriber_behaviour_scores ANALYTICS

Column	Type	Notes
PKid	UUID	Primary key
prescriber_id	UUID FK	→ users
period_month	DATE	First of month
total_prescriptions	INTEGER
guideline_compliance_rate	DECIMAL(5,4)	0-1
watch_group_rate	DECIMAL(5,4)	WHO WATCH antibiotics %
empiric_rate	DECIMAL(5,4)	% without culture
amr_risk_score	DECIMAL(5,2)	Composite 0-100

STACK Technology Stack Map & Responsibility Boundaries

Each technology layer has a clearly defined responsibility boundary. Data crosses boundaries via well-defined interfaces (REST APIs, message queues, shared MySQL).

PHP

PHP (Vanilla) — Web API & Interoperability

REST API server, JWT auth, form validation, Redis queue dispatch, FHIR R4 resource builder, DHIS2/WHO sync, web dashboard rendering, role-based access, USSD webhook handler, SMS dispatch via Africa's Talking.
FLT

Flutter — Mobile Application

Cross-platform app (Android/iOS) for lab technicians and clinicians. Offline-first using SQLite with background sync. Forms for lab result submission, prescription entry, alert inbox. Barcode scanning for specimen ID. Low-bandwidth mode.
PY

Python — ETL Pipeline & ML Engine

Celery workers + Pandas for ETL. scikit-learn + XGBoost for resistance classification (Random Forest). DBSCAN (GeoPandas) for spatial clustering. Prophet + ARIMA for forecasting. SHAP for explainability. FastAPI microservice exposes /predict endpoints.
DB

MySQL + PostGIS + Redis

MySQL is the primary data store with PostGIS for geospatial queries. Redis handles the Celery job queue and caches ML predictions (TTL 6h). TimescaleDB extension for time-series aggregation on resistance trends.
HL7

FHIR R4 / HL7 — Interoperability Layer

HAPI FHIR validator for resource compliance. LOINC for lab test coding, SNOMED CT for organisms, ICD-11 for diagnoses, ATC for antimicrobials. Bidirectional sync with DHIS2 and one-way export to WHO GLASS / Africa CDC.
SMS

USSD / SMS — Low-Resource Interface

Africa's Talking USSD API with a session-based menu tree (PHP handler). Structured SMS parsing for basic-phone data entry. Two-way: facilities submit data + receive alerts. Offline community education via SMS broadcast.

COMPONENT ARCHITECTURE