π¦ Archived β May 2026. EpiHack Arizona 2026 has concluded; this repository is preserved as a known-good baseline for future revival. The full archival journey lives at https://tyson-swetnam.github.io/epihack-2026/docs/; see
plan/10-archival-and-docs.mdfor the archival plan, the Ansible audit for the deployable-state snapshot, andCITATION.cfffor citation metadata. The live demo at http://epihack-test.cis240692.projects.jetstream-cloud.org/ remains up on a Jetstream2 VM as a reference deployment.Whatβs here, where it lives: UI/UX journey at
docs/journey/(seven pages, including the vibe-coding history); reference site generated by MkDocs Material atdocs/; reproducible end-to-end stack viaansible/; all 15 components (11 MCPs + agents + app + openapi + docs) green at archive freeze perdocs/reference/test-matrix.md.To revive:
ansible-playbook -i inventory.yml playbook.ymlagainst a fresh Ubuntu 24.04 box; seedocs/deploy/ansible.md.
EpiHack AZ 2026 β a working repository for the EpiHack Arizona event hosted by the Ending Pandemics Academy and the University of Arizona Global Health Institute.
This repository is an experiment in building a living knowledge graph for One Health surveillance. Three pieces of infrastructure do the heavy lifting:
| Layer | Role | What it lets us do |
|---|---|---|
| Claude Code | Agentic authoring | Drafts the schema, runs parallel sub-agents to research AZ counties / tribes / pathogens / outbreaks / datasets / standards, keeps the prose docs in sync with the SQL seeds, and opens pull requests against this repo. Every commit message in git log describes a Claude-led change. |
| GitHub | Source of truth + review surface | Every change β new content, schema, MCP code, visualizations β lands as a pull request; humans review and merge. Versioned snapshots of upstream specs (e.g. mcp/vectorsurv-mcp/openapi/) make API drift a git diff away. The site itself is served via GitHub Pages with Jekyll. |
| DuckLake (Postgres + DuckDB) | Queryable knowledge graph | A property-graph (kg.node, kg.edge, kg.property) seeded from version-controlled SQL; Postgres holds the DuckLake catalog (time-travel, branches, ACID), DuckDB is the query engine. Joins Parquet + Postgres + CSV in a single SQL statement; works on a laptop and at hack-day scale. |
What makes it living rather than a static snapshot:
schema/deep/*.sql seed, and opens a PR. Reviewers (humans
or other agents) merge. The next .read rebuilds the graph.mcp/vectorsurv-mcp/openapi/ directory holds versioned snapshots; a
git diff between two snapshots is the changelog the MCP client
reacts to.vectorsurv-mcp exposes the
national mosquito- and tick-surveillance API as MCP tools (sites,
collections, pools, vector-index calculations, human / equine
arbovirus case counts). An LLM client can query VectorSurv and
drop the results into the same DuckLake graph.kg_node_id that round-trips
to the SQL graph. Click a feature, get the canonical node back.Alongside the knowledge graph, the repo ships a working participatory-surveillance application. Four loosely-coupled components share one origin:
| Component | Stack | Role |
|---|---|---|
app/ |
Next.js 16 + React 19 + TypeScript + Tailwind | Mobile-first anonymous reporting app (tick / heat / cool-off), typed against api/openapi.yaml. Static-exported to /epihack-2026/app/. |
agents/ |
Python 3.11 + FastAPI + Pydantic v2 + anthropic + mcp |
The HTTP backend + eight-agent orchestrator (Intake β Geo β Validation β Triage β Enrichment β Notification + Cluster + KnowledgeUpdate). Serves api/openapi.yaml. |
mcp/ |
FastMCP + httpx + Pydantic v2 | Eleven MCP servers wrapping live (and, where no upstream API exists, mock) agency data sources. |
dashboard/, today/, map/, graph/ |
Vanilla HTML + ES modules | Agency analyst workspace, public citizen view, and the two knowledge-graph viewers. |
As of plan/09 the write path is
dual-sink: the mobile app persists to MongoDB, while the web
build and all analytics stay on DuckLake. Both channels POST to the
same /v1/reports endpoint and run the same privacy enforcement
(coarsen location, strip/reject EXIF GPS, never-diagnose triage guard,
SHA-256 audit digests) before the sink is chosen by an
X-Client-Channel header β so the contract lives in one place
(agents/.../api/routes/reports.py). Mobile documents are then replayed
into DuckLake by a watermarked, idempotent mongo_to_ducklake sync, so
the agents, MCP servers, and cluster detection all see one unified
dataset.
web build ββ βββΊ DuckLake (kg_writer) βββββββββββββββ
ββ POST /v1/reports Β· FastAPI β€ βββΊ knowledge graph
mobile app ββ + X-Client-Channel βββΊ MongoDB (mongo_writer) β sync βββββββ (agents Β· MCP Β·
cluster scan)
privacy enforcement (validate Β· coarsen Β· EXIF check Β· triage-guard Β· SHA-256 digests)
runs inside FastAPI BEFORE the sink is chosen β one contract for both channels
Everything in this repository is also a page on the published site at https://tyson-swetnam.github.io/epihack-2026/.
01β09 plus cluster-calibration, evaluation, and federation notes) for a mobile-first participatory-surveillance app spanning Vector-Borne Disease and Heat. Covers Figure 2 parameter mapping by vertical, the MCP integration topology, the eight-agent architecture, four worked end-to-end data flows, the auth model, the mobile UX revamp, the dual MongoDB/DuckLake datastore, and a phased roadmap tied to the Figure 3 timeliness milestones.Eleven servers ship today; see mcp/README.md for the
full index (tool tables, auth posture, test counts).
vectorsurv-mcp β VectorSurv national mosquito + tick surveillance API (spec v1.0.44). 13 tools.knowledge-graph-mcp β Read-only DuckDB query MCP over the kg (572 nodes / 791 edges / 1027 properties). 12 tools + SELECT-only SQL escape-hatch.great-az-tick-check-mcp β Mock submission tracking for the UA Cooperative Extension tick program. 5 tools.nws-heatrisk-mcp β NWS HeatRisk + alerts + heat-index. 7 tools.mag-hrn-mcp β MAG Heat Relief Network cooling-center search. 5 tools.adhs-mcp β ADHS public surveillance summaries (heat mortality, arbovirus, reportable conditions). 6 tools.211-az-mcp β 211 Arizona referrals + transport dispatch. 6 tools.whispers-mcp β USGS WHISPers wildlife mortality events. 6 tools.inaturalist-mcp β iNaturalist citizen-science observations. 6 tools.sms-entry-mcp β SMS-only intake adapter; Twilio HMAC-SHA1 signature check, normalisation, intent parsing. 6 tools.wearable-mcp β HealthKit / Health Connect readings (skin temp, HRV, sweat rate, heart rate); on-device-only posture, mock-by-default. 4 tools.app/ β Mobile-first reporting app: Next.js 16 + React 19 + TypeScript + Tailwind, typed against api/openapi.yaml. Anonymous Human / Animal / Environmental flows (tick mail-in, heat check-in, anonymous heat self-report, βwhere can I cool off?β), client-side EXIF strip + ZIP / 1Β km coarsening, a localStorage offline retry queue, and an X-Client-Channel header that routes the write to MongoDB (mobile) or DuckLake (web). An optional account adds profile enrichment (household size, pets, outdoor work β all opt-in, off by default) so advisories stay relevant, plus a personal dashboard (/dashboard): local weather, active alerts near you, a link into the live map + county resources, a community leaderboard, engagement rewards, and a weekly-email opt-in (leaderboard, rewards, and the weather strip are demo stubs pending a live feed). The original vanilla-HTML flows live on as a read-only archive at app/legacy/.
agents/ β The FastAPI backend + 8-agent pipeline (Intake β Geo-Enrichment β Validation β Triage β Enrichment β Notification β Cluster Detection β Knowledge Update). Two write sinks (kg_writer β DuckLake, mongo_writer β MongoDB) behind one privacy-enforcing endpoint, plus the mongo_to_ducklake sync. Offline test suite; Scenarios A and C run end-to-end against shipped MCP-tool names.plan/EXECUTION-STATUS.md, plan/EXECUTION-STATUS-PHASE-1-2.md, and plan/EXECUTION-STATUS-PHASE-4.md for the verification matrix.today/ β AZ One Health Today: a citizen-facing aggregated view (todayβs HeatRisk, WNV pool positivity, recent wildlife signals, and a five-number statewide snapshot). Auto-detects county, no login, no PII β renders only pre-aggregated kg fields.dashboard/ β Read-only analyst workspace for ADHS Vector-Borne & Zoonotic Diseases, Maricopa County DPH Heat Surveillance, AZ Game & Fish Wildlife Health Program, and Coconino HHS. Four-audience landing pages, status cards, Cluster Detection Agent feed, lazy-loaded MapLibre embed, sparkline case-count tables, and a SQL preview that round-trips to knowledge-graph-mcp. Implements Scenario D from plan/04-data-flows.md.schema/ β core graph (frameworks) plus worksheet template, focus areas, designs, World CafΓ© cards, and the two focus-group seeds.schema/deep/ β sub-agent deep-research seeds: all 15 AZ counties, all 22 federally recognized AZ tribes, pathogens (with vectors / reservoirs / ICD-10), historical AZ outbreaks (with Figure 3 milestone dates), datasets & APIs (NEON DPs, WHISPers, NWS, GBIF, iNat), interop standards (FHIR, OMOP, ICD-10, Darwin Core), MCP servers.README.md Project overview (this file)
index.html Top-level site landing page (linked from GitHub Pages)
CLAUDE.md Repo guide for Claude Code / contributors
api/
βββ openapi.yaml Source of truth for the app β backend HTTP contract
app/ Next.js 16 + React 19 + TypeScript + Tailwind reporting app
βββ src/app/ -- routes: home, report/[type], account, profile, sign-in, auth
βββ src/lib/ -- api-client, coarse-geo, exif-stripper, offline-queue,
β api-types.ts (generated from openapi.yaml β do not hand-edit)
βββ src/components/ -- ReportFlow, AppShell, OfflineFlusher, ProfileForm
βββ legacy/ -- original vanilla-HTML flows (read-only archive)
agents/ FastAPI backend + 8-agent orchestrator (Python 3.11)
βββ src/onehealth_agents/
βββ api/ -- FastAPI app + routes (reports, profile, auth, context)
βββ orchestrator.py -- runs the 8 agents below
βββ intake.py geo.py validation.py triage.py enrichment.py
β notification.py cluster.py update.py -- the 8 agents
βββ kg_writer.py -- DuckLake sink (web channel)
βββ mongo_writer.py -- MongoDB sink (mobile channel)
βββ sync/ -- mongo_to_ducklake watermarked, idempotent ETL
βββ mcp_client.py audit.py contracts.py ...
mcp/ Eleven MCP servers, one uv workspace each -- see mcp/README.md
βββ vectorsurv-mcp/ knowledge-graph-mcp/ great-az-tick-check-mcp/
βββ nws-heatrisk-mcp/ mag-hrn-mcp/ adhs-mcp/ 211-az-mcp/
βββ whispers-mcp/ inaturalist-mcp/ sms-entry-mcp/ wearable-mcp/
map/ MapLibre GL map of AZ (counties, tribes, NEON sites, agency
HQs, federal lands, outbreaks); each pin carries a kg_node_id.
graph/ Cytoscape.js pathogen knowledge graph (16 pathogens).
dashboard/ Phase-3 agency-side read-only analyst workspace
(ADHS / MCDPH / AZGFD / Coconino).
today/ Phase-3 public citizen-facing aggregated view (no login, no PII).
figures/ Structured transcriptions of the five EpiHack reference figures.
wildlife/ heat/ Focus-group materials (4 questions + 30+ resource catalogs each).
worksheets/ Completed design worksheets from EpiHack breakouts.
notes/world-cafe/ World CafΓ© Q4 breakout cards (heat, unhoused, info-flow).
evaluation/ Cluster-detector evaluation harness + 2024 baseline.
schema/ Knowledge-graph SQL (property graph: kg.node / edge / property)
βββ knowledge_graph.sql -- core graph (frameworks)
βββ system_designs.sql world_cafe.sql wildlife_vectors.sql heat.sql
βββ deep/ -- parallel sub-agent deep-research seeds
βββ standards.sql -- FHIR/OMOP/ICD-10/Darwin Core (load FIRST)
βββ pathogens.sql -- vectors / reservoirs / ICD-10 (load SECOND)
βββ counties.sql tribes.sql outbreaks.sql datasets_apis.sql
βββ application.sql followups.sql audit.sql
βββ cluster_followups.sql outbreaks_near_me.sql mcp_servers.sql
ansible/ One-command VM deploy (Postgres + DuckLake, self-hosted
MongoDB + sync timer, MCP servers, FastAPI, app, nginx).
deploy/ VM sizing, DNS, and the operations runbook.
plan/ 01β09 plan docs + cluster-calibration / evaluation / status.
The Markdown files use YAML frontmatter and explicit subject | predicate |
object tables so they can be parsed directly into the knowledge-graph
tables defined in schema/knowledge_graph.sql.
The figures encode three reusable conceptual frameworks that we want to operationalize as a queryable knowledge graph:
These are all relational by nature (parameters belong to categories, milestones precede milestones, steps precede steps, sectors emit signals) which is why a property-graph encoding is a natural fit.
EpiHack Arizona 2026 broke participants into focus groups, each chartered to apply the frameworks above to a concrete domain. This repository covers two:
| Layer | Role |
|---|---|
| Postgres | DuckLake catalog: snapshot metadata, schema evolution, ACID transactions over the lakehouse. |
| DuckLake | Open lakehouse format on top of Parquet, catalog in Postgres. Gives us time travel, branches, and multi-writer concurrency without standing up Iceberg/Hudi infrastructure. |
| DuckDB | Embedded query engine. Reads/writes DuckLake natively; can join Parquet, Postgres, and CSV in a single SQL statement; works on a laptop and at hack-day scale. |
DuckLake is the web + analytics store; the mobile app writes to MongoDB, which is synced back into DuckLake so the agents, MCP servers, and cluster detection see one dataset (see System architecture). The bootstrap below builds the DuckLake side.
# 1. Postgres for the DuckLake catalog
createdb epihack
# 2. DuckDB session
duckdb
-- Inside DuckDB:
INSTALL ducklake; INSTALL postgres;
LOAD ducklake; LOAD postgres;
ATTACH 'ducklake:postgres:dbname=epihack host=localhost user=epihack'
AS epihack
(DATA_PATH 's3://epihack/ducklake/'); -- or a local path for laptop dev
USE epihack;
.read schema/knowledge_graph.sql
.read schema/system_designs.sql
.read schema/world_cafe.sql
.read schema/wildlife_vectors.sql -- focus group 1
.read schema/heat.sql -- focus group 2
.read schema/deep/standards.sql -- must load first (SNOMED / ICD-10 FKs)
.read schema/deep/pathogens.sql -- must load second (pathogen FKs)
.read schema/deep/counties.sql
.read schema/deep/tribes.sql
.read schema/deep/outbreaks.sql
.read schema/deep/datasets_apis.sql
.read schema/deep/application.sql
.read schema/deep/followups.sql
After loading, the graph is queryable in plain SQL. Examples:
-- All parameters in the Exposure class
SELECT n.label
FROM kg.edge e
JOIN kg.node n ON n.node_id = e.subject_id
WHERE e.predicate = 'belongsTo'
AND e.object_id = 'category.exposure';
-- Milestone ordering for timeliness metrics
SELECT n.label, p.value_num AS ordinal
FROM kg.node n
JOIN kg.property p ON p.node_id = n.node_id AND p.key = 'ordinal'
WHERE n.node_type = 'milestone'
ORDER BY p.value_num;
-- Wide summary of completed system designs
SELECT * FROM kg.v_design_summary;
-- Which focus areas does each design target?
SELECT d.label AS design, f.label AS focus_area
FROM kg.edge e
JOIN kg.node d ON d.node_id = e.subject_id
JOIN kg.node f ON f.node_id = e.object_id
WHERE e.predicate = 'targetsFocusArea'
ORDER BY design, focus_area;
-- All World CafΓ© Q4 engagement tactics, grouped by card
SELECT * FROM kg.v_engagement_tactics ORDER BY card, tactic;
-- Lifecycle chain via recursive CTE
WITH RECURSIVE chain AS (
SELECT subject_id, object_id, 1 AS depth
FROM kg.edge
WHERE predicate = 'precedes' AND subject_id = 'step.01_assess_needs'
UNION ALL
SELECT e.subject_id, e.object_id, c.depth + 1
FROM kg.edge e
JOIN chain c ON e.subject_id = c.object_id
WHERE e.predicate = 'precedes'
)
SELECT * FROM chain;
report fact
table whose columns are the parameters from Figure 2.metric view between
milestone-date columns on the outbreak table.Spinning up your own instance? deploy/README.md
walks through VM sizing, DNS, and the operations runbook;
ansible/ is a one-command Ansible playbook that takes
a fresh Ubuntu 24.04 VM from apt update to a running deployment of
Claude Code, every MCP server in mcp/, the FastAPI backend,
the Next.js reporting app, Postgres for the DuckLake catalog,
self-hosted MongoDB for the mobile write-path (bound to 127.0.0.1,
auth enabled) with its mongo_to_ducklake sync timer, and nginx with
optional Letβs Encrypt TLS.
cd ansible
cp inventory.example.yml inventory.yml # edit ansible_host
cp group_vars/all.vault.example.yml group_vars/all.vault.yml
ansible-vault encrypt group_vars/all.vault.yml # fill in secrets first
ansible-galaxy install -r requirements.yml
ansible-playbook -i inventory.yml playbook.yml --ask-vault-pass
The repository is now stewarded by a standing review board (ADHS,
AZGFD, ITCA-TEC, Maricopa Vector Control) per the cross-cutting
governance track in plan/05-roadmap.md.
Contributions are welcome through pull requests; the six documents
below describe the conventions, the review structure, the security
posture, and the version history.
CONTRIBUTING.md β local environment
setup, PR workflow, MCP-server and schema-seed templates, coding
style, and the privacy + data-sovereignty checklist every PR
touching observation data must pass.GOVERNANCE.md β standing review board
membership, proposal-then-merge cadence, tribal-partner veto,
opt-in posture for tribal data, conflict-of-interest disclosure,
and sunset clauses for MCP servers that proxy tribal data.SECURITY.md β private-disclosure channel,
the five-class threat model
(re-identification / credential leakage / token reuse /
prompt-injection / cluster-detection false positives), mitigations
in place, and an itemised list of known security gaps.CHANGELOG.md β per-phase rollup of what
landed and when (PRs #1 through #8), plus the βNextβ backlog from
plan/EXECUTION-STATUS-PHASE-1-2.md
and plan/CLUSTER-CALIBRATION.md.mcp/README.md β index of all 11 MCP
servers with tool counts, auth posture, and test counts, plus the
recipe for adding a new MCP server.NOTICE β third-party attribution for runtime
dependencies (MapLibre, Cytoscape, FastMCP / mcp SDK, pydantic,
httpx, DuckDB / DuckLake), data sources surfaced via MCP, and
upstream-spec snapshots.See LICENSE.