# nortonv/bridge-simulation architecture

> Architecture diagram of the GitHub repository nortonv/bridge-simulation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nortonv/bridge-simulation
- Repository: https://github.com/nortonv/bridge-simulation

## Overview

##### Projekt típusa és célja (amit a diagramnak tükröznie kell)
Ez egy **lokális (desktop) Python/Pygame alkalmazás**, ami egy **2D hídépítő editor + valós idejű statikai (FEM) szimulátor**. Nincs klasszikus “backend/frontend” vagy hálózati komponens; a “rendszer” főleg **moduláris game-loop + domain modell + solver + UI + audio + perzisztencia**.

A következő top-level modulok természetes architekturális komponensek:

- **Entry / App bootstrap**
- `src/main.py`
- **Core / Game state & world**
- `src/core/game_state.py`
- `src/core/grid.py`
- `src/core/constants.py`
- `src/core/material_manager.py`
- `src/core/serializer.py`
- **Domain entities (a “model”)**
- `src/entities/bridge.py`
- `src/entities/beam.py`
- `src/entities/agent.py` (Ixchel karakter)
- **Solver / Physics**
- `src/solvers/static_solver.py`
- **UI (editor + overlays + property menu + rendering)**
- `src/ui/editor.py`
- `src/ui/renderers.py`
- `src/ui/graph_overlay.py`
- `src/ui/property_menu.py`
- `src/ui/toolbar.py`
- **Audio**
- `src/audio/audio_manager.py` + `src/audio/assets/*`
- **Shared utilities**
- `src/utils/math_utils.py`
- `src/utils/render_utils.py`
- **Externalized data**
- `saves/*.json` (bridge mentések)
- `requirements.txt` (pygame, numpy)

##### Fő futási ciklus (Game loop) – központi gerinc
Rajzold ki középre a **Pygame loop-ot** (implicit a `main.py`-ban), és bontsd 4 lépésre:
##### Render + Audio (képernyő + hang)

Ezt érdemes egy “App Runtime” dobozként ábrázolni, benne a loop-pal.

##### Build Mode vs Simulation Mode (két fő workflow)
A README alapján két domináns állapot van (SPACE vált):
- **Build Mode**:
- UI Editor (node/beam létrehozás, törlés, mozgatás, ív eszköz)
- Bridge modell módosul
- (Opcionális) “smart connection”: kereszteződésnél darabolás → ez tipikusan `bridge.py/beam.py` logika
- **Simulation Mode**:
- Agent (Ixchel) mozog → terhelési pont változik
- Solver fut → eredmények (N, M, U, ratio, buckling) visszaíródnak a modelbe vagy egy “results” struktúrába
- UI overlay nézetek (forces/material/stress) és feliratok ezekből renderelnek

A diagramon külön jelöld két “mode” dobozzal és nyilakkal, hogy ugyanazt a Bridge modellt használják, csak más műveletekkel.

##### Kapcsolatok és adatáramlás (nyilak, direction, “mi kitől függ”)
A legfontosabb kapcsolatok, amiket a diagramon kötelező megmutatni:

##### Core state mint Single Source of Truth
- `main.py` → tart egy **GameState**-et (`core/game_state.py`)
- **GameState** tartalmazza / hivatkozza:
- **Bridge** (`entities/bridge.py`) + benne **Beams/Nodes** (beam, implicit node struktúra)
- **Agent** (`entities/agent.py`)
- **MaterialManager** (`core/material_manager.py`) + globális beállítások (hőmérséklet, stb.)
- UI állapotok (aktuális tool, view mode, label mode, distortion factor)

Nyilak:
- `UI/*` → (events) → `GameState` / `Bridge` módosítás
- `Solver/static_solver.py` ← (Bridge geometry + materials + loads + temperatures) ← `GameState`
- `Solver/static_solver.py` → (displacements/forces/moments/ratios) → `GameState`/`Bridge` (vagy solver result cache)
- `UI/renderers.py`, `UI/graph_overlay.py` ← (Bridge + solver results + view flags) ← `GameState`

