epihack-2026

πŸ“¦ 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.md for the archival plan, the Ansible audit for the deployable-state snapshot, and CITATION.cff for 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 at docs/; reproducible end-to-end stack via ansible/; all 15 components (11 MCPs + agents + app + openapi + docs) green at archive freeze per docs/reference/test-matrix.md.

To revive: ansible-playbook -i inventory.yml playbook.yml against a fresh Ubuntu 24.04 box; see docs/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.

A living database for ending pandemics

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:

System architecture

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.

Two stores, one privacy contract

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

Site roadmap

Everything in this repository is also a page on the published site at https://tyson-swetnam.github.io/epihack-2026/.

Reference frameworks

Focus groups

Interactive viewers

Application plan

MCP servers (live data ingestion for LLMs)

Eleven servers ship today; see mcp/README.md for the full index (tool tables, auth posture, test counts).

Reporting app + backend

Public dashboard (Phase 3)

Agency dashboard (Phase 3)

Knowledge-graph SQL

Breakout artifacts

Contents

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.

Knowledge framework: DuckLake + DuckDB + Postgres

The figures encode three reusable conceptual frameworks that we want to operationalize as a queryable knowledge graph:

  1. Figure 1 β€” the purpose of a One Health participatory system.
  2. Figure 2 β€” the minimum key data parameters (a typed data dictionary across General / Human / Severity / Exposure / Auxiliary / Environmental / Livestock / Wildlife).
  3. Figure 3 β€” the outbreak timeliness milestones used to compute inter-milestone intervals.
  4. Figure 4 β€” the 12-step lifecycle for designing and launching participatory surveillance.

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.

Focus groups

EpiHack Arizona 2026 broke participants into focus groups, each chartered to apply the frameworks above to a concrete domain. This repository covers two:

  1. Wildlife & Vector-Borne Diseases β€” four guiding questions on how Arizona tracks wildlife and vector density; how zoonotic infections are monitored in wildlife and vectors; what technologies could improve surveillance; and how participatory surveillance can better track wildlife disease. Anchored on NEON, ADHS, AZGFD, the Great Arizona Tick Check, USGS WHISPers, USDA APHIS, USFWS, the 22 AZ tribal nations, and 15 county vector programs.
  2. Heat β€” four guiding questions on how the public is informed about cooling-center locations; whether centers share resources in real time; what severe-heat education is provided; and who is most vulnerable to heat in Arizona. Anchored on the ADHS Heat Preparedness Network, the MAG Heat Relief Network at hrn.azmag.gov, the Phoenix Office of Heat Response and Mitigation, the UA Heat Resilience Initiative (which umbrellas SW-IFL, NIHHIS, CLIMAS, BRACE, and SCORCH), NWS HeatRisk, and 211 Arizona.

Why DuckLake + DuckDB + Postgres

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.

Bootstrap

# 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;

Next steps for the EpiHack build

Self-hosting on a VM

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

Contributing + governance

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.

License

See LICENSE.