# malevolent-shrine-hq/vocalguard architecture

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

- Interactive diagram: https://gitdiagram.com/malevolent-shrine-hq/vocalguard
- Repository: https://github.com/malevolent-shrine-hq/vocalguard

## Overview

VocalGuard is a web console and FastAPI service for detecting synthetic speech and checking speaker identity. Analysts upload recordings or stream microphone audio; the service preprocesses audio, runs deepfake inference, and returns threat assessments, while live sessions also support voiceprint verification and temporal risk scoring. The console also supports authenticated voiceprint enrollment and demo samples. Backend module relationships are supported by the excerpts and SOURCE INDEX; frontend-to-service interaction is documented at a high level in the README, but its specific request wiring was not sampled.

Main entry points: [`api/index.py`](https://github.com/malevolent-shrine-hq/vocalguard/blob/main/api/index.py) (REST and Stream API), [`api/streaming_detector.py`](https://github.com/malevolent-shrine-hq/vocalguard/blob/main/api/streaming_detector.py) (Streaming Sessions), [`src/App.jsx`](https://github.com/malevolent-shrine-hq/vocalguard/blob/main/src/App.jsx) (Operations Console), [`api/detector.py`](https://github.com/malevolent-shrine-hq/vocalguard/blob/main/api/detector.py) (Audio Preprocessing and Inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Analyst Console"]
  node_console["Operations Console<br/>[App.jsx]"]
  node_frontend_auth["Sign-in UI<br/>[main.jsx]"]
end

subgraph group_service["Detection Service"]
  node_api["REST and Stream API<br/>[index.py]"]
  node_auth["Session Verification<br/>[auth.py]"]
  node_samples["Demo Samples<br/>[index.py]"]
end

subgraph group_analysis["Audio Analysis"]
  node_stream["Streaming Sessions"]
  node_detector["Audio Preprocessing and Inference<br/>[detector.py]"]
  node_weights["Detector Weights"]
end

subgraph group_identity["Identity Verification"]
  node_biometrics["Voiceprint Engine"]
  node_vault[("Enrolled Voiceprints")]
end

node_analyst(("Analyst"))
node_clerk["Clerk Identity Service"]
node_sample_audio["Demo Audio Files"]

node_analyst -->|"uses"| node_console
node_console -->|"submits audio"| node_api
node_frontend_auth -->|"provides sign-in"| node_console
node_frontend_auth -->|"configures provider"| node_clerk
node_api -->|"checks sessions"| node_auth
node_auth -->|"verifies tokens"| node_clerk
node_api -->|"runs detection"| node_detector
node_api -->|"creates sessions"| node_stream
node_api -->|"manages profiles"| node_biometrics
node_api -->|"serves samples"| node_sample_audio
node_stream -->|"analyzes windows"| node_detector
node_stream -->|"checks identity"| node_biometrics
node_detector -->|"loads checkpoint"| node_weights
node_biometrics -->|"loads and saves"| node_vault
node_samples -->|"reads files"| node_sample_audio

click node_console "https://github.com/malevolent-shrine-hq/vocalguard/blob/main/src/App.jsx"
click node_frontend_auth "https://github.com/malevolent-shrine-hq/vocalguard/blob/main/src/main.jsx"
click node_api "https://github.com/malevolent-shrine-hq/vocalguard/blob/main/api/index.py"
click node_auth "https://github.com/malevolent-shrine-hq/vocalguard/blob/main/api/auth.py"
click node_samples "https://github.com/malevolent-shrine-hq/vocalguard/blob/main/api/index.py"
click node_stream "https://github.com/malevolent-shrine-hq/vocalguard/blob/main/api/streaming_detector.py"
click node_detector "https://github.com/malevolent-shrine-hq/vocalguard/blob/main/api/detector.py"
click node_weights "https://github.com/malevolent-shrine-hq/vocalguard/blob/main/model/voice_deepfake_detector.pth"
click node_biometrics "https://github.com/malevolent-shrine-hq/vocalguard/blob/main/api/speaker_biometrics.py"
click node_vault "https://github.com/malevolent-shrine-hq/vocalguard/blob/main/model/enrolled_voiceprints.json"
click node_sample_audio "https://github.com/malevolent-shrine-hq/vocalguard/tree/main/public/samples"

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_console,node_frontend_auth toneBlue
class node_api,node_auth,node_samples toneAmber
class node_stream,node_detector,node_weights toneMint
class node_biometrics,node_vault toneRose
class node_analyst,node_clerk toneIndigo
class node_sample_audio toneTeal
```

## Components

### Analyst Console

- [Operations Console](https://github.com/malevolent-shrine-hq/vocalguard/blob/main/src/App.jsx): `src/App.jsx`
- [Sign-in UI](https://github.com/malevolent-shrine-hq/vocalguard/blob/main/src/main.jsx): `src/main.jsx`

### Detection Service

- [REST and Stream API](https://github.com/malevolent-shrine-hq/vocalguard/blob/main/api/index.py): `api/index.py`
- [Session Verification](https://github.com/malevolent-shrine-hq/vocalguard/blob/main/api/auth.py): `api/auth.py`
- [Demo Samples](https://github.com/malevolent-shrine-hq/vocalguard/blob/main/api/index.py): `api/index.py`

### Audio Analysis

- [Streaming Sessions](https://github.com/malevolent-shrine-hq/vocalguard/blob/main/api/streaming_detector.py): `api/streaming_detector.py`
- [Audio Preprocessing and Inference](https://github.com/malevolent-shrine-hq/vocalguard/blob/main/api/detector.py): `api/detector.py`
- [Detector Weights](https://github.com/malevolent-shrine-hq/vocalguard/blob/main/model/voice_deepfake_detector.pth): `model/voice_deepfake_detector.pth`

### Identity Verification

- [Voiceprint Engine](https://github.com/malevolent-shrine-hq/vocalguard/blob/main/api/speaker_biometrics.py): `api/speaker_biometrics.py`
- [Enrolled Voiceprints](https://github.com/malevolent-shrine-hq/vocalguard/blob/main/model/enrolled_voiceprints.json): `model/enrolled_voiceprints.json`

### Other components

- **Analyst**
- **Clerk Identity Service**
- [Demo Audio Files](https://github.com/malevolent-shrine-hq/vocalguard/tree/main/public/samples): `public/samples`

## Connections

- Analyst → Operations Console: uses (evidence: `README.md`)
- Operations Console → REST and Stream API: submits audio (evidence: `README.md`)
- Sign-in UI → Operations Console: provides sign-in (evidence: `src/main.jsx`)
- Sign-in UI → Clerk Identity Service: configures provider (evidence: `src/main.jsx`)
- REST and Stream API → Session Verification: checks sessions (evidence: `api/index.py`)
- Session Verification → Clerk Identity Service: verifies tokens (evidence: `api/auth.py`)
- REST and Stream API → Audio Preprocessing and Inference: runs detection (evidence: `api/index.py`)
- REST and Stream API → Streaming Sessions: creates sessions (evidence: `api/index.py`)
- REST and Stream API → Voiceprint Engine: manages profiles (evidence: `api/index.py`)
- REST and Stream API → Demo Audio Files: serves samples (evidence: `api/index.py`)
- Streaming Sessions → Audio Preprocessing and Inference: analyzes windows (evidence: `api/streaming_detector.py`)
- Streaming Sessions → Voiceprint Engine: checks identity (evidence: `api/streaming_detector.py`)
- Audio Preprocessing and Inference → Detector Weights: loads checkpoint (evidence: `api/detector.py`)
- Voiceprint Engine → Enrolled Voiceprints: loads and saves (evidence: `api/speaker_biometrics.py`)
- Demo Samples → Demo Audio Files: reads files (evidence: `api/index.py`)