# darl-libsignal/libsignal architecture

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

- Interactive diagram: https://gitdiagram.com/darl-libsignal/libsignal
- Repository: https://github.com/darl-libsignal/libsignal

## Overview

##### Project Type and Purpose
- This is a Python-based library (“LibSignal”) providing OpenAI Gym-compatible environments for traffic signal control (TSC) and a suite of baseline methods (traditional and RL-based).
- It wraps three simulators (CityFlow, SUMO, CBEngine), handles data ingestion/conversion, and supports running complete train/evaluate pipelines with one command (`python run.py`).

##### High-Level File/Directory Analysis
- Top-level:
- run.py – CLI entrypoint and experiment driver
- requirements.txt – Python dependencies
- README.md – installation & usage
- Core modules:
- agent/ – implementations of RL and heuristic TSC agents (DQN, PPO, SAC, CoLight, etc.)
- common/ – shared interfaces, metric calculators, registry, converter utilities
- configs/ – simulator config files (CityFlow, SUMO, OpenEngine) and TSC hyperparameter YAMLs
- data/ & dataset/ – raw traffic network/flow data and on-the-fly dataset class
- generator/ – road network & traffic generator scripts
- world/ – simulator wrappers for CityFlow, SUMO, OpenEngine
- trainer/ – base trainer and TSC trainer that orchestrate RL training loops
- utils/ – logging utilities
- final_result/ – training logs and output artifacts

##### Key Architectural Patterns
- Modular “plugin” architecture via a central registry (`common/registry.py`) to decouple components (agents, worlds, tasks).
- Clear separation of concerns:
- Data generation/conversion (generator/, common/converter)
- Simulator abstraction (world/)
- Environment interface (environment.py)
- Agent logic (agent/)
- Training orchestration (trainer/)
- Configuration driven (configs/)
- Uniform experiment launcher (run.py) that reads configs, instantiates classes via registry, and triggers training/evaluation.

##### Main Components & Interactions
a. Components
1. Run Manager (run.py + Config Loader)
2. Registry Service (common/registry)
3. Generator & Converter (generator/, common/converter)
4. Data Store (data/raw_data, dataset/onfly_dataset)
5. Simulator Adapters (world_cityflow, world_sumo, world_openengine)
6. Gym-style Environment (environment.py)
7. Agent Module (agent/)
8. Trainer Module (trainer/)
9. Metrics & Logger (common/metrics, utils/logger)
10. Output Artifacts (final_result/)
11. External Simulators (CityFlow, SUMO, CBEngine binaries)

b. Relationships & Data Flow
1. Run Manager loads CLI args & YAML configs → Register desired Agent, World, Task.
2. Generator (if synthetic) prepares road network & flow files → Data Store.
3. Converter optionally transforms net/flow between formats.
4. World Adapter wraps external simulator API → exposes Gym-style step(), reset().
5. Trainer asks Environment for state → passes to Agent → receives action → applies to Environment → Environment calls Simulator → returns next state, reward.
6. Trainer updates Agent model (via PyTorch), logs metrics.
7. At end of epoch/experiment, Logger writes to final_result/.

c. Architectural Patterns & Principles
- Dependency Injection via registry to plug new agents or simulators.
- Single Responsibility: each module focuses on one facet (e.g., world vs. agent vs. trainer).
- Configuration-first: YAML and CFG files drive behavior, reducing hardcoding.
- Extensibility: adding a new agent or simulator only requires implementing the interface and registering it.

