# harkirat78/billiards-physics-game architecture

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

- Interactive diagram: https://gitdiagram.com/harkirat78/billiards-physics-game
- Repository: https://github.com/harkirat78/billiards-physics-game

## Overview

##### Main Components
- Frontend/UI: Represented by HTML files (index.html, shoot.html) and JavaScript (game.js). These form the browser-based interface where users play the game and visualizations are rendered.
- Physics Engine & Core Game Logic: Highlight the C-based components (phylib.c, phylib.h, phylib.i, and possibly the compiled output via the makefile) that encapsulate the billiards physics simulation. Consider mentioning Physics.py if it also manages or demonstrates physics computations.
- Database Layer: Include the MySQL database, which is used for managing game data, player scores, and statistics.
- Additional Scripted Tools: Although not dominant in the architecture, note that Python scripts (such as server.py) may handle auxiliary data processing or system monitoring.

##### Relationships and Data Flows
- Backend-to-Physics Engine: Illustrate how the server coordinates with the multi-threaded C physics engine, including passing game state information and retrieving physics calculation results.
- Backend/Physics Engine-to-Database: Indicate data persistence flows between the backend (or physics engine) and the MySQL database for storing/retrieving game metrics.
- Client-Side Dynamic Updates: Optionally show how front-end JavaScript (game.js) processes data for real-time visual feedback.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clearly divide the presentation layer (HTML/CSS/JS), the application logic (server and API layer), and the core computation layer (C-based multi-threaded physics engine).
- Multi-threading: Mark the C physics engine as multi-threaded to signify optimized performance during real-time simulation.
- API Integration: Highlight the role of API communications for transferring information between the web interface and backend logic.
- Efficient Memory Management: Note that the C code is optimized for memory allocation – this can be annotated near the physics engine component.

##### Technical Details
- For Frontend: Label “Web Browser” with components such as “index.html,” “shoot.html,” and “game.js.”
- For Backend: Label “Server/API Layer” noting the components—Python (server.py) and mention of Node.js (per the README instructions) if applicable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend/UI Layer
    subgraph "Frontend/UI"
        direction TB
        F1["index.html"]:::frontend
        F2["shoot.html"]:::frontend
        F3["game.js"]:::frontend
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        direction TB
        BS["server.py"]:::backend
    end

    %% C Game Engine (Physics Engine)
    subgraph "C Game Engine"
        direction TB
        PE0["Engine Core (multi-threaded)"]:::physics
        PE1["phylib.c"]:::physics
        PE2["phylib.h"]:::physics
        PE3["phylib.i"]:::physics
        PE4["makefile (build executable)"]:::physics
        PE5["Physics.py"]:::physics
        PE0 --> PE1
        PE0 --> PE2
        PE0 --> PE3
        PE0 --> PE4
        PE0 --> PE5
    end

    %% MySQL Database
    DB["MySQL Database"]:::database

    %% Data Flow Connections
    F3 -->|"API_calls"| BS
    BS -->|"invoke_simulation"| PE0
    BS -->|"persist/retrieve"| DB
    PE0 -->|"game_metrics"| DB

    %% Click Events
    click F1 "https://github.com/harkirat78/billiards-physics-game/blob/main/index.html"
    click F2 "https://github.com/harkirat78/billiards-physics-game/blob/main/shoot.html"
    click F3 "https://github.com/harkirat78/billiards-physics-game/blob/main/game.js"
    click BS "https://github.com/harkirat78/billiards-physics-game/blob/main/server.py"
    click PE1 "https://github.com/harkirat78/billiards-physics-game/blob/main/phylib.c"
    click PE2 "https://github.com/harkirat78/billiards-physics-game/blob/main/phylib.h"
    click PE3 "https://github.com/harkirat78/billiards-physics-game/blob/main/phylib.i"
    click PE4 "https://github.com/harkirat78/billiards-physics-game/tree/main/makefile"
    click PE5 "https://github.com/harkirat78/billiards-physics-game/blob/main/Physics.py"

    %% Styles
    classDef frontend fill:#e1f5fe,stroke:#0277bd,stroke-width:2px;
    classDef backend fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef physics fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
    classDef database fill:#fce4ec,stroke:#ad1457,stroke-width:2px;
```
