# franciszekcieslik/classical-mechanics-simulator-in-2d architecture

> Architecture diagram of the GitHub repository franciszekcieslik/classical-mechanics-simulator-in-2d, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/franciszekcieslik/classical-mechanics-simulator-in-2d
- Repository: https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d

## Overview

##### Project type and purpose
- This is a desktop‐based 2D classical mechanics simulator written in Python.
- It provides an interactive GUI for users to define forces and velocities, runs a physics simulation loop, renders trajectories in real time, and persists experiment data to local JSON files.

##### File structure
- Top-level modules:
- app/main.py → application entry point and orchestrator
- app/app.py → application class that initializes subsystems (GUI, simulation loop, file I/O)
- Core directories:
- app/obj → all physics, rendering, GUI helper classes, managers
- app/local_save → JSON files for saved experiments
- Within app/obj you see subpackages for:
– guielements (sidebar, inputs, buttons)
– managers (ForceManager, VectorManager, ObjectsManager, SaveManager, etc.)
– core models (PhysicObject, RealObject, Trajectory)

##### README for additional insights
- Implements an extendable, interactive simulation with clear visualization
- Uses JSON for configuration and persistence
- Targets Python 3.9+ with pip‐installable requirements

a. Application Controller (app/main.py → app/app.py)
b. GUI Module (app/obj/guielements + renderer classes in app/obj/drawn)
c. Physics Simulation Engine (ForceManager, VectorManager, ObjectsManager, Trajectory)
e. Persistence Layer (SaveManager + local_save JSON storage)
g. External environment (Python runtime, optional Git for install)

##### Relationships and interactions
- User events → GUI Module → Controller
- Controller schedules Simulation Engine updates on tick
- Simulation Engine updates model state → passes updated state to Rendering Engine
- Rendering Engine draws on canvas via GUI Module
- Persistence Layer reads/writes model state to JSON when user saves/loads

##### Architectural patterns and principles
- MVC‐like separation:
- Model = physics objects & state managers
- Controller = app/app.py + event handlers in guielements → drives simulation loop
- Single responsibility: each manager class handles one concern (forces, objects, I/O)

##### Relevant technologies and frameworks
- Python 3.9+
- JSON for data persistence
- Standard library (dataclasses, tkinter or similar GUI bindings)
- Project uses pyproject.toml and requirements.txt for dependency management

##### Detail level
- Avoid over‐abstraction—show actual modules where business logic resides.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Environment
    subgraph "External Environment"
        PY["Python 3.9+ Runtime\npyproject.toml\nrequirements.txt"]:::external
        User["User"]:::external
    end

    %% Assets Manager
    subgraph "Assets Manager"
        Assets["Icons\napp/assets/icons/"]:::persistence
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        SM["SaveManager\napp/obj/savemanager.py"]:::persistence
        Local["Local Save\napp/local_save/"]:::persistence
    end

    %% Physics Simulation Engine
    subgraph "Physics Simulation Engine"
        FM["ForceManager\napp/obj/forcemanager.py"]:::core
        VM["VectorManager\napp/obj/vectormanager.py"]:::core
        OM["ObjectsManager\napp/obj/objectsmanager.py"]:::core
        TR["Trajectory\napp/obj/trajectory.py"]:::core
        IC["ImpulseCollector\napp/obj/impulsecollector.py"]:::core
        BA["BodyArea\napp/obj/body_area.py"]:::core
        PO["PhysicObject\napp/obj/physicobject.py"]:::core
        RO["RealObject\napp/obj/realobject.py"]:::core
    end

    %% Rendering Engine
    subgraph "Rendering Engine"
        Cam["Camera\napp/obj/camera.py"]:::ui
        DA["DrawAssistance\napp/obj/drawassistance.py"]:::ui
        Grid["Grid\napp/obj/grid.py"]:::ui
        Axes["Axes\napp/obj/axes.py"]:::ui
        Drawn["Shapes\napp/obj/drawn/"]:::ui
    end

    %% GUI Module
    subgraph "GUI Module"
        GUIPkg["Widgets\napp/obj/guielements/"]:::ui
        Panel["PanelGUI\napp/obj/panelgui.py"]:::ui
        Checkbox["CheckboxPool\napp/obj/guielements/checkboxpool.py"]:::ui
        Number["NumberInput\napp/obj/guielements/numberinput.py"]:::ui
        Toggle["ToggleImageButton\napp/obj/guielements/toggleimagebutton.py"]:::ui
        Sidebar["Sidebar\napp/obj/guielements/sidebar/sidebar.py"]:::ui
    end

    %% Application Controller
    subgraph "Application Controller"
        Main["Main\napp/main.py"]:::core
        App["App\napp/app.py"]:::core
    end

    %% Connections
    User -->|"user events"| GUIPkg
    GUIPkg -->|"handle event"| App
    App -->|"tick"| FM
    FM --> VM --> OM --> TR
    TR -->|"update state"| Cam
    Cam --> DA --> Drawn
    Drawn -->|"render frame"| GUIPkg
    App -->|"save/load"| SM
    SM -->|"read/write JSON"| Local
    GUIPkg -->|"load icons"| Assets
    PY -->|executes| App

    %% Click Events
    click Main "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/main.py"
    click App "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/app.py"
    click GUIPkg "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/tree/main/app/obj/guielements/"
    click Panel "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/obj/panelgui.py"
    click Checkbox "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/obj/guielements/checkboxpool.py"
    click Number "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/obj/guielements/numberinput.py"
    click Toggle "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/obj/guielements/toggleimagebutton.py"
    click Sidebar "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/obj/guielements/sidebar/sidebar.py"
    click Cam "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/obj/camera.py"
    click DA "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/obj/drawassistance.py"
    click Grid "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/obj/grid.py"
    click Axes "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/obj/axes.py"
    click Drawn "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/tree/main/app/obj/drawn/"
    click FM "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/obj/forcemanager.py"
    click VM "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/obj/vectormanager.py"
    click OM "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/obj/objectsmanager.py"
    click TR "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/obj/trajectory.py"
    click IC "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/obj/impulsecollector.py"
    click BA "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/obj/body_area.py"
    click PO "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/obj/physicobject.py"
    click RO "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/obj/realobject.py"
    click SM "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/blob/main/app/obj/savemanager.py"
    click Local "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/tree/main/app/local_save/"
    click Assets "https://github.com/franciszekcieslik/classical-mechanics-simulator-in-2d/tree/main/app/assets/icons/"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef persistence fill:#A9DFBF,stroke:#145A32,color:#0B5345;
    classDef ui fill:#F5CBA7,stroke:#B9770E,color:#873600;
    classDef external fill:#D5D8DC,stroke:#5D6D7E,color:#2C3E50;
    class Main,App,FM,VM,OM,TR,IC,BA,PO,RO core
    class SM,Local,Assets persistence
    class GUIPkg,Panel,Checkbox,Number,Toggle,Sidebar,Cam,DA,Grid,Axes,Drawn ui
    class PY,User external
```
