# eschouten/ai-detector architecture

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

- Interactive diagram: https://gitdiagram.com/eschouten/ai-detector
- Repository: https://github.com/eschouten/ai-detector

## Overview

AI Detector watches camera and video-file sources, runs local YOLO object detection, optionally verifies detections with an AI prompt, then exports alerts and media. Its web frontend is described as supporting live-stream monitoring and review of past detections. The manager and webhook exporter excerpts support their specific runtime links; other stage connections reflect the README’s product description, while frontend-to-detector wiring is not established by the sampled source.

Main entry points: [`detector/src/aidetector/detection/detector.py`](https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/detection/detector.py) (Detection runtime), [`detector/src/aidetector/exporters/exporter.py`](https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/exporters/exporter.py) (Export dispatch), [`web/src/routes/(admin)`](https://github.com/eschouten/ai-detector/tree/main/web/src/routes/(admin)) (Admin interface), [`detector/src/aidetector/sources`](https://github.com/eschouten/ai-detector/tree/main/detector/src/aidetector/sources) (Source collector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Source collection"]
  node_manager["Service manager<br/>[manager.py]"]
  node_source_collector["Source collector"]
  node_streaming["Stream handling<br/>[streaming.py]"]
  node_video_media["Video processing<br/>[video.py]"]
end

subgraph group_detection["Detection and verification"]
  node_detector["Detection runtime<br/>[detector.py]"]
  node_yolo["YOLO inference<br/>[yolo.py]"]
  node_validator["AI verification<br/>[validator.py]"]
end

subgraph group_delivery["Alert delivery"]
  node_exporter["Export dispatch<br/>[exporter.py]"]
  node_disk["Disk exporter<br/>[disk.py]"]
  node_telegram["Telegram exporter<br/>[telegram.py]"]
  node_webhook["Webhook exporter<br/>[webhook.py]"]
end

subgraph group_web["Web monitoring"]
  node_web_app["Admin interface"]
  node_web_remote["Service remotes"]
  node_stream_preview["Live preview<br/>[+server.ts]"]
  node_detection_media["Detection media<br/>[+server.ts]"]
end

node_operator(("Operator"))
node_video_sources(("Cameras and files"))
node_model{{"YOLO model"}}
node_verification_service{{"AI service"}}
node_external_webhook{{"Webhook endpoint"}}
node_detection_files[("Saved detection files")]
node_ffmpeg{{"FFmpeg"}}

node_operator -->|"uses"| node_web_app
node_video_sources -->|"provides video"| node_source_collector
node_manager -->|"starts"| node_detector
node_source_collector -->|"handles streams"| node_streaming
node_detector -->|"runs inference"| node_yolo
node_yolo -->|"uses"| node_model
node_detector -.->|"optionally verifies"| node_validator
node_validator -.->|"asks prompt"| node_verification_service
node_detector -->|"exports detections"| node_exporter
node_exporter -->|"dispatches"| node_disk
node_exporter -->|"dispatches"| node_telegram
node_exporter -->|"dispatches"| node_webhook
node_webhook -->|"sends request"| node_external_webhook
node_web_app -->|"requests data"| node_web_remote
node_web_app -->|"requests preview"| node_stream_preview
node_stream_preview -->|"spawns"| node_ffmpeg
node_web_app -->|"requests media"| node_detection_media
node_detection_media -->|"reads files"| node_detection_files

click node_manager "https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/detection/manager.py"
click node_source_collector "https://github.com/eschouten/ai-detector/tree/main/detector/src/aidetector/sources"
click node_streaming "https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/sources/streaming.py"
click node_video_media "https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/media/video.py"
click node_detector "https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/detection/detector.py"
click node_yolo "https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/detection/yolo.py"
click node_validator "https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/detection/validator.py"
click node_exporter "https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/exporters/exporter.py"
click node_disk "https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/exporters/disk.py"
click node_telegram "https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/exporters/telegram.py"
click node_webhook "https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/exporters/webhook.py"
click node_web_app "https://github.com/eschouten/ai-detector/tree/main/web/src/routes/(admin)"
click node_web_remote "https://github.com/eschouten/ai-detector/tree/main/web/src/lib/remote"
click node_stream_preview "https://github.com/eschouten/ai-detector/blob/main/web/src/routes/(admin)/streams/%5Bsource%5D/%2Bserver.ts"
click node_detection_media "https://github.com/eschouten/ai-detector/blob/main/web/src/routes/(admin)/detections/%5Bcategory%5D/%5Bstage%5D/%5Btimestamp%5D/%5Bresource%5D/%2Bserver.ts"

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_manager,node_source_collector,node_streaming,node_video_media toneBlue
class node_detector,node_yolo,node_validator,node_detection_files toneAmber
class node_exporter,node_disk,node_telegram,node_webhook,node_external_webhook toneMint
class node_web_app,node_web_remote,node_stream_preview,node_detection_media toneRose
class node_operator,node_video_sources,node_model,node_verification_service,node_ffmpeg toneIndigo
```

## Components

### Source collection

- [Service manager](https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/detection/manager.py): `detector/src/aidetector/detection/manager.py`
- [Source collector](https://github.com/eschouten/ai-detector/tree/main/detector/src/aidetector/sources): `detector/src/aidetector/sources`
- [Stream handling](https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/sources/streaming.py): `detector/src/aidetector/sources/streaming.py`
- [Video processing](https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/media/video.py): `detector/src/aidetector/media/video.py`

### Detection and verification

- [Detection runtime](https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/detection/detector.py): `detector/src/aidetector/detection/detector.py`
- [YOLO inference](https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/detection/yolo.py): `detector/src/aidetector/detection/yolo.py`
- [AI verification](https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/detection/validator.py): `detector/src/aidetector/detection/validator.py`

### Alert delivery

- [Export dispatch](https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/exporters/exporter.py): `detector/src/aidetector/exporters/exporter.py`
- [Disk exporter](https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/exporters/disk.py): `detector/src/aidetector/exporters/disk.py`
- [Telegram exporter](https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/exporters/telegram.py): `detector/src/aidetector/exporters/telegram.py`
- [Webhook exporter](https://github.com/eschouten/ai-detector/blob/main/detector/src/aidetector/exporters/webhook.py): `detector/src/aidetector/exporters/webhook.py`

### Web monitoring

- [Admin interface](https://github.com/eschouten/ai-detector/tree/main/web/src/routes/(admin)): `web/src/routes/(admin)`
- [Service remotes](https://github.com/eschouten/ai-detector/tree/main/web/src/lib/remote): `web/src/lib/remote`
- [Live preview](https://github.com/eschouten/ai-detector/blob/main/web/src/routes/(admin)/streams/%5Bsource%5D/%2Bserver.ts): `web/src/routes/(admin)/streams/[source]/+server.ts`
- [Detection media](https://github.com/eschouten/ai-detector/blob/main/web/src/routes/(admin)/detections/%5Bcategory%5D/%5Bstage%5D/%5Btimestamp%5D/%5Bresource%5D/%2Bserver.ts): `web/src/routes/(admin)/detections/[category]/[stage]/[timestamp]/[resource]/+server.ts`

### Other components

- **Operator**
- **Cameras and files**
- **YOLO model**
- **AI service**
- **Webhook endpoint**
- **Saved detection files**
- **FFmpeg**

## Connections

- Operator → Admin interface: uses
- Cameras and files → Source collector: provides video
- Service manager → Detection runtime: starts
- Source collector → Stream handling: handles streams
- Detection runtime → YOLO inference: runs inference
- YOLO inference → YOLO model: uses
- Detection runtime → AI verification: optionally verifies
- AI verification → AI service: asks prompt
- Detection runtime → Export dispatch: exports detections
- Export dispatch → Disk exporter: dispatches
- Export dispatch → Telegram exporter: dispatches
- Export dispatch → Webhook exporter: dispatches
- Webhook exporter → Webhook endpoint: sends request
- Admin interface → Service remotes: requests data
- Admin interface → Live preview: requests preview
- Live preview → FFmpeg: spawns
- Admin interface → Detection media: requests media
- Detection media → Saved detection files: reads files