# srujanrana07/fakeifi_deepfake_voice_detection_pipeline architecture

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

- Interactive diagram: https://gitdiagram.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline
- Repository: https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline

## Overview

1. This repository is centered on a Python backend for deepfake voice detection, with a research/ML training history and UI mockups around it. The main production path is a Flask API that accepts audio, processes it, runs inference, and returns a label plus confidence.

2. The core runtime boundary is:
   audio client or frontend -> Flask app in `app.py` -> audio preprocessing / feature extraction in `voice_analysis.py` -> model inference in `voice_model.py` -> JSON response back to the client.

3. `voice_analysis.py` is the signal-processing layer. Based on the README, it performs the audio normalization pipeline: resampling to 16 kHz, mono conversion, optional silence trimming, amplitude normalization, and feature extraction such as MFCCs, spectrogram-related features, pitch, and silence statistics.

4. `voice_model.py` is the inference layer. It likely loads the trained CNN artifact from `saved_models/SceneFake_CNN_SMOTE.h5` and uses `models/label_encoder.joblib` to map numeric outputs back to human-readable classes such as Real and Fake.

5. The primary model artifact is a 1D CNN trained on MFCC feature maps. The README indicates a binary classifier with ReLU/MaxPooling/Dropout blocks, Adam optimization, and sparse categorical cross-entropy. This suggests the backend is optimized for feature-based inference rather than raw waveform classification.

6. There are also classical ML artifacts under `models/`:
   - `random_forest.joblib`
   - `knn.joblib`
   - `label_encoder.joblib`
   These indicate a second branch of experimentation or fallback baselines, but the README makes clear the CNN is the main deployed model family.

7. Training and model exploration live in `notebook/`. `CNN_Model_1.ipynb` and `RF_KNN.ipynb` separate the deep learning pipeline from the baseline experiments, so the repo cleanly separates research notebooks from the runtime backend code.

8. The UI is not committed as source code here; only preview assets are present under `assets/ui/web/`. The README says the frontend is private, React-based, and communicates with the Flask backend. So for architecture diagrams, treat the frontend as an external client boundary rather than part of this repo’s source of truth.

9. `app.py` is the integration entry point and probably the only executable service in the repo. It likely owns request validation, file upload handling, orchestration of preprocessing and prediction, and response formatting. In architecture terms, this is the API gateway between user audio and the ML pipeline.

10. The data and model boundaries are important:
   - raw audio is ephemeral request data
   - extracted features are intermediate backend data
   - `.h5` and `.joblib` files are persisted model assets
   - `assets/ui/` contains static documentation/preview media, not application logic

11. The project is a research prototype rather than a production ML platform. There is no visible training service, feature store, database, message queue, or external inference service. That means the deployed architecture is intentionally simple: one Flask service plus local model files.

12. For a diagram, the most accurate high-level boxes are: client/frontend, Flask API, audio preprocessing/feature extraction, CNN inference model, and model artifact storage. A secondary, clearly separate box can represent notebook-based experimentation and baseline models, since those support research but are not part of the main request path.

