# hhgzs/tjurm-2024 architecture

> Architecture diagram of the GitHub repository hhgzs/tjurm-2024, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hhgzs/tjurm-2024
- Repository: https://github.com/hhgzs/tjurm-2024

## Overview

##### Main Components
- Configuration & Parameter Manager – Represented by the modules in “data/uniconfig”, “include/data_manager”, and “src/data_manager”. This component handles JSON-based configurations and parameters (including dynamic linking of parameters from system directories).
- Garage/Vehicle Manager – This corresponds to the “garage” module in both include and source folders. It uses factory pattern techniques to create specific instances (e.g., wrapper_car, wrapper_rune, wrapper_tower) based on the configuration.
- Thread Management – The project is organized using several threads:
- Control Threads (located in “src/threads/control”): Handles serial communication with the lower-level hardware using CRC, receive/send functionalities.
- Pipeline Threads (in “src/threads/pipeline”): This is where the system’s core real-time processing happens. It is further divided into:
- Baseline Pipeline (for standard YOLOv5-based detection and tracking)
- Fourpoints Pipeline (handling the four-point network processing)
- Rune Pipeline (for the specialized “rune” mode)
- UI & Debug Threads – Threads like “image_thread.cpp”, “recording_thread.cpp”, and “ui.cpp” handle image display, debugging, and user interface functionalities.
- Main Application Controller – The “main.cpp” initializes and links all of the above components, coordinating startup and thread management.
- External Dependencies – The system relies on the OpenRM vision algorithm library and the nlohmann JSON library (embedded in “libs/json”). Make sure to mark this external linkage.

##### Relationships and Interactions
- The configuration files from “data/uniconfig” are read by the Data Manager and then propagated as parameters throughout the system (using the Singleton and Template method patterns).
- The Garage Module interacts with both configuration and control threads. It creates specialized instances based on the current configuration (Factory Pattern) and communicates with the control module (Observer Pattern).
- The Control module interacts with the hardware (serial communication). It both sends control signals (post-processing results from the pipelines) and receives data that may further influence the pipelines and modes.
- UI / Debug threads provide real-time visualization. Their data flows back into the control structures as needed (for example, when “imshow” is enabled).

##### Architectural Patterns and Design Principles
- Pipeline Architecture: Illustrate the flow steps in each pipeline stage (preprocessing, detection, tracking, and control) with each block clearly labeled.
- Decoupled Algorithm and Framework Layers: Show a clear separation between the self-aim framework (which handles high-level thread orchestration and parameter management) and the external OpenRM algorithm library (plugged in via dynamic linking).
- Use of Design Patterns: Indicate where factory (garage creation), strategy (choosing processing pipeline modes), and observer (serial communication for triggering mode changes) patterns are used.

##### Relevant Technologies, Frameworks, and Libraries
- C++ (with CMake as the build system)
- JSON processing using the nlohmann JSON library (from “libs/json”)
- External dependency on the OpenRM-2024 vision algorithm library
- Multi-threading (various thread modules for control, pipeline, and UI) and serial port communication (embedded in control threads)
- Linux-based configuration involving system-level services (e.g., rc.local for self-startup)

