# chillandbuild/aira-ai architecture

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

- Interactive diagram: https://gitdiagram.com/chillandbuild/aira-ai
- Repository: https://github.com/chillandbuild/aira-ai

## Overview

AIRA is a multi-tenant lead-management and customer-engagement product: its Android companion syncs call logs, while the web dashboard supports business and operator workflows backed by a FastAPI service. A central customer path is an inbound WhatsApp webhook, conversation handling, AI-assisted reply, and channel response; the dashboard separately manages leads, knowledge, deals, analytics, and calling. Groups reflect these product areas and the backend’s shared runtime. The README is empty, so feature coverage is inferred from the source tree; unsampled components and relationships are shown conservatively.

Main entry points: [`frontend/app/dashboard/DashboardClient.tsx`](https://github.com/chillandbuild/aira-ai/blob/main/frontend/app/dashboard/DashboardClient.tsx) (Dashboard), [`backend/app/services/ai_reply.py`](https://github.com/chillandbuild/aira-ai/blob/main/backend/app/services/ai_reply.py) (AI Reply Engine), [`backend/app/routes/webhook.py`](https://github.com/chillandbuild/aira-ai/blob/main/backend/app/routes/webhook.py) (WhatsApp Webhook), [`android/app/src/main/java/com/aira/sync/SyncWorker.kt`](https://github.com/chillandbuild/aira-ai/blob/main/android/app/src/main/java/com/aira/sync/SyncWorker.kt) (Sync Worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Android Sync"]
  node_sync_service["Sync Service<br/>[SyncService.kt]"]
  node_sync_worker["Sync Worker<br/>[SyncWorker.kt]"]
  node_call_log["Call Log Reader<br/>[CallLogReader.kt]"]
  node_android_api["API Client<br/>[AiraApi.kt]"]
  node_prefs["Sync Preferences<br/>[Prefs.kt]"]
end

subgraph group_web["Web Dashboard"]
  node_auth_context["Auth Context"]
  node_dashboard["Dashboard"]
  node_lead_workspace["Lead Workspace<br/>[LeadsClient.tsx]"]
  node_inbound_leads["Inbound Leads"]
  node_brain_ui["Brain Workspace<br/>[useBrainData.ts]"]
  node_call_ui["Telecalling"]
end

subgraph group_api["Backend API"]
  node_api_entry["API App<br/>[main.py]"]
  node_webhook["WhatsApp Webhook<br/>[webhook.py]"]
  node_routes["HTTP Routes"]
  node_auth["Auth Dependencies<br/>[auth.py]"]
  node_db_client["Supabase Client<br/>[supabase.py]"]
  node_dynamic_config["Tenant Settings<br/>[config_dynamic.py]"]
  node_database[("Supabase")]
end

subgraph group_conversation["Conversation Intelligence"]
  node_reply_engine["AI Reply Engine<br/>[ai_reply.py]"]
  node_knowledge["Knowledge Service"]
  node_model_client["Gemini Client<br/>[gemini_client.py]"]
  node_scoring["Lead Scoring<br/>[scoring_engine.py]"]
end

subgraph group_operations["Business Operations"]
  node_intake["Paid Intake<br/>[intake.py]"]
  node_deal_engine["Deal Engine<br/>[deal_engine.py]"]
  node_deals["Deal Service<br/>[deals.py]"]
  node_calls_pipeline["Call AI Pipeline"]
end

node_android_user(("Phone User"))
node_web_user(("Business User"))
node_external_customer(("Messaging Customer"))
node_meta{{"Meta Messaging"}}
node_razorpay{{"Razorpay"}}

node_android_user -.->|"starts sync"| node_sync_service
node_sync_service -->|"schedules"| node_sync_worker
node_sync_worker -->|"reads calls"| node_call_log
node_sync_worker -->|"uploads logs"| node_android_api
node_sync_worker -->|"reads settings"| node_prefs
node_web_user -.->|"signs in"| node_auth_context
node_auth_context -->|"provides role"| node_dashboard
node_dashboard -.->|"opens leads"| node_lead_workspace
node_dashboard -.->|"opens inbound"| node_inbound_leads
node_dashboard -.->|"opens brain"| node_brain_ui
node_dashboard -.->|"opens calling"| node_call_ui
node_api_entry -->|"uses auth"| node_auth
node_api_entry -->|"registers routes"| node_routes
node_api_entry -->|"registers webhook"| node_webhook
node_webhook -->|"gets database"| node_db_client
node_db_client -->|"queries"| node_database
node_dynamic_config -->|"reads settings"| node_db_client
node_webhook -.->|"receives messages"| node_external_customer
node_meta -.->|"posts events"| node_webhook
node_webhook -.->|"handles replies"| node_reply_engine
node_reply_engine -->|"retrieves context"| node_knowledge
node_reply_engine -.->|"calls model"| node_model_client
node_reply_engine -.->|"sends response"| node_meta
node_reply_engine -->|"reads and writes"| node_database
node_knowledge -->|"reads knowledge"| node_database
node_model_client -->|"gets credentials"| node_dynamic_config
node_scoring -->|"classifies lead"| node_model_client
node_scoring -->|"reads lead data"| node_database
node_intake -->|"uses deal rules"| node_deal_engine
node_intake -->|"uses deal service"| node_deals
node_intake -.->|"creates payment"| node_razorpay
node_deals -->|"uses deal rules"| node_deal_engine
node_deals -->|"reads and writes"| node_database
node_calls_pipeline -->|"tracks processing"| node_database
node_calls_pipeline -.->|"fetches recordings"| node_meta

click node_sync_service "https://github.com/chillandbuild/aira-ai/blob/main/android/app/src/main/java/com/aira/sync/SyncService.kt"
click node_sync_worker "https://github.com/chillandbuild/aira-ai/blob/main/android/app/src/main/java/com/aira/sync/SyncWorker.kt"
click node_call_log "https://github.com/chillandbuild/aira-ai/blob/main/android/app/src/main/java/com/aira/sync/CallLogReader.kt"
click node_android_api "https://github.com/chillandbuild/aira-ai/blob/main/android/app/src/main/java/com/aira/sync/AiraApi.kt"
click node_prefs "https://github.com/chillandbuild/aira-ai/blob/main/android/app/src/main/java/com/aira/sync/Prefs.kt"
click node_auth_context "https://github.com/chillandbuild/aira-ai/blob/main/frontend/app/dashboard/contexts/AuthRoleContext.tsx"
click node_dashboard "https://github.com/chillandbuild/aira-ai/blob/main/frontend/app/dashboard/DashboardClient.tsx"
click node_lead_workspace "https://github.com/chillandbuild/aira-ai/blob/main/frontend/app/dashboard/leads/LeadsClient.tsx"
click node_inbound_leads "https://github.com/chillandbuild/aira-ai/blob/main/frontend/app/dashboard/inbound-leads/InboundLeadsClient.tsx"
click node_brain_ui "https://github.com/chillandbuild/aira-ai/blob/main/frontend/components/brain/useBrainData.ts"
click node_call_ui "https://github.com/chillandbuild/aira-ai/blob/main/frontend/app/dashboard/telecalling/lib/useCallingCockpit.ts"
click node_api_entry "https://github.com/chillandbuild/aira-ai/blob/main/backend/app/main.py"
click node_webhook "https://github.com/chillandbuild/aira-ai/blob/main/backend/app/routes/webhook.py"
click node_routes "https://github.com/chillandbuild/aira-ai/tree/main/backend/app/routes"
click node_auth "https://github.com/chillandbuild/aira-ai/blob/main/backend/app/dependencies/auth.py"
click node_db_client "https://github.com/chillandbuild/aira-ai/blob/main/backend/app/db/supabase.py"
click node_dynamic_config "https://github.com/chillandbuild/aira-ai/blob/main/backend/app/config_dynamic.py"
click node_reply_engine "https://github.com/chillandbuild/aira-ai/blob/main/backend/app/services/ai_reply.py"
click node_knowledge "https://github.com/chillandbuild/aira-ai/blob/main/backend/app/services/knowledge_service.py"
click node_model_client "https://github.com/chillandbuild/aira-ai/blob/main/backend/app/services/gemini_client.py"
click node_scoring "https://github.com/chillandbuild/aira-ai/blob/main/backend/app/services/scoring_engine.py"
click node_intake "https://github.com/chillandbuild/aira-ai/blob/main/backend/app/services/intake.py"
click node_deal_engine "https://github.com/chillandbuild/aira-ai/blob/main/backend/app/services/deal_engine.py"
click node_deals "https://github.com/chillandbuild/aira-ai/blob/main/backend/app/services/deals.py"
click node_calls_pipeline "https://github.com/chillandbuild/aira-ai/blob/main/backend/app/services/call_ai_pipeline.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_sync_service,node_sync_worker,node_call_log,node_android_api,node_prefs,node_android_user,node_web_user toneBlue
class node_auth_context,node_dashboard,node_lead_workspace,node_inbound_leads,node_brain_ui,node_call_ui toneAmber
class node_api_entry,node_webhook,node_routes,node_auth,node_db_client,node_dynamic_config,node_database toneMint
class node_reply_engine,node_knowledge,node_model_client,node_scoring toneRose
class node_intake,node_deal_engine,node_deals,node_calls_pipeline,node_external_customer,node_meta,node_razorpay toneIndigo
```

## Components

### Android Sync

- [Sync Service](https://github.com/chillandbuild/aira-ai/blob/main/android/app/src/main/java/com/aira/sync/SyncService.kt): `android/app/src/main/java/com/aira/sync/SyncService.kt`
- [Sync Worker](https://github.com/chillandbuild/aira-ai/blob/main/android/app/src/main/java/com/aira/sync/SyncWorker.kt): `android/app/src/main/java/com/aira/sync/SyncWorker.kt`
- [Call Log Reader](https://github.com/chillandbuild/aira-ai/blob/main/android/app/src/main/java/com/aira/sync/CallLogReader.kt): `android/app/src/main/java/com/aira/sync/CallLogReader.kt`
- [API Client](https://github.com/chillandbuild/aira-ai/blob/main/android/app/src/main/java/com/aira/sync/AiraApi.kt): `android/app/src/main/java/com/aira/sync/AiraApi.kt`
- [Sync Preferences](https://github.com/chillandbuild/aira-ai/blob/main/android/app/src/main/java/com/aira/sync/Prefs.kt): `android/app/src/main/java/com/aira/sync/Prefs.kt`

### Web Dashboard

- [Auth Context](https://github.com/chillandbuild/aira-ai/blob/main/frontend/app/dashboard/contexts/AuthRoleContext.tsx): `frontend/app/dashboard/contexts/AuthRoleContext.tsx`
- [Dashboard](https://github.com/chillandbuild/aira-ai/blob/main/frontend/app/dashboard/DashboardClient.tsx): `frontend/app/dashboard/DashboardClient.tsx`
- [Lead Workspace](https://github.com/chillandbuild/aira-ai/blob/main/frontend/app/dashboard/leads/LeadsClient.tsx): `frontend/app/dashboard/leads/LeadsClient.tsx`
- [Inbound Leads](https://github.com/chillandbuild/aira-ai/blob/main/frontend/app/dashboard/inbound-leads/InboundLeadsClient.tsx): `frontend/app/dashboard/inbound-leads/InboundLeadsClient.tsx`
- [Brain Workspace](https://github.com/chillandbuild/aira-ai/blob/main/frontend/components/brain/useBrainData.ts): `frontend/components/brain/useBrainData.ts`
- [Telecalling](https://github.com/chillandbuild/aira-ai/blob/main/frontend/app/dashboard/telecalling/lib/useCallingCockpit.ts): `frontend/app/dashboard/telecalling/lib/useCallingCockpit.ts`

### Backend API

- [API App](https://github.com/chillandbuild/aira-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [WhatsApp Webhook](https://github.com/chillandbuild/aira-ai/blob/main/backend/app/routes/webhook.py): `backend/app/routes/webhook.py`
- [HTTP Routes](https://github.com/chillandbuild/aira-ai/tree/main/backend/app/routes): `backend/app/routes`
- [Auth Dependencies](https://github.com/chillandbuild/aira-ai/blob/main/backend/app/dependencies/auth.py): `backend/app/dependencies/auth.py`
- [Supabase Client](https://github.com/chillandbuild/aira-ai/blob/main/backend/app/db/supabase.py): `backend/app/db/supabase.py`
- [Tenant Settings](https://github.com/chillandbuild/aira-ai/blob/main/backend/app/config_dynamic.py): `backend/app/config_dynamic.py`
- **Supabase**

### Conversation Intelligence

- [AI Reply Engine](https://github.com/chillandbuild/aira-ai/blob/main/backend/app/services/ai_reply.py): `backend/app/services/ai_reply.py`
- [Knowledge Service](https://github.com/chillandbuild/aira-ai/blob/main/backend/app/services/knowledge_service.py): `backend/app/services/knowledge_service.py`
- [Gemini Client](https://github.com/chillandbuild/aira-ai/blob/main/backend/app/services/gemini_client.py): `backend/app/services/gemini_client.py`
- [Lead Scoring](https://github.com/chillandbuild/aira-ai/blob/main/backend/app/services/scoring_engine.py): `backend/app/services/scoring_engine.py`

### Business Operations

- [Paid Intake](https://github.com/chillandbuild/aira-ai/blob/main/backend/app/services/intake.py): `backend/app/services/intake.py`
- [Deal Engine](https://github.com/chillandbuild/aira-ai/blob/main/backend/app/services/deal_engine.py): `backend/app/services/deal_engine.py`
- [Deal Service](https://github.com/chillandbuild/aira-ai/blob/main/backend/app/services/deals.py): `backend/app/services/deals.py`
- [Call AI Pipeline](https://github.com/chillandbuild/aira-ai/blob/main/backend/app/services/call_ai_pipeline.py): `backend/app/services/call_ai_pipeline.py`

### Other components

- **Phone User**
- **Business User**
- **Messaging Customer**
- **Meta Messaging**
- **Razorpay**

## Connections

- Phone User → Sync Service: starts sync
- Sync Service → Sync Worker: schedules (evidence: `android/app/src/main/java/com/aira/sync/SyncService.kt`)
- Sync Worker → Call Log Reader: reads calls (evidence: `android/app/src/main/java/com/aira/sync/SyncWorker.kt`)
- Sync Worker → API Client: uploads logs (evidence: `android/app/src/main/java/com/aira/sync/SyncWorker.kt`)
- Sync Worker → Sync Preferences: reads settings (evidence: `android/app/src/main/java/com/aira/sync/SyncWorker.kt`)
- Business User → Auth Context: signs in
- Auth Context → Dashboard: provides role (evidence: `frontend/app/dashboard/DashboardClient.tsx`)
- Dashboard → Lead Workspace: opens leads
- Dashboard → Inbound Leads: opens inbound
- Dashboard → Brain Workspace: opens brain
- Dashboard → Telecalling: opens calling
- API App → Auth Dependencies: uses auth (evidence: `backend/app/main.py`)
- API App → HTTP Routes: registers routes (evidence: `backend/app/main.py`)
- API App → WhatsApp Webhook: registers webhook (evidence: `backend/app/main.py`)
- WhatsApp Webhook → Supabase Client: gets database (evidence: `backend/app/routes/webhook.py`)
- Supabase Client → Supabase: queries (evidence: `backend/app/db/supabase.py`)
- Tenant Settings → Supabase Client: reads settings (evidence: `backend/app/config_dynamic.py`)
- WhatsApp Webhook → Messaging Customer: receives messages
- Meta Messaging → WhatsApp Webhook: posts events
- WhatsApp Webhook → AI Reply Engine: handles replies (evidence: `backend/app/routes/webhook.py`)
- AI Reply Engine → Knowledge Service: retrieves context (evidence: `backend/app/services/ai_reply.py`)
- AI Reply Engine → Gemini Client: calls model (evidence: `backend/app/services/ai_reply.py`)
- AI Reply Engine → Meta Messaging: sends response
- AI Reply Engine → Supabase: reads and writes (evidence: `backend/app/services/ai_reply.py`)
- Knowledge Service → Supabase: reads knowledge (evidence: `backend/app/services/knowledge_service.py`)
- Gemini Client → Tenant Settings: gets credentials (evidence: `backend/app/services/gemini_client.py`)
- Lead Scoring → Gemini Client: classifies lead (evidence: `backend/app/services/scoring_engine.py`)
- Lead Scoring → Supabase: reads lead data (evidence: `backend/app/services/scoring_engine.py`)
- Paid Intake → Deal Engine: uses deal rules (evidence: `backend/app/services/intake.py`)
- Paid Intake → Deal Service: uses deal service (evidence: `backend/app/services/intake.py`)
- Paid Intake → Razorpay: creates payment
- Deal Service → Deal Engine: uses deal rules (evidence: `backend/app/services/deals.py`)
- Deal Service → Supabase: reads and writes (evidence: `backend/app/services/deals.py`)
- Call AI Pipeline → Supabase: tracks processing (evidence: `backend/app/services/call_ai_pipeline.py`)
- Call AI Pipeline → Meta Messaging: fetches recordings