Main entry points: [`voice_model.py`](https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/voice_model.py) (Voice model), [`app.py`](https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/app.py) (Flask API), [`README.md`](https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/README.md) (Project docs), [`voice_analysis.py`](https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/voice_analysis.py) (Audio analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_runtime["Production path"]
  node_n_client(("Frontend client<br/>external"))
  node_n_app["Flask API<br/>[app.py]"]
  node_n_analysis["Audio analysis<br/>processing<br/>[voice_analysis.py]"]
  node_n_model["Voice model<br/>inference<br/>[voice_model.py]"]
end

subgraph group_g_research["Research assets"]
  node_n_cnn_artifact[("CNN weights<br/>model artifact")]
  node_n_label_encoder[("Label encoder<br/>artifact")]
  node_n_rf[("Random forest<br/>baseline model")]
  node_n_knn[("KNN baseline<br/>baseline model<br/>[knn.joblib]")]
  node_n_cnn_nb["CNN notebook<br/>research notebook<br/>[CNN_Model_1.ipynb]"]
  node_n_baseline_nb["Baseline notebook<br/>research notebook<br/>[RF_KNN.ipynb]"]
  node_n_readme["Project docs<br/>documentation<br/>[README.md]"]
end

subgraph group_g_assets["Static previews"]
  node_n_ui_preview["UI preview<br/>static asset<br/>[web.txtt]"]
end

node_n_client -->|"upload audio"| node_n_app
node_n_app -->|"preprocess"| node_n_analysis
node_n_analysis -->|"feature tensor"| node_n_model
node_n_model -->|"load weights"| node_n_cnn_artifact
node_n_model -->|"decode class"| node_n_label_encoder
node_n_model -->|"prediction"| node_n_app
node_n_app -->|"json response"| node_n_client
node_n_cnn_nb -.->|"train/export"| node_n_cnn_artifact
node_n_baseline_nb -.->|"train/export"| node_n_rf
node_n_baseline_nb -.->|"train/export"| node_n_knn
node_n_readme -.->|"documents"| node_n_app
node_n_readme -.->|"documents"| node_n_analysis
node_n_readme -.->|"documents"| node_n_model
node_n_ui_preview -.->|"preview"| node_n_client

click node_n_app "https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/app.py"
click node_n_analysis "https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/voice_analysis.py"
click node_n_model "https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/voice_model.py"
click node_n_cnn_artifact "https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/saved_models/SceneFake_CNN_SMOTE.h5"
click node_n_label_encoder "https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/models/label_encoder.joblib"
click node_n_rf "https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/models/random_forest.joblib"
click node_n_knn "https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/models/knn.joblib"
click node_n_cnn_nb "https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/notebook/CNN_Model_1.ipynb"
click node_n_baseline_nb "https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/notebook/RF_KNN.ipynb"
click node_n_ui_preview "https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/assets/ui/web/web.txtt"
click node_n_readme "https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/README.md"

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_n_client,node_n_app,node_n_analysis,node_n_model toneBlue
class node_n_cnn_artifact,node_n_label_encoder,node_n_rf,node_n_knn,node_n_cnn_nb,node_n_baseline_nb,node_n_readme toneAmber
class node_n_ui_preview toneMint
```

## Components

### Production path

Request handling and inference flow for uploaded audio.

- **Frontend client**: external · Private React UI that uploads audio to the backend.
- [Flask API](https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/app.py): service · Main entry point; validates requests, handles uploads, and returns prediction responses. · `app.py`
- [Audio analysis](https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/voice_analysis.py): processing · Normalizes audio and extracts MFCC, spectrogram, pitch, and silence features. · `voice_analysis.py`
- [Voice model](https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/voice_model.py): inference · Loads the trained classifier and maps predictions to labels. · `voice_model.py`

### Research assets

Model experimentation, notebooks, and saved artifacts outside the main request path.

- [CNN weights](https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/saved_models/SceneFake_CNN_SMOTE.h5): model artifact · Primary trained CNN model file used for inference. · `saved_models/SceneFake_CNN_SMOTE.h5`
- [Label encoder](https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/models/label_encoder.joblib): artifact · Maps model outputs to human-readable classes. · `models/label_encoder.joblib`
- [Random forest](https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/models/random_forest.joblib): baseline model · Classical ML baseline stored as a joblib artifact. · `models/random_forest.joblib`
- [KNN baseline](https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/models/knn.joblib): baseline model · Nearest-neighbor baseline stored as a joblib artifact. · `models/knn.joblib`
- [CNN notebook](https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/notebook/CNN_Model_1.ipynb): research notebook · Training and exploration notebook for the deep learning pipeline. · `notebook/CNN_Model_1.ipynb`
- [Baseline notebook](https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/notebook/RF_KNN.ipynb): research notebook · Notebook for random forest and KNN experiments. · `notebook/RF_KNN.ipynb`
- [Project docs](https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/README.md): documentation · Explains the pipeline, model choices, and deployment shape. · `README.md`

### Static previews

Non-executable UI preview assets and documentation media.

- [UI preview](https://github.com/srujanrana07/fakeifi_deepfake_voice_detection_pipeline/blob/main/assets/ui/web/web.txtt): static asset · Committed frontend preview/documentation asset, not application code. · `assets/ui/web/web.txtt`

## Connections

- Frontend client → Flask API: upload audio · The frontend submits an audio file for detection.
- Flask API → Audio analysis: preprocess · API invokes the audio normalization and feature extraction pipeline.
- Audio analysis → Voice model: feature tensor · Extracted features are forwarded for inference.
- Voice model → CNN weights: load weights · Primary classifier parameters are read from the saved CNN artifact.
- Voice model → Label encoder: decode class · Numeric predictions are translated into Real/Fake labels.
- Voice model → Flask API: prediction · Inference result is returned to the API for response formatting.
- Flask API → Frontend client: json response · API returns predicted label and confidence to the caller.
- CNN notebook → CNN weights: train/export · Notebook represents the training path for the main model artifact.
- Baseline notebook → Random forest: train/export · Notebook represents the classical baseline experiments.
- Baseline notebook → KNN baseline: train/export · Notebook represents the classical baseline experiments.
- Project docs → Flask API: documents · Repository docs describe the Flask service and request flow.
- Project docs → Audio analysis: documents · Docs outline the audio normalization and feature extraction stages.
- Project docs → Voice model: documents · Docs describe the CNN inference layer and label decoding.
- UI preview → Frontend client: preview · Static UI asset reflects the external frontend boundary.