##### Important Detail
- As many components as possible from the file tree—don’t shy away from splitting the architecture in detailed sections. Even small components (like the checksum in control/crc or the image display in image_thread.cpp) contribute to the overall architecture.
- Since the project supports customization by modifying parameters in the configuration directory (and uses a symbolic link from /etc/openrm), highlight that configuration management is an integral part of the system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Application
    MainApp["Main Application (main.cpp)"]:::main

    %% Configuration & Parameter Manager
    DataManager["Data Manager/Configuration"]:::config

    %% Garage/Vehicle Manager
    GarageManager["Garage Manager (Vehicle Factory)"]:::garage

    %% Control Module (Serial Communication, CRC)
    ControlModule["Control Module (Serial Communication, CRC)"]:::control

    %% Pipeline Threads Subgraphs
    subgraph "Baseline Pipeline"
        BaselinePre["Preprocessor (Baseline)"]:::pipeline
        BaselineDet["Detector (Baseline)"]:::pipeline
        BaselineTrack["Tracker/Updater (Baseline)"]:::pipeline
    end

    subgraph "Fourpoints Pipeline"
        FourpointsPre["Preprocessor (Fourpoints)"]:::pipeline
        FourpointsDet["Detector (Fourpoints)"]:::pipeline
        FourpointsProc["Fourpoints Process"]:::pipeline
    end

    subgraph "Rune Pipeline"
        RunePre["Preprocessor (Rune)"]:::pipeline
        RuneDet["Detector (Rune)"]:::pipeline
        RuneTrack["Tracker (Rune)"]:::pipeline
    end

    %% UI & Debug Threads
    UIThread["UI/Debug Threads"]:::ui

    %% External Dependencies
    ExternalDep["External Dependencies"]:::external

    %% Connections: Main Application spawns all threads/components
    MainApp -->|"init_config"| DataManager
    MainApp -->|"init_vehicle_factory"| GarageManager
    MainApp -->|"spawn_control_thread"| ControlModule
    MainApp -->|"spawn_pipeline_threads"| BaselinePre
    MainApp -->|"spawn_pipeline_threads"| FourpointsPre
    MainApp -->|"spawn_pipeline_threads"| RunePre
    MainApp -->|"spawn_UI_thread"| UIThread

    %% Data flow: Configuration to Garage Manager
    DataManager -->|"provides_parameters"| GarageManager

    %% Garage Manager communicates with Control Module (Factory & Observer patterns)
    GarageManager -->|"triggers_updates"| ControlModule

    %% Pipeline flow: Baseline Pipeline stages
    BaselinePre -->|"processes"| BaselineDet
    BaselineDet -->|"detects"| BaselineTrack
    BaselineTrack -->|"results"| ControlModule

    %% Pipeline flow: Fourpoints Pipeline stages
    FourpointsPre -->|"processes"| FourpointsDet
    FourpointsDet -->|"detects"| FourpointsProc
    FourpointsProc -->|"results"| ControlModule

    %% Pipeline flow: Rune Pipeline stages
    RunePre -->|"processes"| RuneDet
    RuneDet -->|"detects"| RuneTrack
    RuneTrack -->|"results"| ControlModule

    %% UI feedback to Control Module
    UIThread -->|"feedback"| ControlModule

    %% Data Manager uses External Dependencies (e.g., JSON library)
    DataManager -->|"uses_JSON"| ExternalDep

    %% Click Events for Configuration & Parameter Manager
    click DataManager "https://github.com/hhgzs/tjurm-2024/blob/main/data/uniconfig/Config.json"
    click DataManager "https://github.com/hhgzs/tjurm-2024/blob/main/data/uniconfig/CamLens.json"
    click DataManager "https://github.com/hhgzs/tjurm-2024/blob/main/data/uniconfig/guard.sh"
    click DataManager "https://github.com/hhgzs/tjurm-2024/blob/main/include/data_manager/base.h"
    click DataManager "https://github.com/hhgzs/tjurm-2024/blob/main/include/data_manager/param.h"
    click DataManager "https://github.com/hhgzs/tjurm-2024/blob/main/src/data_manager/base.cpp"
    click DataManager "https://github.com/hhgzs/tjurm-2024/blob/main/src/data_manager/init.cpp"
    click DataManager "https://github.com/hhgzs/tjurm-2024/blob/main/src/data_manager/param.cpp"

    %% Click Events for Garage/Vehicle Manager
    click GarageManager "https://github.com/hhgzs/tjurm-2024/blob/main/include/garage/garage.h"
    click GarageManager "https://github.com/hhgzs/tjurm-2024/blob/main/include/garage/interface.h"
    click GarageManager "https://github.com/hhgzs/tjurm-2024/blob/main/include/garage/wrapper_car.h"
    click GarageManager "https://github.com/hhgzs/tjurm-2024/blob/main/include/garage/wrapper_rune.h"
    click GarageManager "https://github.com/hhgzs/tjurm-2024/blob/main/include/garage/wrapper_tower.h"
    click GarageManager "https://github.com/hhgzs/tjurm-2024/blob/main/src/garage/garage.cpp"
    click GarageManager "https://github.com/hhgzs/tjurm-2024/blob/main/src/garage/wrapper_car.cpp"
    click GarageManager "https://github.com/hhgzs/tjurm-2024/blob/main/src/garage/wrapper_rune.cpp"
    click GarageManager "https://github.com/hhgzs/tjurm-2024/blob/main/src/garage/wrapper_tower.cpp"

    %% Click Events for Control Threads
    click ControlModule "https://github.com/hhgzs/tjurm-2024/blob/main/include/threads/control/control.h"
    click ControlModule "https://github.com/hhgzs/tjurm-2024/blob/main/include/threads/control/crc.h"
    click ControlModule "https://github.com/hhgzs/tjurm-2024/blob/main/include/threads/control/structure.h"
    click ControlModule "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/control/control.cpp"
    click ControlModule "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/control/crc.cpp"
    click ControlModule "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/control/receive_thread.cpp"
    click ControlModule "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/control/send_thread.cpp"

    %% Click Events for Baseline Pipeline Threads
    click BaselinePre "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/pipeline/baseline/preprocessor_thread.cpp"
    click BaselineDet "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/pipeline/baseline/detector_thread.cpp"
    click BaselineTrack "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/pipeline/baseline/tracker_thread.cpp"
    click BaselineTrack "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/pipeline/baseline/tracker/locater.cpp"
    click BaselineTrack "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/pipeline/baseline/tracker/pointer.cpp"
    click BaselineTrack "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/pipeline/baseline/tracker/updater.cpp"

    %% Click Events for Fourpoints Pipeline Threads
    click FourpointsPre "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/pipeline/fourpoints/preprocessor_thread.cpp"
    click FourpointsDet "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/pipeline/fourpoints/detector_thread.cpp"
    click FourpointsProc "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/pipeline/fourpoints/fourpoints.cpp"

    %% Click Events for Rune Pipeline Threads
    click RunePre "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/pipeline/rune/preprocessor_thread.cpp"
    click RuneDet "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/pipeline/rune/detector_thread.cpp"
    click RuneTrack "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/pipeline/rune/tracker_thread.cpp"

    %% Click Events for UI & Debug Threads
    click UIThread "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/pipeline/image_thread.cpp"
    click UIThread "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/pipeline/recording_thread.cpp"
    click UIThread "https://github.com/hhgzs/tjurm-2024/blob/main/src/threads/pipeline/ui.cpp"

    %% Click Event for Main Application Controller
    click MainApp "https://github.com/hhgzs/tjurm-2024/blob/main/src/main.cpp"

    %% Click Event for External Dependencies (JSON Library)
    click ExternalDep "https://github.com/hhgzs/tjurm-2024/tree/main/libs/json"

    %% Styles
    classDef main fill:#ffdd57,stroke:#333,stroke-width:2px;
    classDef config fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef garage fill:#82E0AA,stroke:#333,stroke-width:2px;
    classDef control fill:#F5B7B1,stroke:#333,stroke-width:2px;
    classDef pipeline fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef ui fill:#D2B4DE,stroke:#333,stroke-width:2px;
    classDef external fill:#CCD1D1,stroke:#333,stroke-width:2px;
```
