# Backend Architecture Guide

**Last Updated**: 2026-06-29  
**Change Log**:
- 2026-06-29: Initial version generated after cloning the repository.

---

## 🎯 Overview

The backend acts as the core orchestration, API layer, and pipeline processor for the Post-Call Analytics Platform. It is written in Python using **Flask** (and a migrated/parallel high-performance **FastAPI** deployment option), coupled with a **MySQL** cluster for metadata/transactional storage, **Qdrant** for vector retrieval, and **Redis** for caching.

---

## 📁 File Structure Map

```
dashboard-backend/
├── app.py                      # Flask Application entry point (defines endpoints)
├── fastapi_app.py              # Migrated FastAPI app structure for high throughput
├── config.py                   # Centralized Configuration (DBs, AWS, STT credentials)
├── db_handler.py               # DatabaseHandler class for raw MySQL queries & connection pooling
├── auth_handler.py             # JWT Token creation, validation, and Admin role verification
├── rag_handler.py              # Ingests, embeds, retrieves documents/conversations via Qdrant/MySQL
├── analytics.py                # AnalyticsService calculating KPIs, call duration averages, sentiment trends
├── agent_runner.py             # Orchestrates rendering of custom prompts to AWS Bedrock & Ollama
├── leadsquared_service.py      # LeadSquared CRM HTTP wrapper for fetching and syncing activities
├── sync_crm_leads.py           # Sync service pulling new CRM records to local cache
├── call_processor.py           # Core three-stage pipeline (Sync, Transcribe, Analyze)
├── stt/                        # Speech-To-Text module
│   ├── __init__.py             # Factory returning provider instance (Sarvam/Deepgram)
│   ├── base.py                 # Abstract base class BaseSTT
│   └── sarvam.py               # SarvamSTT integration (batches, polls, and formats diarized JSON)
└── migrations/                 # Schema updates and SQL migration scripts
```

---

## 📡 Endpoint Map

| Method | Path | Target File | Purpose |
|--------|------|-------------|---------|
| `POST` | `/auth/login` | `app.py` | Authenticates users and generates JWT token |
| `GET` | `/calls/<bid>` | `app.py` | Returns paginated call analytics with filters |
| `GET` | `/calls/<bid>/<callid>` | `app.py` | Fetches details (transcripts, speaker timelines) for a call |
| `POST` | `/rag/<bid>/query` | `app.py` | Query RAG assistant for specific tenant |
| `POST` | `/rag/<bid>/documents` | `app.py` | Ingest and embed corporate knowledge documents |
| `GET` | `/pipeline/<bid>/status` | `app.py` | Show pipeline run summaries, watermarks and queues |
| `GET` | `/agents/<bid>/leaderboard` | `app.py` | Fetch agent scores and leaderboards |

---

## 🔄 Service Dependency Diagram

```
      ┌─────────────────────────────────────────────────────────┐
      │                         Clients                         │
      │                  (Frontend UI / Iframe)                 │
      └───────────┬─────────────────────────────────┬───────────┘
                  │ JWT Token                       │ REST
                  ▼                                 ▼
      ┌─────────────────────────────────────────────────────────┐
      │                        Backend                          │
      │                 (app.py / fastapi_app.py)               │
      └────┬────────────┬─────────────┬─────────────┬───────────┘
           │            │             │             │
           ▼            ▼             ▼             ▼
      ┌──────────┐ ┌──────────┐  ┌──────────┐  ┌────────────────┐
      │   Auth   │ │Database  │  │   RAG    │  │   Analytics    │
      │ Handler  │ │ Handler  │  │ Handler  │  │    Service     │
      └──────────┘ └─────┬────┘  └────┬─────┘  └────────────────┘
                         │            │
                         ▼            ▼
                    ┌─────────┐  ┌──────────┐
                    │  MySQL  │  │  Qdrant  │
                    │ Cluster │  │Vector DB │
                    └─────────┘  └──────────┘
```

---

## ⚡ Execution Order & Middleware Lifecycle

1. **Authentication**: All endpoints (except `/auth/login` and webhook inputs) pass through a decorator or middleware invoking `auth_handler.py` to validate JWT.
2. **Context Resolution**: The tenant ID (`bid`) is verified from the route parameter. Database connections are dynamically fetched or routed based on `bid`.
3. **Caching**: Redis caches hot queries (like `/analytics` aggregates) to prevent expensive SQL aggregations.
4. **Error Handling**: Standard global error handlers return JSON formats like `{"success": false, "error": "Message"}` with appropriate HTTP codes.