# ace-ify/careva architecture

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

- Interactive diagram: https://gitdiagram.com/ace-ify/careva
- Repository: https://github.com/ace-ify/careva

## Overview

Careva is a Hindi/English voice health helpline for browser and phone callers. A caller joins a LiveKit session, speaks with the primary agent, and receives spoken guidance or a specialist handoff; the agent can look up facilities, schemes, medicines, and air quality, remember callers, and create human escalations. The frontend also exposes call and escalation views. Core backend relationships are supported by excerpts and the SOURCE INDEX; some additional README capabilities are documented but their implementation details were not sampled.

Main entry points: [`backend/src/agent.py`](https://github.com/ace-ify/careva/blob/main/backend/src/agent.py) (Careva agent), [`backend/src/handoff.py`](https://github.com/ace-ify/careva/blob/main/backend/src/handoff.py) (Agent handoff), [`backend/src/facilities.py`](https://github.com/ace-ify/careva/blob/main/backend/src/facilities.py) (Facility locator), [`backend/src/db.py`](https://github.com/ace-ify/careva/blob/main/backend/src/db.py) (Caller and call records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Caller access"]
  node_webapp["Voice session UI<br/>[app.tsx]"]
  node_token["Session token API<br/>[route.ts]"]
  node_livekit["LiveKit transport"]
end

subgraph group_conversation["Voice agents"]
  node_agent["Careva agent<br/>[agent.py]"]
  node_specialist["Clinic specialist"]
  node_handoff["Agent handoff<br/>[handoff.py]"]
end

subgraph group_health["Health services"]
  node_facilities["Facility locator<br/>[facilities.py]"]
  node_knowledge["Health knowledge search<br/>[rag.py]"]
  node_healthapi["Health data tools"]
  node_publicdata["Public health APIs"]
end

subgraph group_state["Memory and follow-up"]
  node_memory[("Caller and call records<br/>[db.py]")]
  node_outbound["Reminder dispatch<br/>[outbound.py]"]
end

subgraph group_operations["Operations interface"]
  node_admin["Admin dashboard<br/>[page.tsx]"]
  node_callsapi["Call analytics API<br/>[route.ts]"]
  node_escalationsapi["Escalation API<br/>[route.ts]"]
  node_forgetapi["Forget API<br/>[route.ts]"]
end

node_caller(("Caller"))
node_phone["Phone network"]

node_caller -->|"starts session"| node_webapp
node_webapp -->|"requests token"| node_token
node_token -->|"issues credentials"| node_livekit
node_caller -->|"sends audio"| node_livekit
node_livekit -->|"routes session"| node_agent
node_agent -->|"returns speech"| node_livekit
node_agent -->|"queries facilities"| node_facilities
node_agent -->|"searches guidance"| node_knowledge
node_agent -->|"requests health data"| node_healthapi
node_facilities -->|"queries registries"| node_publicdata
node_healthapi -->|"queries live data"| node_publicdata
node_agent -->|"reads and writes"| node_memory
node_specialist -->|"looks up details"| node_facilities
node_agent -.->|"initiates transfer"| node_handoff
node_handoff -->|"activates specialist"| node_specialist
node_handoff -->|"returns control"| node_agent
node_agent -.->|"dispatches reminders"| node_outbound
node_outbound -->|"dispatches call"| node_livekit
node_livekit -->|"connects calls"| node_phone
node_admin -.->|"views analytics"| node_callsapi
node_admin -.->|"manages cases"| node_escalationsapi
node_callsapi -->|"reads call data"| node_memory
node_forgetapi -.->|"removes caller data"| node_memory

click node_webapp "https://github.com/ace-ify/careva/blob/main/frontend/components/app/app.tsx"
click node_token "https://github.com/ace-ify/careva/blob/main/frontend/app/api/token/route.ts"
click node_agent "https://github.com/ace-ify/careva/blob/main/backend/src/agent.py"
click node_specialist "https://github.com/ace-ify/careva/blob/main/backend/src/clinic_specialist.py"
click node_handoff "https://github.com/ace-ify/careva/blob/main/backend/src/handoff.py"
click node_facilities "https://github.com/ace-ify/careva/blob/main/backend/src/facilities.py"
click node_knowledge "https://github.com/ace-ify/careva/blob/main/backend/src/rag.py"
click node_healthapi "https://github.com/ace-ify/careva/blob/main/backend/src/health_mcp_server.py"
click node_memory "https://github.com/ace-ify/careva/blob/main/backend/src/db.py"
click node_outbound "https://github.com/ace-ify/careva/blob/main/backend/src/outbound.py"
click node_admin "https://github.com/ace-ify/careva/blob/main/frontend/app/admin/page.tsx"
click node_callsapi "https://github.com/ace-ify/careva/blob/main/frontend/app/api/calls/route.ts"
click node_escalationsapi "https://github.com/ace-ify/careva/blob/main/frontend/app/api/escalations/route.ts"
click node_forgetapi "https://github.com/ace-ify/careva/blob/main/frontend/app/api/forget/route.ts"

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_webapp,node_token,node_livekit toneBlue
class node_agent,node_specialist,node_handoff toneAmber
class node_facilities,node_knowledge,node_healthapi,node_publicdata toneMint
class node_memory,node_outbound toneRose
class node_admin,node_callsapi,node_escalationsapi,node_forgetapi,node_caller,node_phone toneIndigo
```

## Components

### Caller access

- [Voice session UI](https://github.com/ace-ify/careva/blob/main/frontend/components/app/app.tsx): `frontend/components/app/app.tsx`
- [Session token API](https://github.com/ace-ify/careva/blob/main/frontend/app/api/token/route.ts): `frontend/app/api/token/route.ts`
- **LiveKit transport**

### Voice agents

- [Careva agent](https://github.com/ace-ify/careva/blob/main/backend/src/agent.py): `backend/src/agent.py`
- [Clinic specialist](https://github.com/ace-ify/careva/blob/main/backend/src/clinic_specialist.py): `backend/src/clinic_specialist.py`
- [Agent handoff](https://github.com/ace-ify/careva/blob/main/backend/src/handoff.py): `backend/src/handoff.py`

### Health services

- [Facility locator](https://github.com/ace-ify/careva/blob/main/backend/src/facilities.py): `backend/src/facilities.py`
- [Health knowledge search](https://github.com/ace-ify/careva/blob/main/backend/src/rag.py): `backend/src/rag.py`
- [Health data tools](https://github.com/ace-ify/careva/blob/main/backend/src/health_mcp_server.py): `backend/src/health_mcp_server.py`
- **Public health APIs**

### Memory and follow-up

- [Caller and call records](https://github.com/ace-ify/careva/blob/main/backend/src/db.py): `backend/src/db.py`
- [Reminder dispatch](https://github.com/ace-ify/careva/blob/main/backend/src/outbound.py): `backend/src/outbound.py`

### Operations interface

- [Admin dashboard](https://github.com/ace-ify/careva/blob/main/frontend/app/admin/page.tsx): `frontend/app/admin/page.tsx`
- [Call analytics API](https://github.com/ace-ify/careva/blob/main/frontend/app/api/calls/route.ts): `frontend/app/api/calls/route.ts`
- [Escalation API](https://github.com/ace-ify/careva/blob/main/frontend/app/api/escalations/route.ts): `frontend/app/api/escalations/route.ts`
- [Forget API](https://github.com/ace-ify/careva/blob/main/frontend/app/api/forget/route.ts): `frontend/app/api/forget/route.ts`

### Other components

- **Caller**
- **Phone network**

## Connections

- Caller → Voice session UI: starts session
- Voice session UI → Session token API: requests token (evidence: `frontend/components/app/app.tsx`)
- Session token API → LiveKit transport: issues credentials (evidence: `frontend/app/api/token/route.ts`)
- Caller → LiveKit transport: sends audio
- LiveKit transport → Careva agent: routes session
- Careva agent → LiveKit transport: returns speech
- Careva agent → Facility locator: queries facilities (evidence: `backend/src/agent.py`)
- Careva agent → Health knowledge search: searches guidance (evidence: `backend/src/agent.py`)
- Careva agent → Health data tools: requests health data (evidence: `backend/src/agent.py`)
- Facility locator → Public health APIs: queries registries (evidence: `backend/src/facilities.py`)
- Health data tools → Public health APIs: queries live data (evidence: `backend/src/health_mcp_server.py`)
- Careva agent → Caller and call records: reads and writes (evidence: `backend/src/agent.py`)
- Clinic specialist → Facility locator: looks up details (evidence: `backend/src/clinic_specialist.py`)
- Careva agent → Agent handoff: initiates transfer (evidence: `backend/src/agent.py`)
- Agent handoff → Clinic specialist: activates specialist (evidence: `backend/src/handoff.py`)
- Agent handoff → Careva agent: returns control (evidence: `backend/src/handoff.py`)
- Careva agent → Reminder dispatch: dispatches reminders (evidence: `backend/src/agent.py`)
- Reminder dispatch → LiveKit transport: dispatches call (evidence: `backend/src/outbound.py`)
- LiveKit transport → Phone network: connects calls
- Admin dashboard → Call analytics API: views analytics
- Admin dashboard → Escalation API: manages cases
- Call analytics API → Caller and call records: reads call data (evidence: `frontend/app/api/calls/route.ts`)
- Forget API → Caller and call records: removes caller data
