# bkhnk48/pps architecture

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

- Interactive diagram: https://gitdiagram.com/bkhnk48/pps
- Repository: https://github.com/bkhnk48/pps

## Overview

##### Project type and purpose
- This is a standalone Python‐based path‐planning simulation tool (an “open‐source tool” rather than a web app or microservice).

##### File structure
Top-level:
- main.py, connect.py, config.py, filter.py – the orchestration and utility scripts
- components/ – pre-processing and input converters
- controller/ – core orchestration classes (SimulationEngine, GraphProcessor, node/edge/event generators, time‐window controller, restriction controller)
- model/ – domain models (Node, Edge, Graph, Person, AGV, Event, Lobby, Logger, NXSolution) plus two submodules:
– forecasting_model_module/ – ML forecasting integration
– hallway_simulator_module/ – compiled OpenGL C++ simulator binaries for x86_64 and ARM64
- data/ – JSON configuration
- output_B_solver*/ – solver output snapshots
- requirements.txt, README.md, sonar properties, tests

##### Key README insights
- Requires Python 3.10+, OpenGL 4.6+, and a compiled C++ hallway simulator
- User interacts via CLI prompts in main.py
- Three solver choices: external LINK II, parallel network‐simplex, or NetworkX
- Optional call to hallway simulator (sfm)

