# abhinavprkash/fetch-health architecture

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

- Interactive diagram: https://gitdiagram.com/abhinavprkash/fetch-health
- Repository: https://github.com/abhinavprkash/fetch-health

## Overview

Fetch Health is an educational donor/recipient matching simulator: public Fetch agents route requests through a selective-activation harness to a FastAPI gateway, which manages uploads and runs, processes case information, retrieves candidates, and returns transparent matching results. Separate data tools prepare profile and artifact datasets for use by the gateway. The README documents the top-level boundaries; source-index references and excerpts support selected internal links. Unsampled route and worker details are shown only where documented, not inferred.

Main entry points: [`backend/app/main.py`](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/main.py) (FastAPI gateway), [`backend/app/repositories/candidate_store.py`](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/repositories/candidate_store.py) (Candidate store), [`swarm/harness.py`](https://github.com/abhinavprkash/fetch-health/blob/main/swarm/harness.py) (Agent harness), [`backend/app/services/run_service.py`](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/services/run_service.py) (Run orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agents["Agent access"]
  node_public_agents["Capability agents"]
  node_harness["Agent harness<br/>[harness.py]"]
  node_activation["Agent activation"]
end

subgraph group_gateway["Gateway workflow"]
  node_gateway["FastAPI gateway<br/>[main.py]"]
  node_agent_routes["Agent requests<br/>[agents.py]"]
  node_upload_routes["Case uploads<br/>[uploads.py]"]
  node_run_routes["Run lifecycle<br/>[runs.py]"]
  node_profile_routes["Profiles<br/>[profiles.py]"]
  node_edu_routes["Education API<br/>[edu.py]"]
  node_run_service["Run orchestration<br/>[run_service.py]"]
  node_document_processor["Document analysis<br/>[document.py]"]
  node_media_processors["Image video analysis"]
  node_matching["Donor matching<br/>[donor_matching.py]"]
  node_retrieval["Candidate retrieval<br/>[retrieval.py]"]
  node_candidate_store[("Candidate store<br/>[candidate_store.py]")]
  node_profile_store[("Profile store<br/>[profile_store.py]")]
  node_run_store[("Run store<br/>[run_store.py]")]
end

subgraph group_data["Data preparation"]
  node_pipeline["Dataset pipeline<br/>[main.py]"]
  node_factory["Transplant data factory<br/>[main.py]"]
  node_profile_builder["Profile builder<br/>[profile_builder.py]"]
end

subgraph group_bureau["Local Bureau"]
  node_local_bureau["Local Bureau<br/>[bureau.py]"]
  node_document_worker["Document worker<br/>[document_parser.py]"]
end

subgraph group_integrations["Shared integrations"]
  node_llm["LLM integration<br/>[llm.py]"]
  node_audio["Audio transcription<br/>[audio.py]"]
  node_imagegen["Edu diagrams<br/>[imagegen.py]"]
end

node_requester(("ASI:One user"))
node_redis[("Redis Stack")]
node_claude["Claude / ASI:One"]
node_deepgram["Deepgram"]
node_midjourney["Midjourney proxy"]

node_requester -->|"submits tasks"| node_harness
node_harness -->|"routes capabilities"| node_public_agents
node_harness -->|"activates agents"| node_activation
node_harness -->|"forwards requests"| node_gateway
node_public_agents -->|"uses gateway endpoints"| node_gateway
node_gateway -->|"registers routes"| node_agent_routes
node_gateway -->|"registers routes"| node_upload_routes
node_gateway -->|"registers routes"| node_run_routes
node_gateway -->|"registers routes"| node_profile_routes
node_gateway -->|"registers routes"| node_edu_routes
node_run_routes -.->|"manages runs"| node_run_service
node_run_service -->|"updates run state"| node_run_store
node_run_service -->|"requests matches"| node_matching
node_run_service -.->|"coordinates processing"| node_document_processor
node_upload_routes -.->|"dispatches document analysis"| node_document_processor
node_upload_routes -.->|"dispatches media analysis"| node_media_processors
node_matching -.->|"retrieves candidates"| node_retrieval
node_retrieval -->|"searches candidates"| node_candidate_store
node_profile_routes -->|"accesses candidates"| node_candidate_store
node_profile_routes -.->|"uses profile storage"| node_profile_store
node_gateway -->|"initializes store"| node_candidate_store
node_gateway -->|"initializes store"| node_profile_store
node_gateway -->|"initializes store"| node_run_store
node_candidate_store -.->|"stores and searches"| node_redis
node_pipeline -.->|"shares profile data conventions"| node_factory
node_factory -->|"builds profiles"| node_profile_builder
node_factory -.->|"exports candidate data"| node_candidate_store
node_local_bureau -->|"registers worker"| node_document_worker
node_document_worker -->|"gateway performs extraction"| node_gateway
node_document_processor -.->|"uses extraction model"| node_llm
node_llm -->|"calls provider"| node_claude
node_llm -.->|"calls ASI:One"| node_requester
node_audio -->|"transcribes media"| node_deepgram
node_media_processors -.->|"uses transcription"| node_audio
node_edu_routes -.->|"requests diagrams"| node_imagegen
node_imagegen -->|"generates diagrams"| node_midjourney

click node_public_agents "https://github.com/abhinavprkash/fetch-health/tree/main/swarm/generated"
click node_harness "https://github.com/abhinavprkash/fetch-health/blob/main/swarm/harness.py"
click node_activation "https://github.com/abhinavprkash/fetch-health/blob/main/swarm/activation_manager.py"
click node_gateway "https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/main.py"
click node_agent_routes "https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/routes/agents.py"
click node_upload_routes "https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/routes/uploads.py"
click node_run_routes "https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/routes/runs.py"
click node_profile_routes "https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/routes/profiles.py"
click node_edu_routes "https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/routes/edu.py"
click node_run_service "https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/services/run_service.py"
click node_document_processor "https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/processors/document.py"
click node_media_processors "https://github.com/abhinavprkash/fetch-health/tree/main/backend/app/processors"
click node_matching "https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/services/donor_matching.py"
click node_retrieval "https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/services/retrieval.py"
click node_candidate_store "https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/repositories/candidate_store.py"
click node_profile_store "https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/repositories/profile_store.py"
click node_run_store "https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/repositories/run_store.py"
click node_pipeline "https://github.com/abhinavprkash/fetch-health/blob/main/data/data_pipeline/src/main.py"
click node_factory "https://github.com/abhinavprkash/fetch-health/blob/main/data/transplant_data_factory/src/main.py"
click node_profile_builder "https://github.com/abhinavprkash/fetch-health/blob/main/data/transplant_data_factory/src/builders/profile_builder.py"
click node_local_bureau "https://github.com/abhinavprkash/fetch-health/blob/main/local_agents/bureau.py"
click node_document_worker "https://github.com/abhinavprkash/fetch-health/blob/main/local_agents/agents/document_parser.py"
click node_llm "https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/integrations/llm.py"
click node_audio "https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/integrations/audio.py"
click node_imagegen "https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/integrations/imagegen.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_public_agents,node_harness,node_activation,node_requester toneBlue
class node_gateway,node_agent_routes,node_upload_routes,node_run_routes,node_profile_routes,node_edu_routes,node_run_service,node_document_processor,node_media_processors,node_matching,node_retrieval,node_candidate_store,node_profile_store,node_run_store,node_redis toneAmber
class node_pipeline,node_factory,node_profile_builder toneMint
class node_local_bureau,node_document_worker toneRose
class node_llm,node_audio,node_imagegen,node_claude,node_deepgram,node_midjourney toneIndigo
```

## Components

### Agent access

- [Capability agents](https://github.com/abhinavprkash/fetch-health/tree/main/swarm/generated): `swarm/generated`
- [Agent harness](https://github.com/abhinavprkash/fetch-health/blob/main/swarm/harness.py): `swarm/harness.py`
- [Agent activation](https://github.com/abhinavprkash/fetch-health/blob/main/swarm/activation_manager.py): `swarm/activation_manager.py`

### Gateway workflow

- [FastAPI gateway](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/main.py): `backend/app/main.py`
- [Agent requests](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/routes/agents.py): `backend/app/routes/agents.py`
- [Case uploads](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/routes/uploads.py): `backend/app/routes/uploads.py`
- [Run lifecycle](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/routes/runs.py): `backend/app/routes/runs.py`
- [Profiles](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/routes/profiles.py): `backend/app/routes/profiles.py`
- [Education API](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/routes/edu.py): `backend/app/routes/edu.py`
- [Run orchestration](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/services/run_service.py): `backend/app/services/run_service.py`
- [Document analysis](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/processors/document.py): `backend/app/processors/document.py`
- [Image video analysis](https://github.com/abhinavprkash/fetch-health/tree/main/backend/app/processors): `backend/app/processors`
- [Donor matching](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/services/donor_matching.py): `backend/app/services/donor_matching.py`
- [Candidate retrieval](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/services/retrieval.py): `backend/app/services/retrieval.py`
- [Candidate store](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/repositories/candidate_store.py): `backend/app/repositories/candidate_store.py`
- [Profile store](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/repositories/profile_store.py): `backend/app/repositories/profile_store.py`
- [Run store](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/repositories/run_store.py): `backend/app/repositories/run_store.py`

### Data preparation

- [Dataset pipeline](https://github.com/abhinavprkash/fetch-health/blob/main/data/data_pipeline/src/main.py): `data/data_pipeline/src/main.py`
- [Transplant data factory](https://github.com/abhinavprkash/fetch-health/blob/main/data/transplant_data_factory/src/main.py): `data/transplant_data_factory/src/main.py`
- [Profile builder](https://github.com/abhinavprkash/fetch-health/blob/main/data/transplant_data_factory/src/builders/profile_builder.py): `data/transplant_data_factory/src/builders/profile_builder.py`

### Local Bureau

- [Local Bureau](https://github.com/abhinavprkash/fetch-health/blob/main/local_agents/bureau.py): `local_agents/bureau.py`
- [Document worker](https://github.com/abhinavprkash/fetch-health/blob/main/local_agents/agents/document_parser.py): `local_agents/agents/document_parser.py`

### Shared integrations

- [LLM integration](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/integrations/llm.py): `backend/app/integrations/llm.py`
- [Audio transcription](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/integrations/audio.py): `backend/app/integrations/audio.py`
- [Edu diagrams](https://github.com/abhinavprkash/fetch-health/blob/main/backend/app/integrations/imagegen.py): `backend/app/integrations/imagegen.py`

### Other components

- **ASI:One user**
- **Redis Stack**
- **Claude / ASI:One**
- **Deepgram**
- **Midjourney proxy**

## Connections

- ASI:One user → Agent harness: submits tasks (evidence: `README.md`)
- Agent harness → Capability agents: routes capabilities (evidence: `README.md`)
- Agent harness → Agent activation: activates agents (evidence: `README.md`)
- Agent harness → FastAPI gateway: forwards requests (evidence: `README.md`)
- Capability agents → FastAPI gateway: uses gateway endpoints (evidence: `README.md`)
- FastAPI gateway → Agent requests: registers routes (evidence: `backend/app/main.py`)
- FastAPI gateway → Case uploads: registers routes (evidence: `backend/app/main.py`)
- FastAPI gateway → Run lifecycle: registers routes (evidence: `backend/app/main.py`)
- FastAPI gateway → Profiles: registers routes (evidence: `backend/app/main.py`)
- FastAPI gateway → Education API: registers routes (evidence: `backend/app/main.py`)
- Run lifecycle → Run orchestration: manages runs
- Run orchestration → Run store: updates run state (evidence: `backend/app/services/run_service.py`)
- Run orchestration → Donor matching: requests matches (evidence: `backend/app/services/run_service.py`)
- Run orchestration → Document analysis: coordinates processing
- Case uploads → Document analysis: dispatches document analysis
- Case uploads → Image video analysis: dispatches media analysis
- Donor matching → Candidate retrieval: retrieves candidates
- Candidate retrieval → Candidate store: searches candidates (evidence: `backend/app/services/retrieval.py`)
- Profiles → Candidate store: accesses candidates (evidence: `backend/app/routes/profiles.py`)
- Profiles → Profile store: uses profile storage
- FastAPI gateway → Candidate store: initializes store (evidence: `backend/app/main.py`)
- FastAPI gateway → Profile store: initializes store (evidence: `backend/app/main.py`)
- FastAPI gateway → Run store: initializes store (evidence: `backend/app/main.py`)
- Candidate store → Redis Stack: stores and searches
- Dataset pipeline → Transplant data factory: shares profile data conventions
- Transplant data factory → Profile builder: builds profiles (evidence: `data/transplant_data_factory/src/main.py`)
- Transplant data factory → Candidate store: exports candidate data
- Local Bureau → Document worker: registers worker (evidence: `local_agents/bureau.py`)
- Document worker → FastAPI gateway: gateway performs extraction (evidence: `local_agents/agents/document_parser.py`)
- Document analysis → LLM integration: uses extraction model
- LLM integration → Claude / ASI:One: calls provider (evidence: `backend/app/integrations/llm.py`)
- LLM integration → ASI:One user: calls ASI:One
- Audio transcription → Deepgram: transcribes media (evidence: `README.md`)
- Image video analysis → Audio transcription: uses transcription
- Education API → Edu diagrams: requests diagrams
- Edu diagrams → Midjourney proxy: generates diagrams (evidence: `README.md`)