##### Perzisztencia (Save/Load)
- `UI/editor.py` (Ctrl+S / Ctrl+L) → `core/serializer.py`
- `serializer.py` ↔ `saves/*.json`
- `serializer.py` → `Bridge` rekonstruálása → `GameState` frissítése

##### Audio események
- `UI/editor.py` és/vagy `GameState` események (beam_place/break, step, theme) → `audio/audio_manager.py` → Pygame mixer + assets

##### Utils mint “leaf dependency”
- `utils/math_utils.py` és `utils/render_utils.py` tipikusan “alul” vannak:
- Solver és Entities használják a `math_utils`-t
- UI renderers használják a `render_utils`-t
Nyilak itt lefelé mutassanak (mindenki függ tőlük, ők senkitől).

##### Fontos architekturális minták/principles, amiket érdemes kiemelni a diagramon
- **Layering** (nem tökéletesen tiszta, de jól ábrázolható):
- UI / Presentation (`src/ui`)
- Domain Model (`src/entities`)
- Simulation/Computation (`src/solvers`)
- Application State/Services (`src/core`, `src/audio`)
- Utilities (`src/utils`)
- **Single state object**: a `GameState` a központi aggregator.
- **Functional-ish solver**: a `static_solver` egy elkülönített számítási pipeline (NumPy).
- **Event-driven input**: Pygame input → tool logika → model mutations.

##### Mit írj rá a diagramra technológiaként
- **Python 3.8+**
- **Pygame**: main loop, input, windowing, rendering, audio backend
- **NumPy**: globális merevségi mátrix / lineáris algebra (FEM)
- **JSON**: mentések (`saves/*.json`)

Javasolt 2 nézetet készíteni; mindkettő legyen részletes.

