# angelobanse/sumoscenariogenerator architecture

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

- Interactive diagram: https://gitdiagram.com/angelobanse/sumoscenariogenerator
- Repository: https://github.com/angelobanse/sumoscenariogenerator

## Overview

##### Project Type and Purpose
- This is a web application whose primary goal is to generate and download the necessary files to initiate a basic road traffic simulation in SUMO.
- The README explains that the tool is intended to run on a web server (or locally via WAMP, MAMP, or LAMP), and it integrates with external tools like SUMO and Python.
- As such, the application is a hybrid full-stack web tool that has a clear separation between a client-facing frontend and a backend that manages file/script generation.

##### File Structure
- Frontend Components:
– Files such as index.html, 404.html, final.php, and script.php form the entry points to the web interface.
– The directories “css”, “js”, “images”, and “bootstrap” house the styling, JavaScript interactions, media, and layout libraries.
– The manifest.json and robots.txt indicate configuration for web app behavior and search engine/device guidelines.
- Backend Components:
– The cgi-bin directory contains Python scripts (script.py and deleter.py) that likely perform the critical functions of generating and managing the simulation files.
– PHP files (script.php, final.php) present in the root appear to connect the user interface with the underlying logic (potentially calling the Python scripts).
- Auxiliary Files:
– .htaccess and the LICENSE ensure configuration of server behavior and the legal distribution terms.

##### Main Architectural Components
- Client Interface (Frontend):
– A web browser that loads the user interface (HTML, CSS, JavaScript including scenario-generator functionality).
– UI elements that allow a user to input simulation parameters and trigger file generation.
- Web Server & Presentation Layer:
– Static file server that serves HTML, CSS, JS, images, and other assets.
– PHP scripts (script.php, final.php) that manage incoming requests from the client UI.
- Business Logic / Backend Layer:
– cgi-bin Python scripts (script.py, deleter.py):
▪ They execute the logic for generating simulation scenarios.
▪ Possibly handle cleanup or deletion of temporary files.
- External Dependencies:
– SUMO Simulation Software (installed locally or on the server), which utilizes the generated files to run simulations.
– Environment prerequisites like Python and a web server with PHP enabled.

##### Relationships and Interactions
- The client (web browser) interacts with the front-end interface (index.html) that leverages CSS and JavaScript (in js/ and bootstrap directories) to provide a dynamic experience.
- User actions trigger requests to server-side PHP scripts (script.php/final.php), which process inputs and manage calls to the backend logic.
- The PHP layer then communicates with Python scripts in the cgi-bin directory—either synchronously or asynchronously—to generate or delete necessary simulation files.
- Finally, the generated scenario files are returned to the client’s browser for download or further action.

##### Important Architectural Patterns and Technologies
- The separation of concerns is evident: presentation (HTML/CSS/JS), business logic (PHP), and computational logic (Python scripts in cgi-bin).
- The application follows a simple MVC or layered pattern where each layer has a clear responsibility.
- Technologies include PHP for backend scripting, Python for specialized processing via CGI, and client-side technologies like Bootstrap and JavaScript for a responsive UI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        BrowserUI["Client Browser - UI"]:::frontend
        IndexHTML["index.html (Entry Point)"]:::frontend
        ErrorHTML["404.html"]:::frontend
        Manifest["manifest.json"]:::frontend
        Robots["robots.txt"]:::frontend
        CSSFile["css/customStyle.css"]:::frontend
        BootstrapCSS["bootstrap/css"]:::frontend
        BootstrapJS["bootstrap/js"]:::frontend
        ScenarioJS["js/scenario-generator.js"]:::frontend
    end

    %% Web Server & Presentation Layer
    subgraph "Web Server & Presentation Layer"
        ScriptPHP["script.php"]:::middleware
        FinalPHP["final.php (PHP)"]:::middleware
        Htaccess[".htaccess"]:::middleware
    end

    %% Backend / Business Logic
    subgraph "Backend / Business Logic"
        ScriptPy["cgi-bin/script.py"]:::backend
        DeleterPy["cgi-bin/deleter.py"]:::backend
        CgiReadme["cgi-bin/README.md"]:::backend
    end

    %% Auxiliary & Legal
    subgraph "Auxiliary & Legal"
        License["LICENSE"]:::auxiliary
        Readme["README.md"]:::auxiliary
    end

    %% External Dependency
    External["SUMO Simulator - External Dependency"]:::external

    %% Interactions
    BrowserUI -->|"sends_request"| ScriptPHP
    BrowserUI -->|"sends_request"| FinalPHP

    ScriptPHP -->|"calls"| ScriptPy
    FinalPHP -->|"calls"| DeleterPy

    ScriptPy -->|"generates_files"| External
    DeleterPy -->|"cleans_files"| External

    ScriptPy -->|"response"| ScriptPHP
    DeleterPy -->|"response"| FinalPHP

    ScriptPHP -->|"delivers_files"| BrowserUI
    FinalPHP -->|"delivers_files"| BrowserUI

    %% Assets loading (dotted links indicating static asset loads)
    IndexHTML -.-> BrowserUI
    ErrorHTML -.-> BrowserUI
    Manifest -.-> BrowserUI
    Robots -.-> BrowserUI
    CSSFile -.-> BrowserUI
    BootstrapCSS -.-> BrowserUI
    BootstrapJS -.-> BrowserUI
    ScenarioJS -.-> BrowserUI

    %% Click Events for Frontend Assets
    click IndexHTML "https://github.com/angelobanse/sumoscenariogenerator/blob/master/index.html"
    click ErrorHTML "https://github.com/angelobanse/sumoscenariogenerator/blob/master/404.html"
    click Manifest "https://github.com/angelobanse/sumoscenariogenerator/blob/master/manifest.json"
    click Robots "https://github.com/angelobanse/sumoscenariogenerator/blob/master/robots.txt"
    click CSSFile "https://github.com/angelobanse/sumoscenariogenerator/blob/master/css/customStyle.css"
    click BootstrapCSS "https://github.com/angelobanse/sumoscenariogenerator/tree/master/bootstrap/css"
    click BootstrapJS "https://github.com/angelobanse/sumoscenariogenerator/tree/master/bootstrap/js"
    click ScenarioJS "https://github.com/angelobanse/sumoscenariogenerator/blob/master/js/scenario-generator.js"

    %% Click Events for Web Server & Presentation Layer
    click ScriptPHP "https://github.com/angelobanse/sumoscenariogenerator/blob/master/script.php"
    click FinalPHP "https://github.com/angelobanse/sumoscenariogenerator/blob/master/final.php"
    click Htaccess "https://github.com/angelobanse/sumoscenariogenerator/blob/master/.htaccess"

    %% Click Events for Backend / Business Logic
    click ScriptPy "https://github.com/angelobanse/sumoscenariogenerator/blob/master/cgi-bin/script.py"
    click DeleterPy "https://github.com/angelobanse/sumoscenariogenerator/blob/master/cgi-bin/deleter.py"
    click CgiReadme "https://github.com/angelobanse/sumoscenariogenerator/blob/master/cgi-bin/README.md"

    %% Click Events for Auxiliary & Legal
    click License "https://github.com/angelobanse/sumoscenariogenerator/tree/master/LICENSE"
    click Readme "https://github.com/angelobanse/sumoscenariogenerator/blob/master/README.md"

    %% Styles
    classDef frontend fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef middleware fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef backend fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef external fill:#ffe699,stroke:#333,stroke-width:2px;
    classDef auxiliary fill:#e6e6e6,stroke:#333,stroke-width:2px;
```
