# kittulsalpha-ctrl/media-health-checker architecture

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

- Interactive diagram: https://gitdiagram.com/kittulsalpha-ctrl/media-health-checker
- Repository: https://github.com/kittulsalpha-ctrl/media-health-checker

## Overview

This is a media-operations application for validating uploaded or watched video, producing review artifacts, and presenting results in a dashboard. The principal web workflow runs from upload through media inspection, validation, frame and proxy generation, report storage, and dashboard display. A separate filesystem-watcher workflow processes files placed in a watch folder. The excerpts show both workflows, but do not establish that they share a processing pipeline; the web processing excerpt also omits some implementation details.

Main entry points: [`backend/watcher.py`](https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py) (Media handler), [`backend/app.py`](https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/app.py) (Flask application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web dashboard"]
  node_webapp["Flask application<br/>[app.py]"]
  node_upload["Media upload<br/>[app.py]"]
  node_dashboard["Dashboard view<br/>[app.py]"]
end

subgraph group_watch["Watched media"]
  node_watchfolder["Watch folder<br/>[watcher.py]"]
  node_observer["Folder observer<br/>[watcher.py]"]
  node_handler["Media handler<br/>[watcher.py]"]
end

subgraph group_processing["Media processing"]
  node_inspect["Metadata inspection<br/>[watcher.py]"]
  node_validate["Media validation<br/>[watcher.py]"]
  node_classify["Status classification<br/>[watcher.py]"]
  node_organize["Media sorting<br/>[watcher.py]"]
  node_frame["Frame extraction<br/>[watcher.py]"]
  node_proxy["Proxy generation<br/>[watcher.py]"]
  node_tagging["AI tags<br/>[watcher.py]"]
end

subgraph group_artifacts["Reports and artifacts"]
  node_reports["JSON reports<br/>[watcher.py]"]
  node_frames["Frame files<br/>[watcher.py]"]
  node_proxies["Proxy files<br/>[watcher.py]"]
end

node_browser(("Media operator"))
node_ffmpeg["FFmpeg tools"]

node_browser -->|"submits media"| node_upload
node_upload -->|"calls processing"| node_webapp
node_webapp -->|"probes media"| node_inspect
node_webapp -->|"checks media"| node_validate
node_webapp -->|"extracts frame"| node_frame
node_webapp -->|"creates proxy"| node_proxy
node_webapp -->|"generates tags"| node_tagging
node_webapp -->|"writes report"| node_reports
node_browser -->|"views results"| node_dashboard
node_dashboard -->|"reads reports"| node_reports
node_watchfolder -->|"monitors folder"| node_observer
node_observer -->|"dispatches event"| node_handler
node_handler -->|"probes media"| node_inspect
node_handler -->|"checks media"| node_validate
node_handler -->|"selects status"| node_classify
node_handler -->|"moves media"| node_organize
node_handler -->|"extracts frame"| node_frame
node_handler -->|"creates proxy"| node_proxy
node_handler -->|"generates tags"| node_tagging
node_handler -->|"writes report"| node_reports
node_handler -->|"writes frame"| node_frames
node_handler -->|"writes proxy"| node_proxies
node_inspect -->|"runs ffprobe"| node_ffmpeg
node_frame -->|"runs ffmpeg"| node_ffmpeg
node_proxy -->|"runs ffmpeg"| node_ffmpeg

click node_webapp "https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/app.py"
click node_upload "https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/app.py"
click node_dashboard "https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/app.py"
click node_watchfolder "https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py"
click node_observer "https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py"
click node_handler "https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py"
click node_inspect "https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py"
click node_validate "https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py"
click node_classify "https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py"
click node_organize "https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py"
click node_frame "https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py"
click node_proxy "https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py"
click node_tagging "https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py"
click node_reports "https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py"
click node_frames "https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py"
click node_proxies "https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.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_webapp,node_upload,node_dashboard toneBlue
class node_watchfolder,node_observer,node_handler toneAmber
class node_inspect,node_validate,node_classify,node_organize,node_frame,node_proxy,node_tagging toneMint
class node_reports,node_frames,node_proxies toneRose
class node_browser,node_ffmpeg toneIndigo
```

## Components

### Web dashboard

- [Flask application](https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/app.py): `backend/app.py`
- [Media upload](https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/app.py): `backend/app.py`
- [Dashboard view](https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/app.py): `backend/app.py`

### Watched media

- [Watch folder](https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py): `backend/watcher.py`
- [Folder observer](https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py): `backend/watcher.py`
- [Media handler](https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py): `backend/watcher.py`

### Media processing

- [Metadata inspection](https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py): `backend/watcher.py`
- [Media validation](https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py): `backend/watcher.py`
- [Status classification](https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py): `backend/watcher.py`
- [Media sorting](https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py): `backend/watcher.py`
- [Frame extraction](https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py): `backend/watcher.py`
- [Proxy generation](https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py): `backend/watcher.py`
- [AI tags](https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py): `backend/watcher.py`

### Reports and artifacts

- [JSON reports](https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py): `backend/watcher.py`
- [Frame files](https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py): `backend/watcher.py`
- [Proxy files](https://github.com/kittulsalpha-ctrl/media-health-checker/blob/main/backend/watcher.py): `backend/watcher.py`

### Other components

- **Media operator**
- **FFmpeg tools**

## Connections

- Media operator → Media upload: submits media (evidence: `backend/app.py`)
- Media upload → Flask application: calls processing (evidence: `backend/app.py`)
- Flask application → Metadata inspection: probes media (evidence: `backend/app.py`)
- Flask application → Media validation: checks media (evidence: `backend/app.py`)
- Flask application → Frame extraction: extracts frame (evidence: `backend/app.py`)
- Flask application → Proxy generation: creates proxy (evidence: `backend/app.py`)
- Flask application → AI tags: generates tags (evidence: `backend/app.py`)
- Flask application → JSON reports: writes report (evidence: `backend/app.py`)
- Media operator → Dashboard view: views results (evidence: `backend/app.py`)
- Dashboard view → JSON reports: reads reports (evidence: `backend/app.py`)
- Watch folder → Folder observer: monitors folder (evidence: `backend/watcher.py`)
- Folder observer → Media handler: dispatches event (evidence: `backend/watcher.py`)
- Media handler → Metadata inspection: probes media (evidence: `backend/watcher.py`)
- Media handler → Media validation: checks media (evidence: `backend/watcher.py`)
- Media handler → Status classification: selects status (evidence: `backend/watcher.py`)
- Media handler → Media sorting: moves media (evidence: `backend/watcher.py`)
- Media handler → Frame extraction: extracts frame (evidence: `backend/watcher.py`)
- Media handler → Proxy generation: creates proxy (evidence: `backend/watcher.py`)
- Media handler → AI tags: generates tags (evidence: `backend/watcher.py`)
- Media handler → JSON reports: writes report (evidence: `backend/watcher.py`)
- Media handler → Frame files: writes frame (evidence: `backend/watcher.py`)
- Media handler → Proxy files: writes proxy (evidence: `backend/watcher.py`)
- Metadata inspection → FFmpeg tools: runs ffprobe (evidence: `backend/watcher.py`)
- Frame extraction → FFmpeg tools: runs ffmpeg (evidence: `backend/watcher.py`)
- Proxy generation → FFmpeg tools: runs ffmpeg (evidence: `backend/watcher.py`)
