# adityaraj-r/echo-guard architecture

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

- Interactive diagram: https://gitdiagram.com/adityaraj-r/echo-guard
- Repository: https://github.com/adityaraj-r/echo-guard

## Overview

EchoGuard is a forensic audio platform for identifying synthetic or deepfake voice clips. Its primary workflow is dashboard upload or microphone capture, API analysis, audio normalization and visual feature generation, model inference, then a verdict with confidence, metadata and forensic visuals; detections can also be retained for history. The README also describes an asynchronous job-based gateway and worker architecture. The graph includes that distinct capability, but its runtime links to the main analysis pipeline are not established by the excerpts. Some frontend and service details are documented rather than sampled.

Main entry points: [`backend/preprocessing/audio_pipeline.py`](https://github.com/adityaraj-r/echo-guard/blob/main/backend/preprocessing/audio_pipeline.py) (Audio pipeline), [`services/gateway/main.py`](https://github.com/adityaraj-r/echo-guard/blob/main/services/gateway/main.py) (Job gateway), [`frontend/src/pages/DashboardPage.jsx`](https://github.com/adityaraj-r/echo-guard/blob/main/frontend/src/pages/DashboardPage.jsx) (React dashboard), [`backend/api/routes.py`](https://github.com/adityaraj-r/echo-guard/blob/main/backend/api/routes.py) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_dashboard["React dashboard<br/>[DashboardPage.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_capture["Microphone capture<br/>[useRecorder.js]"]
end

subgraph group_api["Analysis API"]
  node_api_routes["API routes<br/>[routes.py]"]
  node_detection_service["Detection orchestration"]
  node_detection_repo["Detection history"]
  node_mongo[("MongoDB<br/>[mongodb.py]")]
end

subgraph group_audio["Audio processing"]
  node_pipeline["Audio pipeline<br/>[audio_pipeline.py]"]
  node_conversion["Audio conversion"]
  node_audio_io["Audio loading<br/>[audio_io.py]"]
  node_visuals["Forensic visuals<br/>[spectrogram.py]"]
  node_waveform["Waveform rendering<br/>[waveform.py]"]
end

subgraph group_ml["Detection model"]
  node_inference["Model inference<br/>[model_inference.py]"]
  node_model["CNN architecture"]
  node_features["Forensic features<br/>[features.py]"]
end

subgraph group_async["Async jobs"]
  node_gateway["Job gateway<br/>[main.py]"]
  node_job_store["Job repository<br/>[repository.py]"]
  node_job_db[("Job database<br/>[db.py]")]
  node_redis["Redis job stream"]
  node_worker["Job worker<br/>[consumer.py]"]
  node_worker_audio["Worker audio processing"]
  node_model_service["Model service<br/>[main.py]"]
end

node_user(("Analyst"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"records audio"| node_capture
node_dashboard -->|"requests analysis"| node_api_client
node_api_client -->|"calls API"| node_api_routes
node_api_routes -->|"analyzes audio"| node_detection_service
node_api_routes -->|"stores and lists"| node_detection_repo
node_detection_service -->|"processes audio"| node_pipeline
node_detection_service -->|"classifies audio"| node_inference
node_pipeline -->|"converts audio"| node_conversion
node_pipeline -->|"generates spectrogram"| node_visuals
node_pipeline -->|"generates waveform"| node_waveform
node_visuals -->|"loads audio"| node_audio_io
node_waveform -->|"loads audio"| node_audio_io
node_inference -->|"runs CNN"| node_model
node_inference -->|"uses feature report"| node_features
node_detection_repo -.->|"persists detections"| node_mongo
node_gateway -->|"records jobs"| node_job_store
node_gateway -->|"queues jobs"| node_redis
node_job_store -->|"stores job state"| node_job_db
node_worker -->|"processes audio"| node_worker_audio
node_gateway -.->|"dispatches jobs"| node_worker
node_worker -.->|"requests inference"| node_model_service

click node_dashboard "https://github.com/adityaraj-r/echo-guard/blob/main/frontend/src/pages/DashboardPage.jsx"
click node_api_client "https://github.com/adityaraj-r/echo-guard/blob/main/frontend/src/services/api.js"
click node_capture "https://github.com/adityaraj-r/echo-guard/blob/main/frontend/src/hooks/useRecorder.js"
click node_api_routes "https://github.com/adityaraj-r/echo-guard/blob/main/backend/api/routes.py"
click node_detection_service "https://github.com/adityaraj-r/echo-guard/blob/main/backend/services/detection_service.py"
click node_detection_repo "https://github.com/adityaraj-r/echo-guard/blob/main/backend/services/detection_repository.py"
click node_mongo "https://github.com/adityaraj-r/echo-guard/blob/main/backend/database/mongodb.py"
click node_pipeline "https://github.com/adityaraj-r/echo-guard/blob/main/backend/preprocessing/audio_pipeline.py"
click node_conversion "https://github.com/adityaraj-r/echo-guard/blob/main/backend/utils/audio_conversion.py"
click node_audio_io "https://github.com/adityaraj-r/echo-guard/blob/main/backend/preprocessing/audio_io.py"
click node_visuals "https://github.com/adityaraj-r/echo-guard/blob/main/backend/visualization/spectrogram.py"
click node_waveform "https://github.com/adityaraj-r/echo-guard/blob/main/backend/visualization/waveform.py"
click node_inference "https://github.com/adityaraj-r/echo-guard/blob/main/backend/ml/model_inference.py"
click node_model "https://github.com/adityaraj-r/echo-guard/blob/main/backend/ml/model_definition.py"
click node_features "https://github.com/adityaraj-r/echo-guard/blob/main/backend/ml/features.py"
click node_gateway "https://github.com/adityaraj-r/echo-guard/blob/main/services/gateway/main.py"
click node_job_store "https://github.com/adityaraj-r/echo-guard/blob/main/services/shared/repository.py"
click node_job_db "https://github.com/adityaraj-r/echo-guard/blob/main/services/shared/db.py"
click node_worker "https://github.com/adityaraj-r/echo-guard/blob/main/services/worker/consumer.py"
click node_worker_audio "https://github.com/adityaraj-r/echo-guard/blob/main/services/worker/audio_processing.py"
click node_model_service "https://github.com/adityaraj-r/echo-guard/blob/main/services/model_service/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_dashboard,node_api_client,node_capture toneBlue
class node_api_routes,node_detection_service,node_detection_repo,node_mongo toneAmber
class node_pipeline,node_conversion,node_audio_io,node_visuals,node_waveform toneMint
class node_inference,node_model,node_features toneRose
class node_gateway,node_job_store,node_job_db,node_redis,node_worker,node_worker_audio,node_model_service,node_user toneIndigo
```

## Components

### Dashboard

- [React dashboard](https://github.com/adityaraj-r/echo-guard/blob/main/frontend/src/pages/DashboardPage.jsx): `frontend/src/pages/DashboardPage.jsx`
- [API client](https://github.com/adityaraj-r/echo-guard/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Microphone capture](https://github.com/adityaraj-r/echo-guard/blob/main/frontend/src/hooks/useRecorder.js): `frontend/src/hooks/useRecorder.js`

### Analysis API

- [API routes](https://github.com/adityaraj-r/echo-guard/blob/main/backend/api/routes.py): `backend/api/routes.py`
- [Detection orchestration](https://github.com/adityaraj-r/echo-guard/blob/main/backend/services/detection_service.py): `backend/services/detection_service.py`
- [Detection history](https://github.com/adityaraj-r/echo-guard/blob/main/backend/services/detection_repository.py): `backend/services/detection_repository.py`
- [MongoDB](https://github.com/adityaraj-r/echo-guard/blob/main/backend/database/mongodb.py): `backend/database/mongodb.py`

### Audio processing

- [Audio pipeline](https://github.com/adityaraj-r/echo-guard/blob/main/backend/preprocessing/audio_pipeline.py): `backend/preprocessing/audio_pipeline.py`
- [Audio conversion](https://github.com/adityaraj-r/echo-guard/blob/main/backend/utils/audio_conversion.py): `backend/utils/audio_conversion.py`
- [Audio loading](https://github.com/adityaraj-r/echo-guard/blob/main/backend/preprocessing/audio_io.py): `backend/preprocessing/audio_io.py`
- [Forensic visuals](https://github.com/adityaraj-r/echo-guard/blob/main/backend/visualization/spectrogram.py): `backend/visualization/spectrogram.py`
- [Waveform rendering](https://github.com/adityaraj-r/echo-guard/blob/main/backend/visualization/waveform.py): `backend/visualization/waveform.py`

### Detection model

- [Model inference](https://github.com/adityaraj-r/echo-guard/blob/main/backend/ml/model_inference.py): `backend/ml/model_inference.py`
- [CNN architecture](https://github.com/adityaraj-r/echo-guard/blob/main/backend/ml/model_definition.py): `backend/ml/model_definition.py`
- [Forensic features](https://github.com/adityaraj-r/echo-guard/blob/main/backend/ml/features.py): `backend/ml/features.py`

### Async jobs

- [Job gateway](https://github.com/adityaraj-r/echo-guard/blob/main/services/gateway/main.py): `services/gateway/main.py`
- [Job repository](https://github.com/adityaraj-r/echo-guard/blob/main/services/shared/repository.py): `services/shared/repository.py`
- [Job database](https://github.com/adityaraj-r/echo-guard/blob/main/services/shared/db.py): `services/shared/db.py`
- **Redis job stream**
- [Job worker](https://github.com/adityaraj-r/echo-guard/blob/main/services/worker/consumer.py): `services/worker/consumer.py`
- [Worker audio processing](https://github.com/adityaraj-r/echo-guard/blob/main/services/worker/audio_processing.py): `services/worker/audio_processing.py`
- [Model service](https://github.com/adityaraj-r/echo-guard/blob/main/services/model_service/main.py): `services/model_service/main.py`

### Other components

- **Analyst**

## Connections

- Analyst → React dashboard: uses
- React dashboard → Microphone capture: records audio
- React dashboard → API client: requests analysis
- API client → API routes: calls API
- API routes → Detection orchestration: analyzes audio (evidence: `backend/api/routes.py`)
- API routes → Detection history: stores and lists (evidence: `backend/api/routes.py`)
- Detection orchestration → Audio pipeline: processes audio (evidence: `backend/services/detection_service.py`)
- Detection orchestration → Model inference: classifies audio (evidence: `backend/services/detection_service.py`)
- Audio pipeline → Audio conversion: converts audio (evidence: `backend/preprocessing/audio_pipeline.py`)
- Audio pipeline → Forensic visuals: generates spectrogram (evidence: `backend/preprocessing/audio_pipeline.py`)
- Audio pipeline → Waveform rendering: generates waveform (evidence: `backend/preprocessing/audio_pipeline.py`)
- Forensic visuals → Audio loading: loads audio (evidence: `backend/visualization/spectrogram.py`)
- Waveform rendering → Audio loading: loads audio (evidence: `backend/visualization/waveform.py`)
- Model inference → CNN architecture: runs CNN (evidence: `backend/ml/model_inference.py`)
- Model inference → Forensic features: uses feature report (evidence: `backend/ml/model_inference.py`)
- Detection history → MongoDB: persists detections (evidence: `backend/services/detection_repository.py`)
- Job gateway → Job repository: records jobs (evidence: `services/gateway/main.py`)
- Job gateway → Redis job stream: queues jobs (evidence: `services/gateway/main.py`)
- Job repository → Job database: stores job state (evidence: `services/shared/repository.py`)
- Job worker → Worker audio processing: processes audio (evidence: `services/worker/consumer.py`)
- Job gateway → Job worker: dispatches jobs
- Job worker → Model service: requests inference