# karansampath/ai-sdr architecture

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

- Interactive diagram: https://gitdiagram.com/karansampath/ai-sdr
- Repository: https://github.com/karansampath/ai-sdr

## Overview

##### Project Type and Purpose
- This is a full-stack, AI-driven Sales Development Representative (SDR) application.
- The backend is a FastAPI service (async Python) providing REST endpoints for lead management, AI qualification, message personalization, pipeline operations, search, evaluation, and utilities.
- The frontend is a Streamlit web app serving as a simple UI for users.
- A DuckDB instance holds lead, interaction, and pipeline data.
- The system integrates with an external AI service (xAI Grok) for lead scoring and message generation.
- There is also a local evaluation framework (in evaluation_tests/) to benchmark consistency, performance, and edge cases.

##### File-Structure Analysis
- Top level: Dockerfile, docker-compose.yml, env.example, run.py (starter script for both services), pyproject.toml (dependencies).
- frontend/streamlit_app.py: Streamlit UI.
- src/: core Python modules—database.py (DuckDB wrapper), models.py (pydantic schemas), main.py (FastAPI app entrypoint), services.py (business logic), evaluation.py, grok.py, prompts/ (Jinja2 templates + manager).
- evaluation_tests/: standalone test scripts that call API endpoints or internal functions for consistency, performance, failure modes.
- scripts/: utility scripts (grok_demo.py, test.py).
- docker-compose.yml: orchestrates FastAPI and Streamlit, sets ports, environment variables.

##### Key Architectural Insights from README
- API endpoints grouped by feature (lead management, AI services, pipeline, evaluation, utilities).
- Async I/O throughout backend.
- Uses Jinja2 for dynamic prompt construction.
- Containerized deployment (Docker multi-service).
- Local dev vs production considerations.

##### Main Components
a. Frontend Layer
- Streamlit App (frontend/streamlit_app.py)
- Communicates via HTTP (port 8501 → 8000)
b. Backend Layer (Monolith)
- FastAPI Server (src/main.py)
- Modules:
- API Routers (lead, messages, pipeline, search, evaluate, health)
- Business Logic (src/services.py, src/evaluation.py, src/grok.py)
- Prompt Manager (src/prompts) plus Jinja2 templates
- Data Models (src/models.py)
- Database Access (src/database.py → DuckDB)
c. Data Storage
- DuckDB file-based database (data/ directory)
d. External Service
- xAI Grok API (external HTTP calls for qualification & messaging)
e. Evaluation Framework
- evaluation_tests/ scripts invoke API endpoints or internal functions
f. Utilities & Scripts
- scripts/grok_demo.py for manual testing
- run.py to start both services
g. Deployment
- Docker & docker-compose orchestration
- Environment variables (XAI_API_KEY, database path)

##### Relationships and Data Flow
1. User interacts with Streamlit UI → sends user actions (CRUD, qualify, search, etc.) to FastAPI.
2. FastAPI handler calls Business Logic → may read/write DuckDB or call external AI service.
3. For AI calls: Business Logic builds prompt via Prompt Manager (Jinja2), issues HTTP to xAI Grok, receives response, processes it.
4. Results returned to frontend or stored in DB (e.g., lead scores, pipeline changes).
5. Evaluation Tests and scripts can directly hit FastAPI endpoints or invoke internal libraries.
6. Docker Compose brings up two containers (backend, frontend) connected via network.

##### Architectural Patterns & Principles
- Modular Monolith: clear separation between API layer, business logic, data access, and prompt templating.
- Async I/O and event loop for high concurrency in AI calls and DB queries.
- Template-based prompt generation (Jinja2) for extensibility.
- Single-node DuckDB for analytics; no separate service.
- Containerized micro-services style (each service in its own container, but tightly coupled).

