# satishvarma2733-byte/ai-agent architecture

> Architecture diagram of the GitHub repository satishvarma2733-byte/ai-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/satishvarma2733-byte/ai-agent
- Repository: https://github.com/satishvarma2733-byte/ai-agent

## Overview

AVN Agent is a voice-agent backend with a FastAPI management and operations API. The principal workflow is a caller reaching the voice worker, which conducts a LiveKit conversation; the backend supports call records, appointments, analytics, and outbound campaign dispatch. Knowledge-base ingestion runs as a separate worker. README describes a backend-only distribution, despite frontend files in the tree, so the frontend is not mapped as a shipped product surface. Workflow and worker links reflect sampled source; unsampled runtime wiring is left out.

Main entry points: [`app/main.py`](https://github.com/satishvarma2733-byte/ai-agent/blob/main/app/main.py) (FastAPI App), [`agent.py`](https://github.com/satishvarma2733-byte/ai-agent/blob/main/agent.py) (Voice Worker), [`outbound_calls.py`](https://github.com/satishvarma2733-byte/ai-agent/blob/main/outbound_calls.py) (Outbound Dispatch), [`app/routers`](https://github.com/satishvarma2733-byte/ai-agent/tree/main/app/routers) (API Routers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_voice["Voice Runtime"]
  node_agent["Voice Worker<br/>[agent.py]"]
  node_outbound["Outbound Dispatch<br/>[outbound_calls.py]"]
end

subgraph group_api["Backend API"]
  node_backend_api["HTTP Entrypoint<br/>[backend_api.py]"]
  node_app_main["FastAPI App<br/>[main.py]"]
  node_routers["API Routers"]
  node_database["Database Layer<br/>[database.py]"]
end

subgraph group_operations["Operations"]
  node_campaign_worker["Campaign Worker<br/>[campaign_worker.py]"]
  node_campaign_routes["Campaign API<br/>[campaigns.py]"]
  node_workflow_engine["Workflow Engine<br/>[workflow_engine.py]"]
  node_workflow_events["Workflow Events<br/>[workflow_events.py]"]
  node_appointment_routes["Appointments API<br/>[appointments.py]"]
end

subgraph group_knowledge["Knowledge Base"]
  node_kb_worker["KB Worker<br/>[kb_worker.py]"]
  node_kb_runtime["KB Processing<br/>[kb.py]"]
end

node_caller(("Caller"))
node_data_store[("Application Data")]
node_livekit["LiveKit"]
node_kb_store[("KB Data")]

node_caller -->|"speaks with"| node_agent
node_agent -->|"uses"| node_livekit
node_backend_api -->|"serves"| node_app_main
node_app_main -->|"registers"| node_routers
node_routers -->|"accesses"| node_database
node_database -->|"connects to"| node_data_store
node_app_main -->|"starts"| node_campaign_worker
node_app_main -->|"starts"| node_workflow_engine
node_app_main -->|"registers"| node_appointment_routes
node_app_main -->|"registers"| node_campaign_routes
node_campaign_worker -->|"dispatches"| node_outbound
node_outbound -->|"dispatches call"| node_livekit
node_workflow_engine -->|"claims events"| node_workflow_events
node_kb_worker -->|"processes jobs"| node_kb_runtime
node_kb_runtime -->|"reads and writes"| node_kb_store

click node_backend_api "https://github.com/satishvarma2733-byte/ai-agent/blob/main/backend_api.py"
click node_app_main "https://github.com/satishvarma2733-byte/ai-agent/blob/main/app/main.py"
click node_routers "https://github.com/satishvarma2733-byte/ai-agent/tree/main/app/routers"
click node_database "https://github.com/satishvarma2733-byte/ai-agent/blob/main/app/core/database.py"
click node_agent "https://github.com/satishvarma2733-byte/ai-agent/blob/main/agent.py"
click node_outbound "https://github.com/satishvarma2733-byte/ai-agent/blob/main/outbound_calls.py"
click node_campaign_worker "https://github.com/satishvarma2733-byte/ai-agent/blob/main/app/services/campaign_worker.py"
click node_campaign_routes "https://github.com/satishvarma2733-byte/ai-agent/blob/main/app/routers/campaigns.py"
click node_workflow_engine "https://github.com/satishvarma2733-byte/ai-agent/blob/main/app/services/workflow_engine.py"
click node_workflow_events "https://github.com/satishvarma2733-byte/ai-agent/blob/main/app/services/workflow_events.py"
click node_appointment_routes "https://github.com/satishvarma2733-byte/ai-agent/blob/main/app/routers/appointments.py"
click node_kb_worker "https://github.com/satishvarma2733-byte/ai-agent/blob/main/kb_worker.py"
click node_kb_runtime "https://github.com/satishvarma2733-byte/ai-agent/blob/main/kb.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_agent,node_outbound toneBlue
class node_backend_api,node_app_main,node_routers,node_database,node_data_store,node_kb_store toneAmber
class node_campaign_worker,node_campaign_routes,node_workflow_engine,node_workflow_events,node_appointment_routes toneMint
class node_kb_worker,node_kb_runtime toneRose
class node_caller,node_livekit toneIndigo
```

## Components

### Voice Runtime

- [Voice Worker](https://github.com/satishvarma2733-byte/ai-agent/blob/main/agent.py): `agent.py`
- [Outbound Dispatch](https://github.com/satishvarma2733-byte/ai-agent/blob/main/outbound_calls.py): `outbound_calls.py`

### Backend API

- [HTTP Entrypoint](https://github.com/satishvarma2733-byte/ai-agent/blob/main/backend_api.py): `backend_api.py`
- [FastAPI App](https://github.com/satishvarma2733-byte/ai-agent/blob/main/app/main.py): `app/main.py`
- [API Routers](https://github.com/satishvarma2733-byte/ai-agent/tree/main/app/routers): `app/routers`
- [Database Layer](https://github.com/satishvarma2733-byte/ai-agent/blob/main/app/core/database.py): `app/core/database.py`

### Operations

- [Campaign Worker](https://github.com/satishvarma2733-byte/ai-agent/blob/main/app/services/campaign_worker.py): `app/services/campaign_worker.py`
- [Campaign API](https://github.com/satishvarma2733-byte/ai-agent/blob/main/app/routers/campaigns.py): `app/routers/campaigns.py`
- [Workflow Engine](https://github.com/satishvarma2733-byte/ai-agent/blob/main/app/services/workflow_engine.py): `app/services/workflow_engine.py`
- [Workflow Events](https://github.com/satishvarma2733-byte/ai-agent/blob/main/app/services/workflow_events.py): `app/services/workflow_events.py`
- [Appointments API](https://github.com/satishvarma2733-byte/ai-agent/blob/main/app/routers/appointments.py): `app/routers/appointments.py`

### Knowledge Base

- [KB Worker](https://github.com/satishvarma2733-byte/ai-agent/blob/main/kb_worker.py): `kb_worker.py`
- [KB Processing](https://github.com/satishvarma2733-byte/ai-agent/blob/main/kb.py): `kb.py`

### Other components

- **Caller**
- **Application Data**
- **LiveKit**
- **KB Data**

## Connections

- Caller → Voice Worker: speaks with
- Voice Worker → LiveKit: uses
- HTTP Entrypoint → FastAPI App: serves
- FastAPI App → API Routers: registers
- API Routers → Database Layer: accesses
- Database Layer → Application Data: connects to
- FastAPI App → Campaign Worker: starts
- FastAPI App → Workflow Engine: starts
- FastAPI App → Appointments API: registers
- FastAPI App → Campaign API: registers
- Campaign Worker → Outbound Dispatch: dispatches
- Outbound Dispatch → LiveKit: dispatches call
- Workflow Engine → Workflow Events: claims events
- KB Worker → KB Processing: processes jobs
- KB Processing → KB Data: reads and writes