##### Main components
a. CLI front end (main.py)
b. Configuration loader (config.py + data/configuration.json)
c. Input converter/preprocessor (components/convert_file.py + filter.py)
d. Controller layer (SimulationEngine):
- NodeGenerator, EdgeGenerator, EventGenerator → build raw graphs
- GraphProcessor → augment graph, apply restrictions, time‐window logic
- RestrictionController & TimeWindowController → enforce constraints
e. Solver engines:
- LINK II (external)
- Parallel network‐simplex (in Python)
- NetworkX (imported library)
f. Forecasting model (forecasting_model_module/ForecastingModel.py)
g. Hallway simulator (hallway_simulator_module/app external binary)
h. Domain model classes (model/*.py) for AGV, Person, Graph, NXSolution, Logger, etc.
i. Output writer (Logger + output_B_solver directories)

##### Relationships and data flows
- User → CLI front end → loads config and input file
- CLI → Components → raw graph data → Controller → domain Graph object
- Controller invokes ForecastingModel → adjusts event timings
- Controller invokes Solver engine → returns route assignments as NXSolution
- If “run sfm” chosen → Controller calls external hallway_simulator_module/app, passing solution
- Simulator returns visual/metrics → aggregated by Logger
- Final schedules written to output_B_solver/ and displayed on CLI

##### Architectural patterns and design principles
- Layered architecture: CLI → Preprocessing → Controller → Model → External/Solver modules
- Clear separation of concerns: components handle I/O, controller handles orchestration, model holds data structures
- Plug-in extensibility: solver engines are interchangeable, forecasting and simulator are optional modules
- Use of external binaries wrapped in Python for high‐performance simulation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Preprocessing Layer
    subgraph "Preprocessing" 
        cli["CLI Front End"]:::pre
        configLoader["Configuration Loader"]:::pre
        configFile["configuration.json"]:::pre
        convert["convert_file.py"]:::pre
        filter["filter.py"]:::pre
    end

    %% Core Orchestration Layer
    subgraph "Core Orchestration"
        simEngine["SimulationEngine"]:::orch
        nodeGen["NodeGenerator"]:::orch
        edgeGen["EdgeGenerator"]:::orch
        eventGen["EventGenerator"]:::orch
        graphProc["GraphProcessor"]:::orch
        restrictCont["RestrictionController"]:::orch
        timeWinCont["TimeWindowController"]:::orch
    end

    %% Domain Model Layer
    subgraph "Domain Model"
        Node["Node"]:::model
        Edge["Edge"]:::model
        Event["Event"]:::model
        Graph["Graph"]:::model
        Person["Person"]:::model
        AGV["AGV"]:::model
        Lobby["Lobby"]:::model
        NXSolution["NXSolution"]:::model
        LoggerClass["Logger"]:::model
    end

    %% Solver Engines
    subgraph "Solver Engines"
        parNet["Parallel network-simplex"]:::third
        nxWrap["NetworkX Wrapper"]:::third
        linkII["LINK II (External)"]:::third
    end

    %% External Modules
    subgraph "External Modules"
        forecast["ForecastingModel"]:::ext
        sfmWrapper["HallwaySimulator.py"]:::ext
        binx86["x86_64 app"]:::ext
        binarm["ARM64 app"]:::ext
    end

    %% Output Layer
    subgraph "Output"
        outputs["Output Snapshots"]:::model
    end

    %% Data Flows
    cli -->|runs| configLoader
    configLoader -->|loads| configFile
    cli -->|inputs| convert
    cli -->|inputs| filter
    convert -->|raw graph data| simEngine
    filter -->|filtered data| simEngine
    configLoader -->|configuration| simEngine

    simEngine -->|generate nodes| nodeGen
    nodeGen -->|generate edges| edgeGen
    edgeGen -->|generate events| eventGen
    eventGen -->|raw graph| graphProc
    graphProc -->|apply restrictions| restrictCont
    restrictCont -->|apply time windows| timeWinCont
    timeWinCont -->|build domain graph| Graph

    simEngine -->|invoke forecasting| forecast
    forecast -->|adjust events| simEngine

    simEngine -->|choose solver| parNet
    simEngine -->|choose solver| nxWrap
    simEngine -->|choose solver| linkII

    simEngine -->|if run sfm| sfmWrapper
    sfmWrapper -->|call binary| binx86
    sfmWrapper -->|call binary| binarm
    binx86 -->|metrics| LoggerClass
    binarm -->|metrics| LoggerClass

    simEngine -->|log results| LoggerClass
    LoggerClass -->|write| outputs
    outputs -->|display| cli

    %% Click Events
    click cli "https://github.com/bkhnk48/pps/blob/finished_new_input/main.py"
    click configLoader "https://github.com/bkhnk48/pps/blob/finished_new_input/config.py"
    click configFile "https://github.com/bkhnk48/pps/blob/finished_new_input/data/configuration.json"
    click convert "https://github.com/bkhnk48/pps/blob/finished_new_input/components/convert_file.py"
    click filter "https://github.com/bkhnk48/pps/blob/finished_new_input/filter.py"
    click simEngine "https://github.com/bkhnk48/pps/blob/finished_new_input/controller/SimulationEngine.py"
    click nodeGen "https://github.com/bkhnk48/pps/blob/finished_new_input/controller/NodeGenerator.py"
    click edgeGen "https://github.com/bkhnk48/pps/blob/finished_new_input/controller/EdgeGenerator.py"
    click eventGen "https://github.com/bkhnk48/pps/blob/finished_new_input/controller/EventGenerator.py"
    click graphProc "https://github.com/bkhnk48/pps/blob/finished_new_input/controller/GraphProcessor.py"
    click restrictCont "https://github.com/bkhnk48/pps/blob/finished_new_input/controller/RestrictionController.py"
    click timeWinCont "https://github.com/bkhnk48/pps/blob/finished_new_input/controller/TimeWindowController.py"
    click parNet "https://github.com/bkhnk48/pps/blob/finished_new_input/raw_shortest_path.py"
    click nxWrap "https://github.com/bkhnk48/pps/blob/finished_new_input/nx_solution.py"
    click forecast "https://github.com/bkhnk48/pps/blob/finished_new_input/model/forecasting_model_module/ForecastingModel.py"
    click sfmWrapper "https://github.com/bkhnk48/pps/blob/finished_new_input/model/hallway_simulator_module/HallwaySimulator.py"
    click binx86 "https://github.com/bkhnk48/pps/tree/finished_new_input/model/hallway_simulator_module/sim/x86_64/app"
    click binarm "https://github.com/bkhnk48/pps/tree/finished_new_input/model/hallway_simulator_module/sim/arm64/app"
    click Node "https://github.com/bkhnk48/pps/blob/finished_new_input/model/Node.py"
    click Edge "https://github.com/bkhnk48/pps/blob/finished_new_input/model/Edge.py"
    click Event "https://github.com/bkhnk48/pps/blob/finished_new_input/model/Event.py"
    click Graph "https://github.com/bkhnk48/pps/blob/finished_new_input/model/Graph.py"
    click Person "https://github.com/bkhnk48/pps/blob/finished_new_input/model/Person.py"
    click AGV "https://github.com/bkhnk48/pps/blob/finished_new_input/model/AGV.py"
    click Lobby "https://github.com/bkhnk48/pps/blob/finished_new_input/model/Lobby.py"
    click NXSolution "https://github.com/bkhnk48/pps/blob/finished_new_input/model/NXSolution.py"
    click LoggerClass "https://github.com/bkhnk48/pps/blob/finished_new_input/model/Logger.py"

    %% Styles
    classDef pre fill:#fff9c4,stroke:#aaa,stroke-width:1px
    classDef orch fill:#c8e6c9,stroke:#aaa,stroke-width:1px
    classDef model fill:#ffe0b2,stroke:#aaa,stroke-width:1px
    classDef ext fill:#b3e5fc,stroke:#aaa,stroke-width:1px
    classDef third fill:#eeeeee,stroke:#aaa,stroke-width:1px
```