d. Key Technologies & Libraries
- Python 3.9, PyTorch 1.11.0, OpenAI Gym API
- CityFlow, SUMO, CBEngine simulators
- YAML for TSC hyperparameters
- Docker for reproducible execution

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Control Plane
    subgraph "Control Plane"
        RM["Run Manager\n(run.py)"]:::core
        CL["Config Loader\n(configs/)"]:::data
        RS["Registry Service\n(common/registry.py)"]:::core
    end

    %% Data Plane
    subgraph "Data Plane"
        GEN["Generator\n(generator/)"]:::core
        CONV["Converter Utility\n(common/converter.py)"]:::core
        RD["Raw Data\n(data/raw_data/)"]:::data
        OF["On-The-Fly Dataset\n(dataset/onfly_dataset.py)"]:::data
    end

    %% Compute Plane
    subgraph "Compute Plane"
        WA1["World Adapter\nCityFlow"]:::core
        WA2["World Adapter\nSUMO"]:::core
        WA3["World Adapter\nOpenEngine"]:::core
        ENV["Gym-style Environment\n(environment.py)"]:::core
        AG["Agent Module\n(agent/)"]:::core
        BT["Base Trainer\n(trainer/base_trainer.py)"]:::core
        TT["TSC Trainer\n(trainer/tsc_trainer.py)"]:::core
        MET["Metrics Calculator\n(common/metrics.py)"]:::core
        LOG["Logger Utility\n(utils/logger.py)"]:::core
        OUT["Output Artifacts\n(final_result/)"]:::storage
    end

    %% External Simulators
    subgraph "External Simulators"
        CF["CityFlow"]:::external
        SU["SUMO"]:::external
        CB["CBEngine"]:::external
    end

    %% Control Plane Connections
    CL --> RM
    RM --> RS
    RM --> CL
    RM --> GEN
    RM --> RS

    %% Data Plane Connections
    GEN --> RD
    CONV <--> RD
    CONV <--> OF

    %% Registry instantiation
    RS --> AG
    RS --> WA1
    RS --> WA2
    RS --> WA3
    RS --> BT
    RS --> TT

    %% Compute Plane Connections
    BT --> ENV
    TT --> ENV
    ENV --> AG
    AG --> ENV
    ENV <--> WA1
    ENV <--> WA2
    ENV <--> WA3
    WA1 --> CF
    WA2 --> SU
    WA3 --> CB
    BT --> MET
    TT --> MET
    BT --> LOG
    TT --> LOG
    BT --> OUT
    TT --> OUT

    %% Click Events
    click RM "https://github.com/darl-libsignal/libsignal/blob/master/run.py"
    click CL "https://github.com/darl-libsignal/libsignal/tree/master/configs/"
    click RS "https://github.com/darl-libsignal/libsignal/blob/master/common/registry.py"
    click GEN "https://github.com/darl-libsignal/libsignal/tree/master/generator/"
    click CONV "https://github.com/darl-libsignal/libsignal/blob/master/common/converter.py"
    click RD "https://github.com/darl-libsignal/libsignal/tree/master/data/raw_data/"
    click OF "https://github.com/darl-libsignal/libsignal/blob/master/dataset/onfly_dataset.py"
    click WA1 "https://github.com/darl-libsignal/libsignal/blob/master/world/world_cityflow.py"
    click WA2 "https://github.com/darl-libsignal/libsignal/blob/master/world/world_sumo.py"
    click WA3 "https://github.com/darl-libsignal/libsignal/blob/master/world/world_openengine.py"
    click ENV "https://github.com/darl-libsignal/libsignal/blob/master/environment.py"
    click AG "https://github.com/darl-libsignal/libsignal/tree/master/agent/"
    click BT "https://github.com/darl-libsignal/libsignal/blob/master/trainer/base_trainer.py"
    click TT "https://github.com/darl-libsignal/libsignal/blob/master/trainer/tsc_trainer.py"
    click MET "https://github.com/darl-libsignal/libsignal/blob/master/common/metrics.py"
    click LOG "https://github.com/darl-libsignal/libsignal/blob/master/utils/logger.py"
    click OUT "https://github.com/darl-libsignal/libsignal/tree/master/final_result/"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72
    classDef data fill:#ABEBC6,stroke:#1D8348
    classDef storage fill:#F9E79F,stroke:#B7950B
    classDef external fill:#D5D8DC,stroke:#566573
```
