# willlzl/topify-hackathon-healthcare-agent architecture

> Architecture diagram of the GitHub repository willlzl/topify-hackathon-healthcare-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/willlzl/topify-hackathon-healthcare-agent
- Repository: https://github.com/willlzl/topify-hackathon-healthcare-agent

## Overview

Hivemind automates healthcare claim follow-up: it ingests claim spreadsheets, processes claims through a worker pipeline, checks payer portals or calls payers, records outcomes, and routes human escalations through the organization graph and Teams. The graph preserves the documented workflow and major integrations, plus the persistence and control-plane layers. Some subsystem links rely on README descriptions or SOURCE INDEX references; unsampled implementation details and uncertain call paths are not expanded.

Main entry points: [`worker/agent_worker.py`](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/worker/agent_worker.py) (Agent worker), [`worker/step_handlers.py`](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/worker/step_handlers.py) (Claim step handlers), [`ingestion/sheets_reader.py`](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/ingestion/sheets_reader.py) (Claim ingestion), [`agents/playwright_forta.py`](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/agents/playwright_forta.py) (Portal agents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Claim workflow"]
  node_sheets["Claim ingestion<br/>[sheets_reader.py]"]
  node_worker["Agent worker<br/>[agent_worker.py]"]
  node_steps["Claim step handlers<br/>[step_handlers.py]"]
  node_brain["LLM reasoning<br/>[claude_brain.py]"]
  node_tools["Agent tools<br/>[tools.py]"]
end

subgraph group_payer["Payer operations"]
  node_browser["Browser automation<br/>[browser_agent.py]"]
  node_forta["Portal agents"]
  node_portalchecks["Payer checkers"]
  node_callservice["Calling service<br/>[calling_service.py]"]
  node_caller["Voice caller"]
  node_transcript["Call parsing"]
  node_payerportals(("Payer portals"))
end

subgraph group_handoff["Human handoffs"]
  node_orggraph["Organization graph<br/>[org_graph.py]"]
  node_teams["Teams integration<br/>[teams.py]"]
end

subgraph group_platform["Control and state"]
  node_api["FastAPI control plane<br/>[main.py]"]
  node_database[("Claim state<br/>[models.py]")]
  node_dbengine["Database sessions<br/>[engine.py]"]
end

subgraph group_shared["Shared runtime"]
  node_settings["Runtime settings<br/>[settings.py]"]
  node_logging["Structured logging<br/>[logging.py]"]
end

node_clinic(("Clinic operator"))
node_teammate(("Clinic teammate"))

node_clinic -->|"provides claims"| node_sheets
node_sheets -->|"supplies claim data"| node_steps
node_clinic -->|"starts claim run"| node_worker
node_api -->|"dispatches test run"| node_worker
node_worker -->|"dispatches steps"| node_steps
node_worker -->|"uses reasoning"| node_brain
node_worker -->|"provides tools"| node_tools
node_steps -->|"invokes tools"| node_tools
node_steps -->|"checks payer portals"| node_portalchecks
node_tools -->|"invokes portal agent"| node_forta
node_forta -->|"uses browser engine"| node_browser
node_forta -->|"automates portal"| node_payerportals
node_steps -->|"requests payer call"| node_callservice
node_callservice -->|"places call"| node_caller
node_callservice -->|"parses transcript"| node_transcript
node_caller -->|"calls payer"| node_payerportals
node_worker -->|"routes handoff"| node_orggraph
node_worker -->|"sends escalation"| node_teams
node_orggraph -->|"selects teammate"| node_teams
node_teams -->|"messages teammate"| node_teammate
node_api -->|"serves voice lookups"| node_database
node_database -->|"uses sessions"| node_dbengine
node_steps -->|"reads claim state"| node_database
node_sheets -->|"reads sheet config"| node_settings
node_worker -->|"reads runtime config"| node_settings
node_worker -->|"logs operations"| node_logging

click node_sheets "https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/ingestion/sheets_reader.py"
click node_worker "https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/worker/agent_worker.py"
click node_steps "https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/worker/step_handlers.py"
click node_brain "https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/worker/claude_brain.py"
click node_tools "https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/worker/tools.py"
click node_browser "https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/agents/browser_agent.py"
click node_forta "https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/agents/playwright_forta.py"
click node_portalchecks "https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/agents/availity_checker.py"
click node_callservice "https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/services/calling_service.py"
click node_caller "https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/calling/elevenlabs_caller.py"
click node_transcript "https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/calling/transcript_parser.py"
click node_orggraph "https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/integrations/org_graph.py"
click node_teams "https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/integrations/teams.py"
click node_api "https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/api/main.py"
click node_database "https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/hivemind/db/models.py"
click node_dbengine "https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/hivemind/db/engine.py"
click node_settings "https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/config/settings.py"
click node_logging "https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/utils/logging.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sheets,node_worker,node_steps,node_brain,node_tools toneBlue
class node_browser,node_forta,node_portalchecks,node_callservice,node_caller,node_transcript,node_payerportals toneAmber
class node_orggraph,node_teams toneMint
class node_api,node_database,node_dbengine toneRose
class node_settings,node_logging,node_clinic,node_teammate toneIndigo
```

## Components

### Claim workflow

- [Claim ingestion](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/ingestion/sheets_reader.py): `ingestion/sheets_reader.py`
- [Agent worker](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/worker/agent_worker.py): `worker/agent_worker.py`
- [Claim step handlers](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/worker/step_handlers.py): `worker/step_handlers.py`
- [LLM reasoning](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/worker/claude_brain.py): `worker/claude_brain.py`
- [Agent tools](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/worker/tools.py): `worker/tools.py`

### Payer operations

- [Browser automation](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/agents/browser_agent.py): `agents/browser_agent.py`
- [Portal agents](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/agents/playwright_forta.py): `agents/playwright_forta.py`
- [Payer checkers](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/agents/availity_checker.py): `agents/availity_checker.py`
- [Calling service](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/services/calling_service.py): `services/calling_service.py`
- [Voice caller](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/calling/elevenlabs_caller.py): `calling/elevenlabs_caller.py`
- [Call parsing](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/calling/transcript_parser.py): `calling/transcript_parser.py`
- **Payer portals**

### Human handoffs

- [Organization graph](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/integrations/org_graph.py): `integrations/org_graph.py`
- [Teams integration](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/integrations/teams.py): `integrations/teams.py`

### Control and state

- [FastAPI control plane](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/api/main.py): `api/main.py`
- [Claim state](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/hivemind/db/models.py): `hivemind/db/models.py`
- [Database sessions](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/hivemind/db/engine.py): `hivemind/db/engine.py`

### Shared runtime

- [Runtime settings](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/config/settings.py): `config/settings.py`
- [Structured logging](https://github.com/willlzl/topify-hackathon-healthcare-agent/blob/main/utils/logging.py): `utils/logging.py`

### Other components

- **Clinic operator**
- **Clinic teammate**

## Connections

- Clinic operator → Claim ingestion: provides claims
- Claim ingestion → Claim step handlers: supplies claim data (evidence: `worker/step_handlers.py`)
- Clinic operator → Agent worker: starts claim run
- FastAPI control plane → Agent worker: dispatches test run (evidence: `api/main.py`)
- Agent worker → Claim step handlers: dispatches steps (evidence: `worker/agent_worker.py`)
- Agent worker → LLM reasoning: uses reasoning (evidence: `worker/agent_worker.py`)
- Agent worker → Agent tools: provides tools (evidence: `worker/agent_worker.py`)
- Claim step handlers → Agent tools: invokes tools (evidence: `worker/step_handlers.py`)
- Claim step handlers → Payer checkers: checks payer portals (evidence: `worker/step_handlers.py`)
- Agent tools → Portal agents: invokes portal agent (evidence: `worker/tools.py`)
- Portal agents → Browser automation: uses browser engine (evidence: `agents/playwright_forta.py`)
- Portal agents → Payer portals: automates portal
- Claim step handlers → Calling service: requests payer call (evidence: `worker/step_handlers.py`)
- Calling service → Voice caller: places call (evidence: `services/calling_service.py`)
- Calling service → Call parsing: parses transcript (evidence: `services/calling_service.py`)
- Voice caller → Payer portals: calls payer
- Agent worker → Organization graph: routes handoff (evidence: `worker/agent_worker.py`)
- Agent worker → Teams integration: sends escalation (evidence: `worker/agent_worker.py`)
- Organization graph → Teams integration: selects teammate
- Teams integration → Clinic teammate: messages teammate
- FastAPI control plane → Claim state: serves voice lookups (evidence: `api/main.py`)
- Claim state → Database sessions: uses sessions (evidence: `hivemind/db/models.py`)
- Claim step handlers → Claim state: reads claim state (evidence: `worker/step_handlers.py`)
- Claim ingestion → Runtime settings: reads sheet config (evidence: `ingestion/sheets_reader.py`)
- Agent worker → Runtime settings: reads runtime config (evidence: `worker/agent_worker.py`)
- Agent worker → Structured logging: logs operations (evidence: `worker/agent_worker.py`)