##### Technologies & Framework Highlights
- FastAPI (async endpoints, pydantic models)
- Streamlit (rapid UI prototyping)
- DuckDB (embedded OLAP database)
- xAI Grok (external AI inference)
- Jinja2 (prompt templating)
- Docker & docker-compose
- uv (package manager), ruff (linter)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend
    subgraph "Streamlit Frontend"
        direction TB
        StreamlitApp["Streamlit App"]:::frontend
    end

    %% Backend Monolith
    subgraph "FastAPI Backend"
        direction TB
        FastAPIServer["FastAPI Server"]:::backend
        APIRouters["API Routers & Endpoints"]:::backend
        subgraph "Business Logic"
            direction TB
            LeadPipeline["Lead Mgmt & Pipeline Ops"]:::backend
            EvaluationLogic["Evaluation Routines"]:::backend
            GrokIntegration["xAI Grok Integration"]:::backend
        end
        DataModels["Data Models (Pydantic)"]:::backend
        DBAccess["DB Access Layer (DuckDB)"]:::backend
        subgraph "Prompt Manager"
            direction TB
            PromptMgr["Prompt Manager"]:::backend
            subgraph "Prompt Templates"
                direction TB
                Template1["lead_qualification_system.j2"]:::backend
                Template2["lead_qualification_user.j2"]:::backend
                Template3["message_personalization_system.j2"]:::backend
                Template4["message_personalization_user.j2"]:::backend
            end
        end
    end

    %% Data Store
    DuckDB["DuckDB Database"]:::datastore

    %% External AI Service
    xAIGrok["xAI Grok API"]:::external

    %% Evaluation Framework
    EvalTests["Evaluation Tests"]:::util

    %% Utility Scripts and Run
    subgraph "Utilities & Scripts"
        direction TB
        GrokDemo["grok_demo.py"]:::util
        TestScript["test.py"]:::util
        RunScript["run.py"]:::util
    end

    %% Deployment
    Deployment["Docker Compose & Configs"]:::util

    %% Connections
    StreamlitApp -->|HTTP 8501→8000| APIRouters
    APIRouters -->|Invokes| LeadPipeline
    APIRouters -->|Invokes| EvaluationLogic
    APIRouters -->|Invokes| GrokIntegration
    APIRouters -->|Uses| DataModels
    LeadPipeline -->|SQL Queries| DBAccess
    EvaluationLogic -->|SQL Queries| DBAccess
    DBAccess -->|Reads/Writes| DuckDB
    GrokIntegration -->|Builds Prompt| PromptMgr
    PromptMgr -->|Loads| Template1
    PromptMgr -->|Loads| Template2
    PromptMgr -->|Loads| Template3
    PromptMgr -->|Loads| Template4
    GrokIntegration -->|HTTP| xAIGrok
    EvalTests -->|HTTP| APIRouters
    GrokDemo -->|HTTP| APIRouters
    TestScript -->|HTTP| APIRouters
    RunScript -->|Starts| StreamlitApp
    RunScript -->|Starts| FastAPIServer
    Deployment -->|Orchestrates| StreamlitApp
    Deployment -->|Orchestrates| FastAPIServer
    Deployment -->|Env Vars| FastAPIServer

    %% Click Events
    click StreamlitApp "https://github.com/karansampath/ai-sdr/blob/main/frontend/streamlit_app.py"
    click FastAPIServer "https://github.com/karansampath/ai-sdr/blob/main/src/main.py"
    click APIRouters "https://github.com/karansampath/ai-sdr/blob/main/src/main.py"
    click LeadPipeline "https://github.com/karansampath/ai-sdr/blob/main/src/services.py"
    click EvaluationLogic "https://github.com/karansampath/ai-sdr/blob/main/src/evaluation.py"
    click GrokIntegration "https://github.com/karansampath/ai-sdr/blob/main/src/grok.py"
    click PromptMgr "https://github.com/karansampath/ai-sdr/blob/main/src/prompts/prompt_manager.py"
    click Template1 "https://github.com/karansampath/ai-sdr/blob/main/src/prompts/templates/lead_qualification_system.j2"
    click Template2 "https://github.com/karansampath/ai-sdr/blob/main/src/prompts/templates/lead_qualification_user.j2"
    click Template3 "https://github.com/karansampath/ai-sdr/blob/main/src/prompts/templates/message_personalization_system.j2"
    click Template4 "https://github.com/karansampath/ai-sdr/blob/main/src/prompts/templates/message_personalization_user.j2"
    click DataModels "https://github.com/karansampath/ai-sdr/blob/main/src/models.py"
    click DBAccess "https://github.com/karansampath/ai-sdr/blob/main/src/database.py"
    click EvalTests "https://github.com/karansampath/ai-sdr/tree/main/evaluation_tests/"
    click GrokDemo "https://github.com/karansampath/ai-sdr/blob/main/scripts/grok_demo.py"
    click TestScript "https://github.com/karansampath/ai-sdr/blob/main/scripts/test.py"
    click RunScript "https://github.com/karansampath/ai-sdr/blob/main/run.py"
    click Deployment "https://github.com/karansampath/ai-sdr/blob/main/docker-compose.yml"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef datastore fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef util fill:#EEEEEE,stroke:#333,stroke-width:1px;
```
