# aparnamol-ks/vidsafe architecture

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

- Interactive diagram: https://gitdiagram.com/aparnamol-ks/vidsafe
- Repository: https://github.com/aparnamol-ks/vidsafe

## Overview

VidSafe is a video moderation application: a user submits a video, the UI runs the pipeline, and the system returns a selectively moderated video plus policy evidence and a report. The pipeline coordinates separate audio and visual analysis, merges the censored audio with the blurred video, aligns detections, and evaluates fused events against policies. The README documents multimodal detection and policy-based reporting; source excerpts show the principal calls. Some UI and reasoning details are only partially sampled, so uncertain links are omitted.

Main entry points: [`modules/pipeline.py`](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/pipeline.py) (VidSafe pipeline), [`modules/audio/audio_pipeline.py`](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/audio/audio_pipeline.py) (Audio analysis pipeline), [`modules/video/video_pipeline.py`](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/video/video_pipeline.py) (Visual analysis pipeline), [`ui/app.py`](https://github.com/aparnamol-ks/vidsafe/blob/main/ui/app.py) (Streamlit interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_ui["Streamlit interface<br/>[app.py]"]
  node_pdf["PDF report export<br/>[pdf_utils.py]"]
  node_reducer["Report summarizer<br/>[policy_reducer.py]"]
end

subgraph group_orchestration["Moderation workflow"]
  node_entry["Application entry<br/>[main.py]"]
  node_pipeline["VidSafe pipeline<br/>[pipeline.py]"]
  node_fusion["Multimodal alignment<br/>[aligner.py]"]
  node_merger["Audio-video merge<br/>[merger.py]"]
  node_converter["Web video conversion"]
  node_config["Runtime thresholds<br/>[config.py]"]
end

subgraph group_video["Visual moderation"]
  node_video_pipeline["Visual analysis pipeline<br/>[video_pipeline.py]"]
  node_clip["Semantic frame filter<br/>[clip_filter.py]"]
  node_detector["RT-DETR detector<br/>[rtdetr_detector.py]"]
  node_blur["Region blurring<br/>[blur.py]"]
  node_temporal["Temporal consistency<br/>[temporal_filter.py]"]
  node_segments["Detection segments<br/>[segment_builder.py]"]
end

subgraph group_audio["Audio moderation"]
  node_audio_pipeline["Audio analysis pipeline<br/>[audio_pipeline.py]"]
  node_extractor["Audio extraction<br/>[extractor.py]"]
  node_transcriber["Speech transcription<br/>[transcriber.py]"]
  node_roberta["Word toxicity detection"]
  node_detoxify["Sentence toxicity detection"]
  node_censor["Audio censoring<br/>[censor.py]"]
end

subgraph group_reasoning["Policy reasoning"]
  node_rag["Policy reasoning<br/>[rag_engine.py]"]
  node_policies["Moderation policies"]
end

node_user(("Video submitter"))

node_user -->|"submits video"| node_ui
node_ui -->|"runs analysis"| node_pipeline
node_entry -->|"invokes"| node_pipeline
node_pipeline -->|"runs audio analysis"| node_audio_pipeline
node_pipeline -->|"runs visual analysis"| node_video_pipeline
node_pipeline -->|"merges moderated media"| node_merger
node_pipeline -->|"converts output"| node_converter
node_pipeline -->|"aligns detections"| node_fusion
node_pipeline -->|"evaluates evidence"| node_rag
node_video_pipeline -->|"filters frames"| node_clip
node_video_pipeline -->|"detects regions"| node_detector
node_video_pipeline -->|"filters detections"| node_temporal
node_video_pipeline -->|"builds segments"| node_segments
node_detector -->|"blurs regions"| node_blur
node_video_pipeline -->|"reads threshold"| node_config
node_audio_pipeline -->|"extracts audio"| node_extractor
node_audio_pipeline -->|"transcribes speech"| node_transcriber
node_audio_pipeline -->|"scores toxic words"| node_roberta
node_audio_pipeline -->|"scores sentences"| node_detoxify
node_audio_pipeline -->|"censors toxic spans"| node_censor
node_transcriber -->|"uses audio utilities"| node_extractor
node_audio_pipeline -->|"reads censor settings"| node_config
node_rag -->|"loads policy data"| node_policies
node_ui -->|"generates PDF"| node_pdf
node_ui -->|"uses report summarizer"| node_reducer
node_reducer -.->|"requests report generation"| node_user

click node_ui "https://github.com/aparnamol-ks/vidsafe/blob/main/ui/app.py"
click node_pdf "https://github.com/aparnamol-ks/vidsafe/blob/main/ui/pdf_utils.py"
click node_reducer "https://github.com/aparnamol-ks/vidsafe/blob/main/ui/policy_reducer.py"
click node_entry "https://github.com/aparnamol-ks/vidsafe/blob/main/main.py"
click node_pipeline "https://github.com/aparnamol-ks/vidsafe/blob/main/modules/pipeline.py"
click node_fusion "https://github.com/aparnamol-ks/vidsafe/blob/main/modules/fusion/aligner.py"
click node_merger "https://github.com/aparnamol-ks/vidsafe/blob/main/modules/audio/merger.py"
click node_converter "https://github.com/aparnamol-ks/vidsafe/blob/main/modules/video/format_converter.py"
click node_video_pipeline "https://github.com/aparnamol-ks/vidsafe/blob/main/modules/video/video_pipeline.py"
click node_clip "https://github.com/aparnamol-ks/vidsafe/blob/main/modules/video/clip_filter.py"
click node_detector "https://github.com/aparnamol-ks/vidsafe/blob/main/modules/video/rtdetr_detector.py"
click node_blur "https://github.com/aparnamol-ks/vidsafe/blob/main/modules/video/blur.py"
click node_temporal "https://github.com/aparnamol-ks/vidsafe/blob/main/modules/video/temporal_filter.py"
click node_segments "https://github.com/aparnamol-ks/vidsafe/blob/main/modules/video/segment_builder.py"
click node_audio_pipeline "https://github.com/aparnamol-ks/vidsafe/blob/main/modules/audio/audio_pipeline.py"
click node_extractor "https://github.com/aparnamol-ks/vidsafe/blob/main/modules/audio/extractor.py"
click node_transcriber "https://github.com/aparnamol-ks/vidsafe/blob/main/modules/audio/transcriber.py"
click node_roberta "https://github.com/aparnamol-ks/vidsafe/blob/main/modules/audio/roberta_detector.py"
click node_detoxify "https://github.com/aparnamol-ks/vidsafe/blob/main/modules/audio/detoxify_detector.py"
click node_censor "https://github.com/aparnamol-ks/vidsafe/blob/main/modules/audio/censor.py"
click node_rag "https://github.com/aparnamol-ks/vidsafe/blob/main/modules/reasoning/rag_engine.py"
click node_policies "https://github.com/aparnamol-ks/vidsafe/blob/main/modules/reasoning/policies/youtube_multimodal_policies.json"
click node_config "https://github.com/aparnamol-ks/vidsafe/blob/main/config.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_ui,node_pdf,node_reducer toneBlue
class node_entry,node_pipeline,node_fusion,node_merger,node_converter,node_config toneAmber
class node_video_pipeline,node_clip,node_detector,node_blur,node_temporal,node_segments toneMint
class node_audio_pipeline,node_extractor,node_transcriber,node_roberta,node_detoxify,node_censor toneRose
class node_rag,node_policies,node_user toneIndigo
```

## Components

### User interface

- [Streamlit interface](https://github.com/aparnamol-ks/vidsafe/blob/main/ui/app.py): `ui/app.py`
- [PDF report export](https://github.com/aparnamol-ks/vidsafe/blob/main/ui/pdf_utils.py): `ui/pdf_utils.py`
- [Report summarizer](https://github.com/aparnamol-ks/vidsafe/blob/main/ui/policy_reducer.py): `ui/policy_reducer.py`

### Moderation workflow

- [Application entry](https://github.com/aparnamol-ks/vidsafe/blob/main/main.py): `main.py`
- [VidSafe pipeline](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/pipeline.py): `modules/pipeline.py`
- [Multimodal alignment](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/fusion/aligner.py): `modules/fusion/aligner.py`
- [Audio-video merge](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/audio/merger.py): `modules/audio/merger.py`
- [Web video conversion](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/video/format_converter.py): `modules/video/format_converter.py`
- [Runtime thresholds](https://github.com/aparnamol-ks/vidsafe/blob/main/config.py): `config.py`

### Visual moderation

- [Visual analysis pipeline](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/video/video_pipeline.py): `modules/video/video_pipeline.py`
- [Semantic frame filter](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/video/clip_filter.py): `modules/video/clip_filter.py`
- [RT-DETR detector](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/video/rtdetr_detector.py): `modules/video/rtdetr_detector.py`
- [Region blurring](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/video/blur.py): `modules/video/blur.py`
- [Temporal consistency](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/video/temporal_filter.py): `modules/video/temporal_filter.py`
- [Detection segments](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/video/segment_builder.py): `modules/video/segment_builder.py`

### Audio moderation

- [Audio analysis pipeline](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/audio/audio_pipeline.py): `modules/audio/audio_pipeline.py`
- [Audio extraction](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/audio/extractor.py): `modules/audio/extractor.py`
- [Speech transcription](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/audio/transcriber.py): `modules/audio/transcriber.py`
- [Word toxicity detection](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/audio/roberta_detector.py): `modules/audio/roberta_detector.py`
- [Sentence toxicity detection](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/audio/detoxify_detector.py): `modules/audio/detoxify_detector.py`
- [Audio censoring](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/audio/censor.py): `modules/audio/censor.py`

### Policy reasoning

- [Policy reasoning](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/reasoning/rag_engine.py): `modules/reasoning/rag_engine.py`
- [Moderation policies](https://github.com/aparnamol-ks/vidsafe/blob/main/modules/reasoning/policies/youtube_multimodal_policies.json): `modules/reasoning/policies/youtube_multimodal_policies.json`

### Other components

- **Video submitter**

## Connections

- Video submitter → Streamlit interface: submits video (evidence: `README.md`)
- Streamlit interface → VidSafe pipeline: runs analysis (evidence: `ui/app.py`)
- Application entry → VidSafe pipeline: invokes (evidence: `main.py`)
- VidSafe pipeline → Audio analysis pipeline: runs audio analysis (evidence: `modules/pipeline.py`)
- VidSafe pipeline → Visual analysis pipeline: runs visual analysis (evidence: `modules/pipeline.py`)
- VidSafe pipeline → Audio-video merge: merges moderated media (evidence: `modules/pipeline.py`)
- VidSafe pipeline → Web video conversion: converts output (evidence: `modules/pipeline.py`)
- VidSafe pipeline → Multimodal alignment: aligns detections (evidence: `modules/pipeline.py`)
- VidSafe pipeline → Policy reasoning: evaluates evidence (evidence: `modules/pipeline.py`)
- Visual analysis pipeline → Semantic frame filter: filters frames (evidence: `modules/video/video_pipeline.py`)
- Visual analysis pipeline → RT-DETR detector: detects regions (evidence: `modules/video/video_pipeline.py`)
- Visual analysis pipeline → Temporal consistency: filters detections (evidence: `modules/video/video_pipeline.py`)
- Visual analysis pipeline → Detection segments: builds segments (evidence: `modules/video/video_pipeline.py`)
- RT-DETR detector → Region blurring: blurs regions (evidence: `modules/video/rtdetr_detector.py`)
- Visual analysis pipeline → Runtime thresholds: reads threshold (evidence: `modules/video/video_pipeline.py`)
- Audio analysis pipeline → Audio extraction: extracts audio (evidence: `modules/audio/audio_pipeline.py`)
- Audio analysis pipeline → Speech transcription: transcribes speech (evidence: `modules/audio/audio_pipeline.py`)
- Audio analysis pipeline → Word toxicity detection: scores toxic words (evidence: `modules/audio/audio_pipeline.py`)
- Audio analysis pipeline → Sentence toxicity detection: scores sentences (evidence: `modules/audio/audio_pipeline.py`)
- Audio analysis pipeline → Audio censoring: censors toxic spans (evidence: `modules/audio/audio_pipeline.py`)
- Speech transcription → Audio extraction: uses audio utilities (evidence: `modules/audio/transcriber.py`)
- Audio analysis pipeline → Runtime thresholds: reads censor settings (evidence: `modules/audio/audio_pipeline.py`)
- Policy reasoning → Moderation policies: loads policy data (evidence: `modules/reasoning/rag_engine.py`)
- Streamlit interface → PDF report export: generates PDF (evidence: `ui/app.py`)
- Streamlit interface → Report summarizer: uses report summarizer (evidence: `ui/app.py`)
- Report summarizer → Video submitter: requests report generation
