# xactai/eli-alpr architecture

> Architecture diagram of the GitHub repository xactai/eli-alpr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xactai/eli-alpr
- Repository: https://github.com/xactai/eli-alpr

## Overview

##### Project type and purpose
- This is an embedded, real-time computer-vision pipeline written in C++ for the NVIDIA Jetson Nano.
- Its purpose is Automatic License Plate Recognition (ALPR) by cascading three YOLO/​Darknet models: vehicle detection, license-plate detection, and optical character recognition (OCR).
- Input can be images, video files, USB/MIPI cameras, RTSP/HLS streams; output is recognized plate text (CLI, JSON over HTTP) plus optional MJPEG stream of annotated frames.

##### File‐structure highlights
- Top-level:
- CMakeLists.txt / YOLO_ALPR.cbp – build scripts
- config.json – runtime settings (input source, model paths, thresholds, output ports/folders)
- models/ – three sets of Darknet network files (.cfg, .weights, .names)
- / & src/ – six modules:
– RTSPcam – video capture & ROI cropping
– Regression – heuristic post-processing (sorting letters, deduplication)
– Tjson – JSON serialization
– http_stream – HTTP server for JSON output (port 8070)
– MJPG_sender – HTTP MJPEG server for annotated video (port 8090)
– Numbers – numeric/string helper utilities
- src/main.cpp – orchestrates module initialization, model loading, processing loop.

##### Key architectural patterns
- Pipeline pattern: linear, stage-by-stage processing of frames (capture → detect → crop → detect → crop → OCR → post-process → output).
- Modular design: each stage is encapsulated in its own module/class with a clear interface.
- Configuration-driven: behavior is toggled via config.json (input source selection, thresholds, folder outputs, flags for CLI vs render).

##### Main components and interactions (to show
a. Configuration Loader
- Reads config.json at startup → supplies parameters to all modules.
b. Video Input Module (RTSPcam)
- Opens the selected VIDEO_INPUT (image, folder, video, usbcam, CSI, CCTV, HLS).
- Applies global Region-of-Interest (RoI) crop.
- Emits raw frames to the Processing Pipeline.
c. Processing Pipeline – three sequential YOLO/​Darknet stages (all GPU/CUDA accelerated):
→ crop each vehicle region
→ crop each plate region
3. OCR Model → runs character detection/recognition → outputs alphanumeric string
d. Heuristic Module (Regression)
– Sorts OCR detections by position, removes duplicates.
e. Output Modules
1. Tjson + http_stream → serialize plate data to JSON → serve on HTTP port 8070
3. CLI Logger → optionally print text to terminal
4. (Optional) File Writers → save debug images/JSONs to disk if folder paths ≠ “none”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration
    subgraph "Configuration"
        ConfigLoader["Configuration Loader\n(config.json)"]:::config
        Main["Main Orchestrator\n(src/main.cpp)"]:::config
    end
    ConfigLoader --> Main

    %% Input Module
    Main --> VideoInput
    subgraph "Input Module"
        VideoInput["Video Input Module\nRTSPcam (Global ROI)"]:::io
    end

    %% Detection Pipeline
    VideoInput --> VehicleDetector
    subgraph "Detection Pipeline"
        VehicleDetector["YOLO Vehicle Detector\nDarknet+CUDA"]:::corePipeline
        PlateDetector["YOLO Plate Detector\nDarknet+CUDA"]:::corePipeline
        OCRDetector["YOLO OCR Detector\nDarknet+CUDA"]:::corePipeline
    end
    VehicleDetector --> PlateDetector
    PlateDetector --> OCRDetector

    %% Post-Processing
    OCRDetector --> Heuristic
    subgraph "Post-Processing"
        Heuristic["Heuristic Module\n(Regression)"]:::util
    end

    %% Output Services
    Heuristic --> JSONSer
    Heuristic --> MJPEG
    Heuristic --> CLI
    Heuristic --> FileWriters
    subgraph "Output Services"
        JSONSer["JSON Serializer\n(Tjson + http_stream)\nport 8070"]:::util
        MJPEG["MJPEG Stream Server\n(MJPG_sender)\nport 8090"]:::io
        CLI["CLI Logger"]:::output
        FileWriters["File Writers\n(Debug images/JSON)"]:::output
    end

    %% External Clients
    subgraph "External Clients"
        Browser["Web Browser\n(MJPEG Viewer)"]:::external
        Service["Node.js/MongoDB\n(JSON Consumer)"]:::external
    end
    Browser --> MJPEG
    Service --> JSONSer

    %% Click Events
    click ConfigLoader "https://github.com/xactai/eli-alpr/blob/main/config.json"
    click Main "https://github.com/xactai/eli-alpr/blob/main/src/main.cpp"
    click VideoInput "https://github.com/xactai/eli-alpr/blob/main/include/RTSPcam.h"
    click VideoInput "https://github.com/xactai/eli-alpr/blob/main/src/RTSPcam.cpp"
    click VehicleDetector "https://github.com/xactai/eli-alpr/tree/main/models/"
    click PlateDetector "https://github.com/xactai/eli-alpr/tree/main/models/"
    click OCRDetector "https://github.com/xactai/eli-alpr/tree/main/models/"
    click Heuristic "https://github.com/xactai/eli-alpr/blob/main/include/Regression.h"
    click Heuristic "https://github.com/xactai/eli-alpr/blob/main/src/Regression.cpp"
    click JSONSer "https://github.com/xactai/eli-alpr/blob/main/include/Tjson.h"
    click JSONSer "https://github.com/xactai/eli-alpr/blob/main/src/Tjson.cpp"
    click JSONSer "https://github.com/xactai/eli-alpr/blob/main/include/http_stream.h"
    click JSONSer "https://github.com/xactai/eli-alpr/blob/main/src/http_stream.cpp"
    click MJPEG "https://github.com/xactai/eli-alpr/blob/main/include/MJPG_sender.h"
    click MJPEG "https://github.com/xactai/eli-alpr/blob/main/src/MJPG_sender.cpp"
    click FileWriters "https://github.com/xactai/eli-alpr/blob/main/include/Numbers.h"

    %% Styles
    classDef corePipeline fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef io fill:#90EE90,stroke:#000,stroke-width:1px
    classDef util fill:#FFFFE0,stroke:#000,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef output fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef external fill:#f0f0f0,stroke:#666,stroke-width:1px,stroke-dasharray: 4 2
```