Dobozok és alcsoportok:
- **App Runtime (main.py + Pygame loop)**
- **Core**
- GameState
- Grid
- MaterialManager
- Serializer
- **Entities**
- Bridge
- Beam
- Agent
- **Solver**
- StaticSolver (FEM)
- **UI**
- Editor (tools)
- Renderers (bridge + deformation)
- PropertyMenu
- Toolbar
- GraphOverlay (distortion slider)
- **Audio**
- AudioManager + assets
- **Utils**
- math_utils
- render_utils
- **Data**
- saves/*.json

Nyilak (irányhelyes dependency):
- UI → Core/GameState
- Core/GameState → Entities
- Solver ↔ (Core/GameState + Entities) (input on one side, results on the other)
- UI/Renderers → Core/GameState (+ solver results)
- Serializer ↔ JSON files
- UI/Editor → AudioManager
- Solver → NumPy (külső dependency jelölés)

##### (2) “Runtime sequence / dataflow” (dinamikus működés)
Egy tipikus frame folyamatábra vagy szekvencia:
- Pygame event pump
- Editor tool interprets (Build: add/move/delete/arc; Sim: agent step)
- Update Bridge/Agent in GameState
- If sim_mode: call StaticSolver.solve(bridge, materials, loads, temps) -> results
- Update overlays (force view / stress ratio / labels)
- Render frame
- Trigger audio events (step, place, break)

A principal szintű “legpontosabb” diagramhoz legyenek következetes konvenciók:

- UI: kék
- Core/services: lila
- Entities/model: zöld
- Solver: narancs
- IO/Data (JSON, assets): szürke
- External libs (Pygame, NumPy): vastag keret vagy külön “External” sáv
- **Nyíl típusok**:
- Teljes vonal: code dependency / import
- Szaggatott: runtime dataflow / call
- Vastag nyíl: nagy adat (pl. “Solver results: U, N, M, ratios”)
- **Címkézd az adatot** a nyilakon:
- “geometry (nodes/beams)”
- “materials (E, rho, strength, thickness, hollow_ratio)”
- “loads (self-weight, agent point load), temperatures (T0, Tsim)”
- “results (displacements, axial forces, moments, stress/buckling ratios)”
- **Mode állapot** jelölése:
- GameState-ben legyen egy “BuildMode/SimMode flag” felirat, és UI/solver nyilak feltételesek (“only when sim_mode”).

##### Gyakori hiba ennél a projektnél (és hogyan kerüld)
- Ne rajzolj “backend”-et vagy hálózati API-t: ez **single-process desktop app**.
- Ne egy dobozba tedd a “physics”-et: különítsd el a **Solver**-t (stat_solver) az **Entities**-től (Bridge/Beam), különben nem látszik a FEM pipeline.
- A Save/Load legyen explicit: `serializer.py` + `saves/*.json` külön komponens, mert a felhasználói workflow része.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% External Dependencies
    %% =========================
    subgraph "External Libraries & Data"
        direction TB
        EXT_PY["Python 3.8+"]:::external
        EXT_PYG["Pygame\n(loop,input,windowing,render,audio)"]:::external
        EXT_NP["NumPy\n(linear algebra for FEM)"]:::external
        DATA_JSON[("JSON Save Files\nsaves/*.json")]:::data
        DATA_ASSETS[("Audio Assets\n(sound files)")]:::data
        REQ["requirements.txt\n(pygame,numpy)"]:::data
    end

    %% =========================
    %% (1) Subsystem / Component Diagram (Static Architecture)
    %% =========================
    subgraph "1) Subsystem / Component Architecture"
        direction TB

        subgraph "App Runtime"
            direction TB
            MAIN["Entry / App Bootstrap\n(Pygame main loop)"]:::runtime
            LOOP["Game Loop\n1) Input\n2) State Update\n3) Physics Solve (if sim_mode)\n4) Render + Audio"]:::runtime
            MAIN -->|"drives"| LOOP
        end

        subgraph "Core (State & Services)"
            direction TB
            GS["GameState\n(Single Source of Truth)\n- build_mode/sim_mode flag\n- tool/view/label flags\n- distortion factor"]:::core
            GRID["Grid System"]:::core
            CONST["Constants / Config"]:::core
            MATM["MaterialManager\n(materials + global params e.g. temperature)"]:::core
            SER["Serializer\n(save/load)"]:::core

            GS -->|"uses"| GRID
            GS -->|"uses"| CONST
            GS -->|"uses"| MATM
            GS -->|"uses"| SER
        end

        subgraph "Domain Entities (Model)"
            direction TB
            BR["Bridge Aggregate\n(nodes + beams + connectivity)\n(smart connection: split on intersections)"]:::entity
            BE["Beam Element"]:::entity
            AG["Agent (Ixchel)\n(moving load point)"]:::entity

            BR -->|"contains"| BE
            GS -->|"holds"| BR
            GS -->|"holds"| AG
        end

        subgraph "Solver (Simulation / Computation)"
            direction TB
            SOL["StaticSolver (FEM)\nK·U = F\nDOF/node: (ux,uy,θ)"]:::solver
        end

        subgraph "UI / Presentation"
            direction TB

            subgraph "Editor & Controls"
                direction TB
                UI_ED["Editor\n(tools,input->model mutations,\nCtrl+S/Ctrl+L)"]:::ui
                UI_TB["Toolbar\n(tool selection / mode controls)"]:::ui
                UI_PM["PropertyMenu\n(parameter editing)"]:::ui
            end

            subgraph "Rendering & Overlays"
                direction TB
                UI_REN["Renderers\n(bridge + deformation + visuals)"]:::ui
                UI_OV["GraphOverlay\n(view: Forces/Material/Stress,\nlabels + distortion slider)"]:::ui
            end
        end

        subgraph "Audio"
            direction TB
            AUD["AudioManager\n(events -> pygame mixer)"]:::audio
        end

        subgraph "Shared Utilities (Leaf Dependencies)"
            direction TB
            MATH["math_utils\n(geometry,vector math)"]:::util
            RUTIL["render_utils\n(drawing helpers)"]:::util
        end
    end

    %% -------------------------
    %% Static dependencies + core flows
    %% -------------------------
    MAIN -->|"creates/owns"| GS
    LOOP -.->|"poll events"| EXT_PYG

    %% UI -> state/model
    UI_ED -->|"events: add/move/delete/arc\nmutate model"| GS
    UI_TB -->|"select tool / toggle mode"| GS
    UI_PM -->|"edit params"| GS

    %% Mode-specific relationships (annotated)
    UI_ED -.->|"SPACE toggles\nbuild_mode/sim_mode"| GS

    %% Solver I/O
    GS -.->|"geometry (nodes/beams)"| SOL
    GS -.->|"materials (E,rho,strength,thickness,hollow_ratio)"| SOL
    GS -.->|"loads (self-weight,agent point load)\ntemperatures (T0,Tsim)"| SOL
    SOL ==>|"results (U,N,M,stress/buckling ratios)"| GS

    %% UI reads state + results for rendering/overlays
    GS -.->|"bridge + results + view flags"| UI_REN
    GS -.->|"view modes + labels + distortion"| UI_OV

    %% Save/Load
    UI_ED -.->|"Ctrl+S/Ctrl+L"| SER
    SER <-->|"read/write"| DATA_JSON
    SER -.->|"reconstruct Bridge\nupdate GameState"| GS

    %% Audio events
    UI_ED -.->|"events (place/break/step/theme)"| AUD
    GS -.->|"state-driven events"| AUD
    AUD -->|"mixer backend"| EXT_PYG
    AUD -->|"loads"| DATA_ASSETS

    %% Utilities as leaf dependencies
    SOL -->|"uses"| MATH
    BR -->|"uses"| MATH
    BE -->|"uses"| MATH
    AG -->|"uses"| MATH
    UI_REN -->|"uses"| RUTIL
    UI_OV -->|"uses"| RUTIL

    %% External solver dependency
    SOL -->|"linear algebra"| EXT_NP

    %% Requirements file
    MAIN -.->|"runtime deps"| REQ

    %% =========================
    %% (2) Runtime Dataflow / Frame Sequence (Dynamic)
    %% =========================
    subgraph "2) Runtime Dataflow (Per Frame)"
        direction TB

        F0["Frame Start"]:::runtime
        F1["1) Pygame Event Pump\n(keyboard/mouse)"]:::runtime
        F2["2) Input Interpretation\n(Editor tools / Toolbar selection)"]:::ui
        F3["3) Update GameState\n(Build: mutate Bridge)\n(Sim: advance Agent/load)"]:::core
        F4{"sim_mode ?"}:::decision
        F5["4) StaticSolver.solve(...)\nAssemble K,F -> solve U"]:::solver
        F6["5) Store/Cache Results\n(U,N,M,ratios) in GameState/Bridge"]:::core
        F7["6) Overlays Prepare\n(Forces/Material/Stress, labels,\ndistortion factor)"]:::ui
        F8["7) Render Frame\n(Bridge + Deformation + Overlay)"]:::ui
        F9["8) Trigger Audio\n(place/break/step/theme)"]:::audio
        F10["Frame End"]:::runtime

        F0 --> F1 --> F2 --> F3 --> F4
        F4 -->|"yes"| F5 --> F6 --> F7 --> F8 --> F9 --> F10
        F4 -->|"no"| F7

        %% Bind dynamic steps to concrete modules
        F1 -.->|"pygame.event.get()"| EXT_PYG
        F2 -.->|"src/ui/editor.py\nsrc/ui/toolbar.py"| UI_ED
        F3 -.->|"mutations/flags"| GS
        F3 -.->|"Build: edit geometry\nSim: move agent load"| BR
        F3 -.->|"Sim: agent step"| AG
        F5 -.->|"src/solvers/static_solver.py"| SOL
        F7 -.->|"src/ui/graph_overlay.py"| UI_OV
        F8 -.->|"src/ui/renderers.py"| UI_REN
        F9 -.->|"src/audio/audio_manager.py"| AUD
    end

    %% =========================
    %% Click Events (from component_mapping)
    %% =========================
    click MAIN "https://github.com/nortonv/bridge-simulation/blob/main/src/main.py"
    click GS "https://github.com/nortonv/bridge-simulation/blob/main/src/core/game_state.py"
    click GRID "https://github.com/nortonv/bridge-simulation/blob/main/src/core/grid.py"
    click CONST "https://github.com/nortonv/bridge-simulation/blob/main/src/core/constants.py"
    click MATM "https://github.com/nortonv/bridge-simulation/blob/main/src/core/material_manager.py"
    click SER "https://github.com/nortonv/bridge-simulation/blob/main/src/core/serializer.py"
    click BR "https://github.com/nortonv/bridge-simulation/blob/main/src/entities/bridge.py"
    click BE "https://github.com/nortonv/bridge-simulation/blob/main/src/entities/beam.py"
    click AG "https://github.com/nortonv/bridge-simulation/blob/main/src/entities/agent.py"
    click SOL "https://github.com/nortonv/bridge-simulation/blob/main/src/solvers/static_solver.py"
    click UI_ED "https://github.com/nortonv/bridge-simulation/blob/main/src/ui/editor.py"
    click UI_REN "https://github.com/nortonv/bridge-simulation/blob/main/src/ui/renderers.py"
    click UI_OV "https://github.com/nortonv/bridge-simulation/blob/main/src/ui/graph_overlay.py"
    click UI_PM "https://github.com/nortonv/bridge-simulation/blob/main/src/ui/property_menu.py"
    click UI_TB "https://github.com/nortonv/bridge-simulation/blob/main/src/ui/toolbar.py"
    click AUD "https://github.com/nortonv/bridge-simulation/blob/main/src/audio/audio_manager.py"
    click DATA_ASSETS "https://github.com/nortonv/bridge-simulation/tree/main/src/audio/assets/"
    click MATH "https://github.com/nortonv/bridge-simulation/blob/main/src/utils/math_utils.py"
    click RUTIL "https://github.com/nortonv/bridge-simulation/blob/main/src/utils/render_utils.py"
    click DATA_JSON "https://github.com/nortonv/bridge-simulation/tree/main/saves/"
    click REQ "https://github.com/nortonv/bridge-simulation/blob/main/requirements.txt"

    %% =========================
    %% Styles (Color + Emphasis)
    %% =========================
    classDef runtime fill:#0b1220,stroke:#93c5fd,stroke-width:2px,color:#e5e7eb
    classDef ui fill:#0b3b66,stroke:#60a5fa,stroke-width:2px,color:#eaf2ff
    classDef core fill:#3b1b6a,stroke:#c4b5fd,stroke-width:2px,color:#f3e8ff
    classDef entity fill:#0f4d2f,stroke:#34d399,stroke-width:2px,color:#eafff5
    classDef solver fill:#7a2e0e,stroke:#fb923c,stroke-width:2px,color:#fff7ed
    classDef audio fill:#4a1240,stroke:#f472b6,stroke-width:2px,color:#ffe4f2
    classDef util fill:#1f2937,stroke:#9ca3af,stroke-width:2px,color:#f9fafb
    classDef data fill:#111827,stroke:#6b7280,stroke-width:2px,color:#f3f4f6
    classDef external fill:#0a2a2a,stroke:#2dd4bf,stroke-width:3px,color:#ecfeff
    classDef decision fill:#2b2b2b,stroke:#fbbf24,stroke-width:2px,color:#fffbea

    %% Emphasize "big data" edge style via thick link where supported
    linkStyle 0 stroke:#93c5fd,stroke-width:2px
    linkStyle 1 stroke:#93c5fd,stroke-width:2px
    linkStyle 14 stroke:#fb923c,stroke-width:4px
```
