# joireve/passerby architecture

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

- Interactive diagram: https://gitdiagram.com/joireve/passerby
- Repository: https://github.com/joireve/passerby

## Overview

Passerby is a C++ pedestrian-detection application for images and video. Its main workflow parses CLI options, selects and opens a source reader, reads frames, runs YOLOv8 inference and postprocessing, then writes per-frame CSV and optionally displays annotated frames. The graph also preserves engine selection, timing, and allocation statistics. Some implementation details are unsampled; documented capabilities are shown where supported, and uncertain links are omitted.

Main entry points: [`src/main.cpp`](https://github.com/joireve/passerby/blob/main/src/main.cpp) (Application loop), [`src/PedestrianDetector.cpp`](https://github.com/joireve/passerby/blob/main/src/PedestrianDetector.cpp) (Pedestrian detector), [`src/FrameReaderFactory.cpp`](https://github.com/joireve/passerby/blob/main/src/FrameReaderFactory.cpp) (Reader factory), [`models/yolov8n.onnx`](https://github.com/joireve/passerby/blob/main/models/yolov8n.onnx) (ONNX model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime orchestration"]
  node_app["Application loop<br/>[main.cpp]"]
  node_csv["CSV output<br/>[main.cpp]"]
  node_display["Window display<br/>[main.cpp]"]
end

subgraph group_input["Frame input"]
  node_factory["Reader factory"]
  node_image["Image reader"]
  node_video["Video reader"]
end

subgraph group_detection["Detection pipeline"]
  node_model["ONNX model<br/>[yolov8n.onnx]"]
  node_detector["Pedestrian detector"]
  node_engine["DNN engine selection<br/>[DnnEngine.hpp]"]
  node_preprocess["LetterBox and blob"]
  node_forward["DNN forward"]
  node_decode["Decode and NMS"]
end

subgraph group_observability["Runtime observability"]
  node_timing["Stage timing"]
  node_allocator["Allocation statistics"]
end

node_user(("CLI user"))
node_opencv["OpenCV DNN"]

node_user -->|"provides options"| node_app
node_app -->|"creates reader"| node_factory
node_factory -->|"dispatches images"| node_image
node_factory -->|"dispatches videos"| node_video
node_app -->|"runs detection"| node_detector
node_app -->|"writes detections"| node_csv
node_app -->|"displays frames"| node_display
node_model -->|"loaded by"| node_detector
node_detector -->|"selects engine"| node_engine
node_detector -->|"preprocesses frames"| node_preprocess
node_detector -->|"runs inference"| node_forward
node_detector -->|"postprocesses output"| node_decode
node_forward -->|"calls DNN"| node_opencv
node_app -->|"records stages"| node_timing
node_app -->|"counts allocations"| node_allocator

click node_app "https://github.com/joireve/passerby/blob/main/src/main.cpp"
click node_csv "https://github.com/joireve/passerby/blob/main/src/main.cpp"
click node_display "https://github.com/joireve/passerby/blob/main/src/main.cpp"
click node_factory "https://github.com/joireve/passerby/blob/main/src/FrameReaderFactory.cpp"
click node_image "https://github.com/joireve/passerby/blob/main/src/ImageFrameReader.cpp"
click node_video "https://github.com/joireve/passerby/blob/main/src/VideoFrameReader.cpp"
click node_model "https://github.com/joireve/passerby/blob/main/models/yolov8n.onnx"
click node_detector "https://github.com/joireve/passerby/blob/main/src/PedestrianDetector.cpp"
click node_engine "https://github.com/joireve/passerby/blob/main/include/DnnEngine.hpp"
click node_preprocess "https://github.com/joireve/passerby/blob/main/src/PedestrianDetector.cpp"
click node_forward "https://github.com/joireve/passerby/blob/main/src/PedestrianDetector.cpp"
click node_decode "https://github.com/joireve/passerby/blob/main/src/PedestrianDetector.cpp"
click node_timing "https://github.com/joireve/passerby/blob/main/src/StageTimeTracker.cpp"
click node_allocator "https://github.com/joireve/passerby/blob/main/src/CountingAllocator.cpp"

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_app,node_csv,node_display,node_user toneBlue
class node_factory,node_image,node_video toneAmber
class node_model,node_detector,node_engine,node_preprocess,node_forward,node_decode toneMint
class node_timing,node_allocator toneRose
class node_opencv toneIndigo
```

## Components

### Runtime orchestration

- [Application loop](https://github.com/joireve/passerby/blob/main/src/main.cpp): `src/main.cpp`
- [CSV output](https://github.com/joireve/passerby/blob/main/src/main.cpp): `src/main.cpp`
- [Window display](https://github.com/joireve/passerby/blob/main/src/main.cpp): `src/main.cpp`

### Frame input

- [Reader factory](https://github.com/joireve/passerby/blob/main/src/FrameReaderFactory.cpp): `src/FrameReaderFactory.cpp`
- [Image reader](https://github.com/joireve/passerby/blob/main/src/ImageFrameReader.cpp): `src/ImageFrameReader.cpp`
- [Video reader](https://github.com/joireve/passerby/blob/main/src/VideoFrameReader.cpp): `src/VideoFrameReader.cpp`

### Detection pipeline

- [ONNX model](https://github.com/joireve/passerby/blob/main/models/yolov8n.onnx): `models/yolov8n.onnx`
- [Pedestrian detector](https://github.com/joireve/passerby/blob/main/src/PedestrianDetector.cpp): `src/PedestrianDetector.cpp`
- [DNN engine selection](https://github.com/joireve/passerby/blob/main/include/DnnEngine.hpp): `include/DnnEngine.hpp`
- [LetterBox and blob](https://github.com/joireve/passerby/blob/main/src/PedestrianDetector.cpp): `src/PedestrianDetector.cpp`
- [DNN forward](https://github.com/joireve/passerby/blob/main/src/PedestrianDetector.cpp): `src/PedestrianDetector.cpp`
- [Decode and NMS](https://github.com/joireve/passerby/blob/main/src/PedestrianDetector.cpp): `src/PedestrianDetector.cpp`

### Runtime observability

- [Stage timing](https://github.com/joireve/passerby/blob/main/src/StageTimeTracker.cpp): `src/StageTimeTracker.cpp`
- [Allocation statistics](https://github.com/joireve/passerby/blob/main/src/CountingAllocator.cpp): `src/CountingAllocator.cpp`

### Other components

- **CLI user**
- **OpenCV DNN**

## Connections

- CLI user → Application loop: provides options (evidence: `README.md`)
- Application loop → Reader factory: creates reader (evidence: `src/main.cpp`)
- Reader factory → Image reader: dispatches images (evidence: `README.md`)
- Reader factory → Video reader: dispatches videos (evidence: `README.md`)
- Application loop → Pedestrian detector: runs detection (evidence: `src/main.cpp`)
- Application loop → CSV output: writes detections (evidence: `src/main.cpp`)
- Application loop → Window display: displays frames (evidence: `src/main.cpp`)
- ONNX model → Pedestrian detector: loaded by (evidence: `README.md`)
- Pedestrian detector → DNN engine selection: selects engine (evidence: `src/PedestrianDetector.cpp`)
- Pedestrian detector → LetterBox and blob: preprocesses frames (evidence: `src/PedestrianDetector.cpp`)
- Pedestrian detector → DNN forward: runs inference (evidence: `src/PedestrianDetector.cpp`)
- Pedestrian detector → Decode and NMS: postprocesses output (evidence: `src/PedestrianDetector.cpp`)
- DNN forward → OpenCV DNN: calls DNN (evidence: `src/PedestrianDetector.cpp`)
- Application loop → Stage timing: records stages (evidence: `src/main.cpp`)
- Application loop → Allocation statistics: counts allocations (evidence: `src/main.cpp`)
