# eshaanpra/scaihackathonv2 architecture

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

- Interactive diagram: https://gitdiagram.com/eshaanpra/scaihackathonv2
- Repository: https://github.com/eshaanpra/scaihackathonv2

## Overview

##### Project Type and Purpose
- This is a Python-based research/hackathon prototype (CLI application) that benchmarks ASR equity in customer-support call flows.
- It runs a configurable pipeline: loads speech samples → transcribes (ASR) → classifies intent → computes fairness metrics → generates visual reports.

##### File Structure Analysis
- Top-level:
- configs/ – YAML configurations for different modes (quick demo, real-data, OpenAI Whisper, etc.)
- src/ – core modules: main.py, pipeline, data loader, ASR wrapper, intent classifier, metrics, visualization
- requirements.txt, run_quick_demo.sh – setup/run scripts
- src/ modules follow a clear ETL pipeline pattern:
- data_loader.py (input)
- asr_engine.py (transcription)
- intent_classifier.py (downstream model)
- metrics.py (calculations)

##### Architecture Insights from README
- Entry point: src/main.py reads a config, instantiates Pipeline.
- Pipeline components are pluggable (mock ASR vs. Whisper vs. HF), driven by configs.
- Outputs: CSV/JSON metrics + matplotlib plots, organized under outputs/<run_name>.

a. Main Components
- CLI / Config Loader
- Data Loader
- ASR Engine (mock | Whisper)
- Intent Classifier
- Metrics Calculator
- Visualizer (plots, heatmaps)
- File System (configs, input corpora, outputs)
- External Services: speech datasets (Common Voice, CallHome, GLOBE), model repos (HuggingFace, OpenAI)
b. Relationships & Data Flow
1) User invokes CLI → config.yaml
2) Config Loader → Pipeline orchestrator
3) Pipeline calls Data Loader → loads/streams audio + metadata
4) Each sample → ASR Engine → transcript
5) Transcript → Intent Classifier → predicted intent
6) References vs. predictions → Metrics Calculator → WER, intent error, disparity index
7) Metrics + raw results → Visualizer → plots/CSVs under outputs/
c. Architectural Patterns & Principles
- Modular pipeline: single-responsibility modules chained in sequence
- Configuration-driven behavior enabling offline demo or real-data runs
- Pluggable ASR backends using a wrapper interface (mock vs. whisper vs. hf_whisper)
d. Technologies & Frameworks
- Python 3.10+ core, PyYAML (config), numpy, matplotlib
- Optional: datasets, openai-whisper, librosa, soundfile, torch/transformers

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interaction"
        QuickDemo["Run Quick Demo"]:::input
        CLI["CLI (main.py)"]:::input
    end

    ConfigFiles[(Configs)]:::input
    Outputs[(Outputs / CSV & Plots)]:::output

    subgraph "Pipeline Modules"
        Pipeline["Pipeline Orchestrator"]:::processing
        DataLoader["Data Loader"]:::processing
        ASREngine["ASR Engine"]:::processing
        IntentClassifier["Intent Classifier"]:::processing
        Metrics["Metrics Calculator"]:::processing
        TextUtils["Text Utils"]:::processing
    end

    subgraph "Visualization"
        Visualizer["Visualizer (plots)"]:::output
        AccentGraphs["Accent Graphs"]:::output
    end

    subgraph "External Services"  
        CommonVoice["Common Voice"]:::external
        CallHome["CallHome"]:::external
        GLOBE["GLOBE"]:::external
        HF["HuggingFace Models"]:::external
        OpenAI["OpenAI Whisper"]:::external
    end

    QuickDemo -->|executes| CLI
    CLI -->|loads| ConfigFiles
    CLI -->|invokes| Pipeline
    Pipeline -->|uses| TextUtils
    Pipeline -->|loads data| DataLoader
    DataLoader -->|streams samples| ASREngine
    ASREngine -->|transcript| IntentClassifier
    IntentClassifier -->|predictions| Metrics
    Metrics -->|calculates metrics| Visualizer
    Metrics -->|calculates metrics| AccentGraphs
    Visualizer -->|writes| Outputs
    AccentGraphs -->|writes| Outputs

    CommonVoice ---|audio| DataLoader
    CallHome ---|audio| DataLoader
    GLOBE ---|audio| DataLoader
    HF ---|models| ASREngine
    OpenAI ---|models| ASREngine

    click CLI "https://github.com/eshaanpra/scaihackathonv2/blob/main/src/main.py"
    click ConfigFiles "https://github.com/eshaanpra/scaihackathonv2/tree/main/configs/"
    click QuickDemo "https://github.com/eshaanpra/scaihackathonv2/blob/main/run_quick_demo.sh"
    click Pipeline "https://github.com/eshaanpra/scaihackathonv2/blob/main/src/pipeline.py"
    click DataLoader "https://github.com/eshaanpra/scaihackathonv2/blob/main/src/data_loader.py"
    click ASREngine "https://github.com/eshaanpra/scaihackathonv2/blob/main/src/asr_engine.py"
    click IntentClassifier "https://github.com/eshaanpra/scaihackathonv2/blob/main/src/intent_classifier.py"
    click Metrics "https://github.com/eshaanpra/scaihackathonv2/blob/main/src/metrics.py"
    click Visualizer "https://github.com/eshaanpra/scaihackathonv2/blob/main/src/visualize.py"
    click AccentGraphs "https://github.com/eshaanpra/scaihackathonv2/blob/main/src/accent_graphs.py"
    click TextUtils "https://github.com/eshaanpra/scaihackathonv2/blob/main/src/text_utils.py"
    click Requirements "https://github.com/eshaanpra/scaihackathonv2/blob/main/requirements.txt"

    classDef input fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef processing fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef output fill:#FFFF99,stroke:#333,stroke-width:1px
```
