# nabilmohamed99/callcenter_calls_analysis architecture

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

- Interactive diagram: https://gitdiagram.com/nabilmohamed99/callcenter_calls_analysis
- Repository: https://github.com/nabilmohamed99/callcenter_calls_analysis

## Overview

##### Project Type and Purpose
- This is a containerized, full-stack “Call Center QA” pipeline that runs entirely on CPU.
- Purpose: ingest WAV files (either seeded or uploaded interactively), store them in MongoDB GridFS, run a multi-stage ML pipeline (VAD, transcription + diarization, quality scoring & insights using Gemini 1.5 Pro), then present results via a Streamlit GUI.

##### Top-Level Components
a. Ingestion Layer
- 01_seed_callhome.py / 01_seed_callhome_darija.py: one-shot scripts to seed sample calls into MongoDB GridFS
- Streamlit upload widget (app.py/app_final_safe.py): interactive user uploads
b. Storage Layer
- MongoDB + GridFS (defined in docker-compose.yml) holds raw audio blobs and resulting metadata (transcripts, scores, summaries)
c. Pipeline Orchestrator
- src/graph.py: defines the DAG of processing steps
- src/supervisor.py: boots the pipeline, watches for new audio, schedules tasks
d. Processing Nodes (src/nodes/*)
1. ingest.py → pulls raw audio from GridFS, hands off to VAD
2. vad_diar_role.py → Whisper-base VAD segmentation (agent vs. client)
3. audio_one_to_txt.json & score_analyst.py → Gemini 1.5 Pro for transcription, diarization, scoring, summaries, sentiment curves
4. sink.py → writes back transcripts, scores, insights to MongoDB
e. GUI Layer
- Streamlit app (app.py / app_final_safe.py)
- Syncs an audio player + waveform display with transcript, score, insights

##### Key Architectural Patterns & Principles
- Modular, pluggable pipeline: each node is an independent Python module under src/nodes
- Orchestrator + DAG separation (graph.py vs supervisor.py) follows dataflow architecture
- All services containerized (Dockerfile + docker-compose), enabling zero-config deployment
- CPU-only ML inference, no external cloud dependencies beyond local Gemini model

##### Technologies & Frameworks
- Python 3.x, Streamlit (UI)
- MongoDB + GridFS (storage)
- Whisper-base for VAD
- Gemini 1.5 Pro for transcription & evaluation
- Docker & Docker Compose (deployment)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Ingestion Layer"
        B1["01_seed_callhome.py"]:::script
        B2["01_seed_callhome_darija.py"]:::script
        B3["Streamlit Upload Widget (app.py)"]:::ui
    end

    subgraph "Storage Layer"
        DB[(MongoDB + GridFS)]:::storage
    end

    subgraph "Pipeline Orchestrator"
        G["src/graph.py"]:::orchestrator
        S["src/supervisor.py"]:::orchestrator
    end

    subgraph "Processing Nodes"
        N1["src/nodes/ingest.py"]:::ml
        N2["src/nodes/vad_diar_role.py"]:::ml
        N3["src/nodes/audio_one_to_txt.json"]:::ml
        N4["src/nodes/score_analyst.py"]:::ml
        N5["src/nodes/sink.py"]:::ml
    end

    subgraph "Deployment"
        D1["Dockerfile"]:::infra
        D2["docker-compose.yml"]:::infra
        D3["docker-compose_test.yml"]:::infra
    end

    subgraph "GUI Layer"
        UI["Streamlit App (app.py)"]:::ui
    end

    %% Data Flows
    B1 -->|"WAV file"| DB
    B2 -->|"WAV file"| DB
    B3 -->|"WAV file"| DB

    S -->|"watches new audio"| N1
    G -->|"defines DAG"| S

    N1 -->|"raw audio segments"| N2
    N2 -->|"speaker segments"| N3
    N3 -->|"transcript + roles"| N4
    N4 -->|"scores + insights"| N5
    N5 -->|"metadata write"| DB

    UI -->|"reads audio + metadata"| DB

    %% Deployment connections
    D2 --> DB
    D2 --> S
    D2 --> UI
    D1 --> D2
    D3 --> D2

    %% Click Events
    click B1 "https://github.com/nabilmohamed99/callcenter_calls_analysis/blob/main/01_seed_callhome.py"
    click B2 "https://github.com/nabilmohamed99/callcenter_calls_analysis/blob/main/01_seed_callhome_darija.py"
    click B3 "https://github.com/nabilmohamed99/callcenter_calls_analysis/blob/main/app.py"
    click DB "https://github.com/nabilmohamed99/callcenter_calls_analysis/blob/main/docker-compose.yml"
    click G "https://github.com/nabilmohamed99/callcenter_calls_analysis/blob/main/src/graph.py"
    click S "https://github.com/nabilmohamed99/callcenter_calls_analysis/blob/main/src/supervisor.py"
    click N1 "https://github.com/nabilmohamed99/callcenter_calls_analysis/blob/main/src/nodes/ingest.py"
    click N2 "https://github.com/nabilmohamed99/callcenter_calls_analysis/blob/main/src/nodes/vad_diar_role.py"
    click N3 "https://github.com/nabilmohamed99/callcenter_calls_analysis/blob/main/src/nodes/audio_one_to_txt.json"
    click N4 "https://github.com/nabilmohamed99/callcenter_calls_analysis/blob/main/src/nodes/score_analyst.py"
    click N5 "https://github.com/nabilmohamed99/callcenter_calls_analysis/blob/main/src/nodes/sink.py"
    click D1 "https://github.com/nabilmohamed99/callcenter_calls_analysis/tree/main/Dockerfile"
    click D2 "https://github.com/nabilmohamed99/callcenter_calls_analysis/blob/main/docker-compose.yml"
    click D3 "https://github.com/nabilmohamed99/callcenter_calls_analysis/blob/main/docker-compose_test.yml"

    %% Styles
    classDef storage fill:#BBDEFB,stroke:#000
    classDef ml fill:#C8E6C9,stroke:#000
    classDef orchestrator fill:#FFE0B2,stroke:#000
    classDef ui fill:#FFF9C4,stroke:#000
    classDef script fill:#E1BEE7,stroke:#000
    classDef infra fill:#CFD8DC,stroke:#000
```
