ridoykhan/outbreak-signal-service repository overview

⁠Outbreak Signal Service

Pulls weekly DHIS2 surveillance data, flags statistical aberrations using CDC's EARS (C1-C3) and CUSUM methods, and publishes the results as a reviewable alert over REST, signed webhooks, and FHIR.

An alert is a signal for a person to review, never a confirmed outbreak - that distinction is built into the alert lifecycle itself.

⁠Quick start

docker run -d \
  -e DB_URL=jdbc:postgresql://<host>:5432/outbreaksignal \
  -e DB_USERNAME=outbreak \
  -e DB_PASSWORD=<password> \
  -e OUTBREAK_SECURITY_JWK_SET_URI=<your identity provider's JWK endpoint> \
  -p 8080:8080 \
  ridoykhan/outbreak-signal-service:v0.1.0

Needs a PostgreSQL database and an OAuth2/JWT identity provider (e.g. Keycloak) for the secured Alerts API. For the full docker compose setup (including an optional local Keycloak for trying it out), see the GitHub repo.

⁠Tags

• latest, v0.1.0 - current stable release. All 7 phases of the original build plan are shipped.

⁠What it does

• Weekly, idempotent sync from a DHIS2 instance
• Five detection strategies (moving-average z-score, EARS C1/C2/C3, CUSUM), each a pluggable Spring bean
• Backtested against 200 synthetic series with a known, injected outbreak before shipping - the best performer, EARS C3, caught 88.5% of them. Full honest results, including the less flattering numbers, in RESULTS.md⁠
• JWT-secured Alerts API with a real lifecycle: open, acknowledged, resolved, dismissed (illegal transitions return 409)
• Signed webhook and email notifications via a transactional outbox
• Read-only FHIR DetectedIssue output

⁠Links

• Source and full documentation: github.com/khalilurrrahmanridoykhan/outbreak-signal-service⁠
• Live instance: outbreak.krrkhan.com⁠
• License: Apache-2.0