# prachirathi07/cogvoice-poc architecture

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

- Interactive diagram: https://gitdiagram.com/prachirathi07/cogvoice-poc
- Repository: https://github.com/prachirathi07/cogvoice-poc

## Overview

##### Project Type and Purpose
- This is a Python-based Proof-of-Concept voice-analysis web application built with Streamlit. It ingests short audio samples, extracts acoustic and linguistic features (via Whisper), applies basic unsupervised ML to highlight potential signs of cognitive decline, and presents the results in a simple UI. It also includes an offline training pipeline to build the model from training data.

##### File Structure Analysis
Top-level files:
- Dockerfile – containerizes the app and its dependencies
- app.py – Streamlit front-end for real-time inference
- config.py – central configuration for paths, model parameters, external tools
- requirements.txt – Python libraries, including Streamlit, Whisper, ML packages
- start.ipynb – exploratory notebook
- README.md

Data and models:
- data/Control, data/Dementia – raw WAV files
- data/features_and_transcripts.csv – precomputed features/transcripts from training set
- data/models/models.pkl – serialized ML model

Processing and ML:
- feature_extractor.py – functions to extract acoustic features (pauses, pitch) and invoke Whisper for transcripts, compute linguistic metrics
- train_pipeline.py – batch pipeline: reads raw data, calls feature_extractor, trains unsupervised model, saves models.pkl
- prediction.py – loads models.pkl, given a new audio file runs feature_extractor and returns scores/class labels
- main.py – orchestrates end-to-end inference logic (could be reused by both CLI and app.py)

##### Key Components
a. Data Layer (raw audio & model storage)
- Raw audio folder (data/Control, data/Dementia)
- Features/Transcripts CSV (intermediate store)
- Model artifact (data/models/models.pkl)
b. Offline Training Pipeline (batch)
- train_pipeline.py
- feature_extractor.py
- External: Whisper STT & ffmpeg
- Output: serialized model
c. Online Inference Service
- Streamlit UI (app.py)
- main.py / prediction.py
- feature_extractor.py
- Model loader (models.pkl)
- External: Whisper STT & ffmpeg
d. Configuration & Environment
- config.py for paths & hyperparameters
- Docker container (Dockerfile) encapsulating all services/dependencies

##### Relationships and Data Flows
- Offline path: Raw audio → feature_extractor → features.csv → train_pipeline → models.pkl
- Online path: User uploads audio via Streamlit → main.py/prediction.py invokes feature_extractor → model.predict → results returned to UI

##### Architectural Patterns & Design Principles
- Separation of concerns:
- Data Extraction (feature_extractor)
- Model Training (train_pipeline)
- Inference (prediction/main + UI)
- Batch vs. real-time: clearly delineate the offline training workflow vs. the real-time inference workflow
- Modular reuse: feature_extractor is shared by both training and inference
- Containerization: Docker ensures consistent environment

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Layer"
        RawData["Raw Data Store\n(data/Control/, data/Dementia/)"]:::data
        FeaturesCSV["Features/Transcripts CSV\n(data/features_and_transcripts.csv)"]:::data
        ModelStore["Model Artifact\n(data/models/models.pkl)"]:::model
    end

    subgraph "External Dependencies"
        Whisper["Whisper STT / ffmpeg"]:::external
    end

    subgraph "Offline Training Pipeline"
        FE["Feature Extraction Module\n(feature_extractor.py)"]:::processing
        Train["Offline Training Pipeline\n(train_pipeline.py)"]:::processing
    end

    subgraph "Online Inference Service"
        UI["Streamlit UI\n(app.py)"]:::ui
        Main["Inference Orchestration\n(main.py)"]:::processing
        Predict["Prediction API\n(prediction.py)"]:::processing
    end

    subgraph "Config & Environment"
        Config["Configuration & Environment Settings\n(config.py)"]:::config
        Docker["Containerization Definition\n(Dockerfile)"]:::config
        Req["Dependency Specification\n(requirements.txt)"]:::config
    end

    subgraph "Exploratory Notebook"
        Notebook["Exploratory Notebook\n(start.ipynb)"]:::notebook
    end

    RawData -->|"wav files"| FE
    FE -->|"features.csv"| FeaturesCSV
    FeaturesCSV -->|"training data"| Train
    Train -->|"models.pkl"| ModelStore

    User["User"]:::ui -->|"upload .wav"| UI
    UI -->|"calls main()"| Main
    Main -->|"calls feature_extractor"| FE
    FE -->|"extract features"| Main
    Main -->|"load model"| ModelStore
    Main -->|"predict() call"| Predict
    Predict -->|"returns scores"| UI

    Whisper -->|"used by"| FE

    Config -->|"settings used by"| FE
    Config -->|"settings used by"| Train
    Config -->|"settings used by"| Main
    Config -->|"settings used by"| UI

    Docker -->|"encapsulates"| Config
    Docker -->|"encapsulates"| FE
    Docker -->|"encapsulates"| Train
    Docker -->|"encapsulates"| UI
    Docker -->|"encapsulates"| Main
    Docker -->|"encapsulates"| Predict

    Notebook -->|"exploration"| FE
    Notebook -->|"data analysis"| Train

    classDef data fill:#d0e1f9,stroke:#333,stroke-width:1px
    classDef processing fill:#f9d0d0,stroke:#333,stroke-width:1px
    classDef model fill:#d0f9d0,stroke:#333,stroke-width:1px
    classDef ui fill:#e0d0f9,stroke:#333,stroke-width:1px
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px
    classDef config fill:#f9f9d0,stroke:#333,stroke-width:1px
    classDef notebook fill:#f0e0f0,stroke:#333,stroke-width:1px

    click RawData "https://github.com/prachirathi07/cogvoice-poc/tree/main/data/Control/"
    click RawData "https://github.com/prachirathi07/cogvoice-poc/tree/main/data/Dementia/"
    click FeaturesCSV "https://github.com/prachirathi07/cogvoice-poc/blob/main/data/features_and_transcripts.csv"
    click ModelStore "https://github.com/prachirathi07/cogvoice-poc/blob/main/data/models/models.pkl"
    click FE "https://github.com/prachirathi07/cogvoice-poc/blob/main/feature_extractor.py"
    click Train "https://github.com/prachirathi07/cogvoice-poc/blob/main/train_pipeline.py"
    click Main "https://github.com/prachirathi07/cogvoice-poc/blob/main/main.py"
    click Predict "https://github.com/prachirathi07/cogvoice-poc/blob/main/prediction.py"
    click UI "https://github.com/prachirathi07/cogvoice-poc/blob/main/app.py"
    click Config "https://github.com/prachirathi07/cogvoice-poc/blob/main/config.py"
    click Docker "https://github.com/prachirathi07/cogvoice-poc/tree/main/Dockerfile"
    click Req "https://github.com/prachirathi07/cogvoice-poc/blob/main/requirements.txt"
    click Notebook "https://github.com/prachirathi07/cogvoice-poc/blob/main/start.ipynb"
```
