# sksahilkhan67sh/ai-callingagent architecture

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

- Interactive diagram: https://gitdiagram.com/sksahilkhan67sh/ai-callingagent
- Repository: https://github.com/sksahilkhan67sh/ai-callingagent

## Overview

AI Calling Agent imports contacts, organizes campaigns, and admits eligible calls to a durable dialing workflow. Calls use either the native voice stack or the optional Dograh integration; terminal outcomes feed recovery or post-call analysis. Operators monitor campaigns, calls, analytics, and system health through an authenticated Next.js dashboard. The README documents the principal flows and capabilities; source excerpts and the index confirm selected wiring. Several worker and route implementations were not sampled, so uncertain internal connections are omitted.

Main entry points: [`backend/app/api/routes`](https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/backend/app/api/routes) (Public routes), [`backend/app/services/queue/dialer_worker.py`](https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/services/queue/dialer_worker.py) (Dialer worker), [`backend/app/services/telephony`](https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/backend/app/services/telephony) (Telephony provider), [`backend/app/services/ai/conversation/orchestrator.py`](https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/services/ai/conversation/orchestrator.py) (Conversation engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operations["Operations UI"]
  node_dashboard["Admin dashboard"]
  node_admin_client["Admin API client<br/>[admin-api.ts]"]
end

subgraph group_api["API and domain"]
  node_admin_routes["Admin routes"]
  node_admin_services["Admin services"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_public_routes["Public routes"]
  node_contacts_campaigns["Contacts and campaigns"]
  node_suppression["Suppression checks"]
  node_postgres[("Postgres domain data")]
end

subgraph group_outbound["Outbound calling"]
  node_outbound_queue["Outbound queue"]
  node_dialer["Dialer worker<br/>[dialer_worker.py]"]
  node_telephony["Telephony provider"]
end

subgraph group_conversation["Voice and recovery"]
  node_conversation_engine["Conversation engine<br/>[orchestrator.py]"]
  node_ai_providers["Speech and language"]
  node_recovery["Recovery manager<br/>[manager.py]"]
end

subgraph group_analysis["Post-call analysis"]
  node_analysis_admission["Analysis admission<br/>[admission.py]"]
  node_analysis_queue["Analysis queue<br/>[queue.py]"]
  node_analysis_worker["Analysis worker<br/>[worker.py]"]
  node_analysis_result[("Call intelligence<br/>[call_analysis.py]")]
end

node_operator(("Operator"))
node_dograh["Dograh service"]

node_operator -->|"uses"| node_dashboard
node_dashboard -->|"requests data"| node_admin_client
node_admin_client -->|"calls API"| node_admin_routes
node_api_app -->|"mounts"| node_admin_routes
node_api_app -->|"mounts"| node_public_routes
node_admin_routes -->|"wraps"| node_admin_services
node_public_routes -->|"manages"| node_contacts_campaigns
node_contacts_campaigns -.->|"persists"| node_postgres
node_dialer -.->|"claims jobs"| node_outbound_queue
node_outbound_queue -.->|"dispatches jobs"| node_dialer
node_dialer -->|"places calls"| node_telephony
node_telephony -->|"triggers calls"| node_dograh
node_dograh -->|"posts outcomes"| node_public_routes
node_telephony -.->|"connects call"| node_conversation_engine
node_conversation_engine -->|"runs voice loop"| node_ai_providers
node_conversation_engine -->|"requests recovery"| node_recovery
node_recovery -->|"admits terminal calls"| node_analysis_admission
node_public_routes -->|"receives webhook outcome"| node_analysis_admission
node_analysis_admission -->|"publishes jobs"| node_analysis_queue
node_analysis_queue -.->|"feeds jobs"| node_analysis_worker
node_analysis_worker -->|"stores analysis"| node_analysis_result
node_analysis_worker -->|"loads conversation"| node_postgres
node_suppression -.->|"reads and writes"| node_postgres

click node_dashboard "https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/frontend/app/admin"
click node_admin_client "https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/frontend/lib/admin-api.ts"
click node_admin_routes "https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/backend/app/api/routes"
click node_admin_services "https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/backend/app/services/admin"
click node_api_app "https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/main.py"
click node_public_routes "https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/backend/app/api/routes"
click node_contacts_campaigns "https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/backend/app/services"
click node_suppression "https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/repositories/suppression_repository.py"
click node_postgres "https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/backend/app/models"
click node_outbound_queue "https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/backend/app/services/queue"
click node_dialer "https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/services/queue/dialer_worker.py"
click node_telephony "https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/backend/app/services/telephony"
click node_conversation_engine "https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/services/ai/conversation/orchestrator.py"
click node_ai_providers "https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/backend/app/services/ai"
click node_recovery "https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/services/recovery/manager.py"
click node_analysis_admission "https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/services/analysis/admission.py"
click node_analysis_queue "https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/services/analysis/queue.py"
click node_analysis_worker "https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/services/analysis/worker.py"
click node_analysis_result "https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/models/call_analysis.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_dashboard,node_admin_client toneBlue
class node_admin_routes,node_admin_services,node_api_app,node_public_routes,node_contacts_campaigns,node_suppression,node_postgres toneAmber
class node_outbound_queue,node_dialer,node_telephony toneMint
class node_conversation_engine,node_ai_providers,node_recovery toneRose
class node_analysis_admission,node_analysis_queue,node_analysis_worker,node_analysis_result,node_operator,node_dograh toneIndigo
```

## Components

### Operations UI

- [Admin dashboard](https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/frontend/app/admin): `frontend/app/admin`
- [Admin API client](https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/frontend/lib/admin-api.ts): `frontend/lib/admin-api.ts`

### API and domain

- [Admin routes](https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/backend/app/api/routes): `backend/app/api/routes`
- [Admin services](https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/backend/app/services/admin): `backend/app/services/admin`
- [FastAPI app](https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/main.py): `backend/app/main.py`
- [Public routes](https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/backend/app/api/routes): `backend/app/api/routes`
- [Contacts and campaigns](https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/backend/app/services): `backend/app/services`
- [Suppression checks](https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/repositories/suppression_repository.py): `backend/app/repositories/suppression_repository.py`
- [Postgres domain data](https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/backend/app/models): `backend/app/models`

### Outbound calling

- [Outbound queue](https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/backend/app/services/queue): `backend/app/services/queue`
- [Dialer worker](https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/services/queue/dialer_worker.py): `backend/app/services/queue/dialer_worker.py`
- [Telephony provider](https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/backend/app/services/telephony): `backend/app/services/telephony`

### Voice and recovery

- [Conversation engine](https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/services/ai/conversation/orchestrator.py): `backend/app/services/ai/conversation/orchestrator.py`
- [Speech and language](https://github.com/sksahilkhan67sh/ai-callingagent/tree/main/backend/app/services/ai): `backend/app/services/ai`
- [Recovery manager](https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/services/recovery/manager.py): `backend/app/services/recovery/manager.py`

### Post-call analysis

- [Analysis admission](https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/services/analysis/admission.py): `backend/app/services/analysis/admission.py`
- [Analysis queue](https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/services/analysis/queue.py): `backend/app/services/analysis/queue.py`
- [Analysis worker](https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/services/analysis/worker.py): `backend/app/services/analysis/worker.py`
- [Call intelligence](https://github.com/sksahilkhan67sh/ai-callingagent/blob/main/backend/app/models/call_analysis.py): `backend/app/models/call_analysis.py`

### Other components

- **Operator**
- **Dograh service**

## Connections

- Operator → Admin dashboard: uses (evidence: `README.md`)
- Admin dashboard → Admin API client: requests data (evidence: `frontend/lib/admin-api.ts`)
- Admin API client → Admin routes: calls API (evidence: `README.md`)
- FastAPI app → Admin routes: mounts (evidence: `backend/app/main.py`)
- FastAPI app → Public routes: mounts (evidence: `backend/app/main.py`)
- Admin routes → Admin services: wraps (evidence: `README.md`)
- Public routes → Contacts and campaigns: manages (evidence: `README.md`)
- Contacts and campaigns → Postgres domain data: persists (evidence: `backend/app/services/ai/policy/engine.py`)
- Dialer worker → Outbound queue: claims jobs
- Outbound queue → Dialer worker: dispatches jobs
- Dialer worker → Telephony provider: places calls (evidence: `README.md`)
- Telephony provider → Dograh service: triggers calls (evidence: `README.md`)
- Dograh service → Public routes: posts outcomes (evidence: `README.md`)
- Telephony provider → Conversation engine: connects call
- Conversation engine → Speech and language: runs voice loop (evidence: `README.md`)
- Conversation engine → Recovery manager: requests recovery (evidence: `backend/app/services/recovery/manager.py`)
- Recovery manager → Analysis admission: admits terminal calls (evidence: `README.md`)
- Public routes → Analysis admission: receives webhook outcome
- Analysis admission → Analysis queue: publishes jobs (evidence: `backend/app/services/analysis/admission.py`)
- Analysis queue → Analysis worker: feeds jobs (evidence: `backend/app/services/analysis/worker.py`)
- Analysis worker → Call intelligence: stores analysis (evidence: `README.md`)
- Analysis worker → Postgres domain data: loads conversation (evidence: `README.md`)
- Suppression checks → Postgres domain data: reads and writes (evidence: `backend/app/repositories/suppression_repository.py`)