# kerema14/traffic-control-simulator architecture

> Architecture diagram of the GitHub repository kerema14/traffic-control-simulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kerema14/traffic-control-simulator
- Repository: https://github.com/kerema14/traffic-control-simulator

## Overview

##### Project Type and Purpose
- This is a desktop Java game built with JavaFX (JDK 21).
- It simulates traffic control on a grid of roads, includes a built-in level editor, and loads/saves predefined levels.
- Key functionality: render interactive UI panes, manage game state, parse plain-text level files, and orchestrate vehicle and traffic-light behaviors.

##### File Structure Analysis
- Top-level directories:
- bin: compiled classes (TrafficControlSimulator) and level resources (bin/levels/*.txt).
- lib: external JavaFX JARs for UI, graphics, media, etc.
- src: application source under package TrafficControlSimulator and raw level files (src/levels/).
- src/TrafficControlSimulator:
- Main.java – app entry point, JavaFX Application subclass.
- Game.java – central game loop and state manager.
- LevelParser.java – reads and interprets level#.txt into game objects.
- EditorPane.java / LevelPane.java – JavaFX UI controllers for the editor and play modes.
- Domain classes: Building, RoadTile, TrafficLight, Vehicle.

##### Insights from README
- Confirms JavaFX usage and level designer feature.

a. Main Components
- User Interface Layer (JavaFX):
– Main Window (Main.java → primaryStage)
– EditorPane
– LevelPane
- Application Core:
– Game Engine (Game.java)
– Domain Model (Building, RoadTile, TrafficLight, Vehicle)
- Persistence / I/O:
– LevelParser (reads/writes *.txt)
– File System (src/levels & bin/levels)
- External Dependencies:
– JavaFX libraries (lib/javafx-*.jar)

b. Relationships & Data Flows
- Main initializes JavaFX, loads UI panes.
- UI panes invoke Game to load or edit a level.
- Game calls LevelParser → reads level file → returns domain objects.
- Game populates Domain Model → notifies UI for rendering.
- User actions in EditorPane generate events → passed to Game → update Domain Model → UI refresh.
- Game loop triggers AI/movement logic on Vehicle/TrafficLight → updates UI.

c. Architectural Patterns & Principles
- MVC-like separation: UI controllers (EditorPane/LevelPane) vs. Game logic vs. Domain entities.
- Single process, layered architecture: UI → Core → Persistence → File system.
- Clear separation of concerns: parsing, state management, rendering, and domain behaviors.

d. Key Technologies & Frameworks
- Java 21
- JavaFX (Controls, FXML, Graphics, Media)
- Plain-text level definitions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Subgraphs
    subgraph "User Interface Layer" 
        direction TB
        Main["Main Window\n(Main.java)"]:::ui
        EditorPane["Editor Mode Pane\n(EditorPane.java)"]:::ui
        LevelPane["Play Mode Pane\n(LevelPane.java)"]:::ui
    end

    subgraph "Application Core" 
        direction TB
        Game["Game Engine\n(Game.java)"]:::core
    end

    subgraph "Domain Model" 
        direction TB
        Building["Building\n(Building.java)"]:::domain
        RoadTile["RoadTile\n(RoadTile.java)"]:::domain
        TrafficLight["TrafficLight\n(TrafficLight.java)"]:::domain
        Vehicle["Vehicle\n(Vehicle.java)"]:::domain
    end

    subgraph "Persistence Layer" 
        direction TB
        LevelParser["LevelParser\n(LevelParser.java)"]:::persistence
        SrcLevels["src/levels\n(Dev Levels)"]:::persistence
        BinLevels["bin/levels\n(Runtime Levels)"]:::persistence
    end

    subgraph "External Dependencies" 
        direction TB
        JavaFX["JavaFX Libraries"]:::external
    end

    %% Connections
    JavaFX -->|"provides UI framework"| Main
    Main -->|"launchUI()"| EditorPane
    Main -->|"launchUI()"| LevelPane
    EditorPane -->|"onUserAction() / editLevel()"| Game
    LevelPane -->|"onUserAction() / playLevel()"| Game
    Game -->|"loadLevel()/saveLevel()"| LevelParser
    LevelParser -->|"read/write"| SrcLevels
    LevelParser -->|"read/write"| BinLevels
    Game -->|"instantiate/update"| Building
    Game -->|"instantiate/update"| RoadTile
    Game -->|"instantiate/update"| TrafficLight
    Game -->|"instantiate/update"| Vehicle
    Building -->|"renderData()"| EditorPane
    Building -->|"renderData()"| LevelPane
    RoadTile -->|"renderData()"| EditorPane
    RoadTile -->|"renderData()"| LevelPane
    TrafficLight -->|"renderData()"| EditorPane
    TrafficLight -->|"renderData()"| LevelPane
    Vehicle -->|"renderData()"| EditorPane
    Vehicle -->|"renderData()"| LevelPane

    %% Click Events
    click Main "https://github.com/kerema14/traffic-control-simulator/blob/main/src/TrafficControlSimulator/Main.java"
    click EditorPane "https://github.com/kerema14/traffic-control-simulator/blob/main/src/TrafficControlSimulator/EditorPane.java"
    click LevelPane "https://github.com/kerema14/traffic-control-simulator/blob/main/src/TrafficControlSimulator/LevelPane.java"
    click Game "https://github.com/kerema14/traffic-control-simulator/blob/main/src/TrafficControlSimulator/Game.java"
    click Building "https://github.com/kerema14/traffic-control-simulator/blob/main/src/TrafficControlSimulator/Building.java"
    click RoadTile "https://github.com/kerema14/traffic-control-simulator/blob/main/src/TrafficControlSimulator/RoadTile.java"
    click TrafficLight "https://github.com/kerema14/traffic-control-simulator/blob/main/src/TrafficControlSimulator/TrafficLight.java"
    click Vehicle "https://github.com/kerema14/traffic-control-simulator/blob/main/src/TrafficControlSimulator/Vehicle.java"
    click LevelParser "https://github.com/kerema14/traffic-control-simulator/blob/main/src/TrafficControlSimulator/LevelParser.java"
    click SrcLevels "https://github.com/kerema14/traffic-control-simulator/tree/main/src/levels/"
    click BinLevels "https://github.com/kerema14/traffic-control-simulator/tree/main/bin/levels/"

    %% Styles
    classDef ui fill:#E0F7FA,stroke:#006064,color:#004D40;
    classDef core fill:#E8F5E9,stroke:#1B5E20,color:#2E7D32;
    classDef domain fill:#FFFDE7,stroke:#F9A825,color:#F57F17;
    classDef persistence fill:#FFF3E0,stroke:#E65100,color:#EF6C00;
    classDef external fill:#ECEFF1,stroke:#455A64,color:#37474F;
```
