# aadityagupta01/ai-voice-detection architecture

> Architecture diagram of the GitHub repository aadityagupta01/ai-voice-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aadityagupta01/ai-voice-detection
- Repository: https://github.com/aadityagupta01/ai-voice-detection

## Overview

AI Voice Detection is a five-language audio classifier, exposed through an API and accompanied by notebooks and saved artifacts for feature extraction and model training. The primary user workflow is an API request with a Base64 MP3: the service checks access and inputs, decodes and preprocesses audio, predicts a class, and returns confidence and an explanation. The README documents offline audio analysis, MFCC feature extraction, and classical-model training; the tree includes the notebooks and feature arrays. Those notebook internals were not sampled, so their links reflect documented stages only.

Main entry points: [`main.py`](https://github.com/aadityagupta01/ai-voice-detection/blob/main/main.py) (Detection Endpoint), [`notebooks/ml_feature_extraction.ipynb`](https://github.com/aadityagupta01/ai-voice-detection/blob/main/notebooks/ml_feature_extraction.ipynb) (ML Features), [`notebooks/ml_training.ipynb`](https://github.com/aadityagupta01/ai-voice-detection/blob/main/notebooks/ml_training.ipynb) (Model Training), [`artifacts/features/ML`](https://github.com/aadityagupta01/ai-voice-detection/tree/main/artifacts/features/ML) (ML Feature Arrays)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_offline["Offline Modeling"]
  node_analysis["Audio Analysis"]
  node_ml_features["ML Features"]
  node_dl_features["DL Features"]
  node_training["Model Training<br/>[ml_training.ipynb]"]
end

subgraph group_service["Detection API"]
  node_api["Detection Endpoint<br/>[main.py]"]
  node_auth["API Key Check<br/>[main.py]"]
  node_validation["Request Validation<br/>[main.py]"]
  node_decode["Base64 Decode<br/>[main.py]"]
  node_preprocess["Audio Preprocessing<br/>[main.py]"]
  node_features["Feature Extraction<br/>[main.py]"]
  node_inference["Model Inference<br/>[main.py]"]
  node_explanation["Result Explanation<br/>[main.py]"]
end

subgraph group_assets["Model Assets"]
  node_ml_arrays["ML Feature Arrays"]
  node_dl_arrays["DL Feature Arrays"]
  node_model["Trained Model"]
end

node_caller(("API Caller"))

node_analysis -->|"analyzes audio"| node_ml_features
node_ml_features -->|"saves features"| node_ml_arrays
node_dl_features -->|"saves features"| node_dl_arrays
node_ml_arrays -->|"trains from"| node_training
node_training -->|"selects model"| node_model
node_caller -->|"submits request"| node_api
node_api -->|"checks key"| node_auth
node_api -->|"validates fields"| node_validation
node_api -->|"decodes audio"| node_decode
node_api -->|"processes audio"| node_preprocess
node_preprocess -->|"extracts features"| node_features
node_api -->|"predicts class"| node_inference
node_model -->|"loaded at startup"| node_inference
node_api -->|"formats result"| node_explanation

click node_analysis "https://github.com/aadityagupta01/ai-voice-detection/blob/main/notebooks/audio_analysis.ipynb"
click node_ml_features "https://github.com/aadityagupta01/ai-voice-detection/blob/main/notebooks/ml_feature_extraction.ipynb"
click node_dl_features "https://github.com/aadityagupta01/ai-voice-detection/blob/main/notebooks/dl_feature_extraction.ipynb"
click node_ml_arrays "https://github.com/aadityagupta01/ai-voice-detection/tree/main/artifacts/features/ML"
click node_dl_arrays "https://github.com/aadityagupta01/ai-voice-detection/tree/main/artifacts/features/DL"
click node_training "https://github.com/aadityagupta01/ai-voice-detection/blob/main/notebooks/ml_training.ipynb"
click node_model "https://github.com/aadityagupta01/ai-voice-detection/blob/main/artifacts/models/best_ml_model.joblib"
click node_api "https://github.com/aadityagupta01/ai-voice-detection/blob/main/main.py"
click node_auth "https://github.com/aadityagupta01/ai-voice-detection/blob/main/main.py"
click node_validation "https://github.com/aadityagupta01/ai-voice-detection/blob/main/main.py"
click node_decode "https://github.com/aadityagupta01/ai-voice-detection/blob/main/main.py"
click node_preprocess "https://github.com/aadityagupta01/ai-voice-detection/blob/main/main.py"
click node_features "https://github.com/aadityagupta01/ai-voice-detection/blob/main/main.py"
click node_inference "https://github.com/aadityagupta01/ai-voice-detection/blob/main/main.py"
click node_explanation "https://github.com/aadityagupta01/ai-voice-detection/blob/main/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_analysis,node_ml_features,node_dl_features,node_training toneBlue
class node_api,node_auth,node_validation,node_decode,node_preprocess,node_features,node_inference,node_explanation toneAmber
class node_ml_arrays,node_dl_arrays,node_model,node_caller toneMint
```

## Components

### Offline Modeling

- [Audio Analysis](https://github.com/aadityagupta01/ai-voice-detection/blob/main/notebooks/audio_analysis.ipynb): `notebooks/audio_analysis.ipynb`
- [ML Features](https://github.com/aadityagupta01/ai-voice-detection/blob/main/notebooks/ml_feature_extraction.ipynb): `notebooks/ml_feature_extraction.ipynb`
- [DL Features](https://github.com/aadityagupta01/ai-voice-detection/blob/main/notebooks/dl_feature_extraction.ipynb): `notebooks/dl_feature_extraction.ipynb`
- [Model Training](https://github.com/aadityagupta01/ai-voice-detection/blob/main/notebooks/ml_training.ipynb): `notebooks/ml_training.ipynb`

### Detection API

- [Detection Endpoint](https://github.com/aadityagupta01/ai-voice-detection/blob/main/main.py): `main.py`
- [API Key Check](https://github.com/aadityagupta01/ai-voice-detection/blob/main/main.py): `main.py`
- [Request Validation](https://github.com/aadityagupta01/ai-voice-detection/blob/main/main.py): `main.py`
- [Base64 Decode](https://github.com/aadityagupta01/ai-voice-detection/blob/main/main.py): `main.py`
- [Audio Preprocessing](https://github.com/aadityagupta01/ai-voice-detection/blob/main/main.py): `main.py`
- [Feature Extraction](https://github.com/aadityagupta01/ai-voice-detection/blob/main/main.py): `main.py`
- [Model Inference](https://github.com/aadityagupta01/ai-voice-detection/blob/main/main.py): `main.py`
- [Result Explanation](https://github.com/aadityagupta01/ai-voice-detection/blob/main/main.py): `main.py`

### Model Assets

- [ML Feature Arrays](https://github.com/aadityagupta01/ai-voice-detection/tree/main/artifacts/features/ML): `artifacts/features/ML`
- [DL Feature Arrays](https://github.com/aadityagupta01/ai-voice-detection/tree/main/artifacts/features/DL): `artifacts/features/DL`
- [Trained Model](https://github.com/aadityagupta01/ai-voice-detection/blob/main/artifacts/models/best_ml_model.joblib): `artifacts/models/best_ml_model.joblib`

### Other components

- **API Caller**

## Connections

- Audio Analysis → ML Features: analyzes audio
- ML Features → ML Feature Arrays: saves features
- DL Features → DL Feature Arrays: saves features
- ML Feature Arrays → Model Training: trains from
- Model Training → Trained Model: selects model
- API Caller → Detection Endpoint: submits request
- Detection Endpoint → API Key Check: checks key
- Detection Endpoint → Request Validation: validates fields
- Detection Endpoint → Base64 Decode: decodes audio
- Detection Endpoint → Audio Preprocessing: processes audio
- Audio Preprocessing → Feature Extraction: extracts features
- Detection Endpoint → Model Inference: predicts class
- Trained Model → Model Inference: loaded at startup
- Detection Endpoint → Result Explanation: formats result