# diogo-vf/rythmtree architecture

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

- Interactive diagram: https://gitdiagram.com/diogo-vf/rythmtree
- Repository: https://github.com/diogo-vf/rythmtree

## Overview

##### Project Type & Purpose
- RythmTree is a full-stack, real-time rhythm-game web application.
- Frontend (HTML/JS/CSS/SASS) serves the game UI, assets, and lobby.
- Backend (Ruby) handles HTTP page serving, REST/WS APIs, game state, and persistence in MongoDB.

##### File Structure
- Top-level “client” folder: contains UI views (HTML), scripts (JS modules under core, actions, adapters), styles (SASS → CSS), images, audio assets, and tests.
- Top-level “server” folder: custom HTTP server, WebSocket server, MVC-style controllers and models, configuration, utility scripts, and app_start entry point.
- Config files in both client and server configure ports, pages, and data sources.
- Build scripts: SASS watcher compiles `.scss` → `.css`.

##### README for Insights
- Tech stack: Ruby 2.6.3, MongoDB, SASS for CSS preprocessing.
- Run steps: `sass --watch…` for styles, `ruby server/app_start.rb` to launch both HTTP and WS servers.
- Configurable HTTP_PORT, MongoDB driver Gems.

##### Main Components & Their Interactions
a. Client-side Browser
– Serves static assets: HTML views, JS bundle, CSS.
– Core JS modules manage page navigation, UI rendering, game logic, and WS messaging.
– Initiates WebSocket connections for real-time events and HTTP requests for page loads or REST endpoints (e.g., login, level metadata).
b. HTTP Server (Ruby)
– Listens on configured HTTP_PORT.
– Routes initial page requests to view templates (controllers under `server/controllers`).
– Exposes REST endpoints for CRUD operations on levels, players, replays, textures, sequences, music.
c. WebSocket Server (Ruby)
– Separate listener for real-time game data (e.g., rhythm cues, player actions).
– Manages persistent WS connections via `server/websocket_server/connection.rb`.
d. Application Controllers & Models
– Controllers (levels.rb, players.rb, etc.) orchestrate requests, invoke model operations, serialize JSON.
– Models wrap MongoDB collections (`mongoDB.rb`, `level.rb`, `player.rb`, etc.), provide data access and validation.
e. MongoDB
– Stores persistent game entities: level designs, player stats, replays, audio references, textures.
f. Build/Dev Tools
– SASS compiler watches SCSS and outputs CSS.
– Optional file watcher (`server/watcher.rb`) for automatic reloads.

##### Architectural Patterns & Design Principles
- MVC pattern on the server: Controllers → Models → MongoDB.
- Modular JS on the client: core modules (boot, builder, pagesManager, wsManager) + adapters + actions.
- Clear separation of concerns: static asset serving vs. API vs. real-time messaging.
- Configuration-driven: `config/config.js` and `config/config.rb` drive environment specifics.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        Browser["Client Browser\n(HTML/CSS/JS Modules)"]:::client
        Config["Client Configuration"]:::client
        Core["Core JS Modules"]:::client
        Actions["Actions & Adapters"]:::client
        Styles["Styles / SASS Build"]:::client
    end

    %% Server Layer
    subgraph "Server Layer"
        direction TB
        HTTP["Ruby HTTP Server\n(controllers, app_start.rb)"]:::server
        Controllers["REST API Controllers"]:::server
        WS["Ruby WebSocket Server\n(connection, listener)"]:::server
        Models["Models & MongoDB Integration"]:::server
        Utils["Utilities & File Watcher"]:::server
    end

    %% Build Tools and DB
    SassCompiler["SASS Compiler\n(SCSS → CSS)"]:::tool
    DB[(MongoDB)]:::db

    %% Connections
    Browser -->|"HTTP GET/POST"| HTTP
    Browser -->|"WebSocket message"| WS
    HTTP -->|"DB read/write"| DB
    WS -->|"DB read/write"| DB
    SassCompiler -->|"compiles SCSS→CSS"| Styles
    Styles -->|"served static"| Browser

    %% Click Events
    click Browser "https://github.com/diogo-vf/rythmtree/tree/master/client/"
    click Config "https://github.com/diogo-vf/rythmtree/blob/master/client/config/config.js"
    click Core "https://github.com/diogo-vf/rythmtree/blob/master/client/scripts/core/boot.js"
    click Actions "https://github.com/diogo-vf/rythmtree/blob/master/client/scripts/actions.js"
    click Styles "https://github.com/diogo-vf/rythmtree/blob/master/client/styles/scss/_common.scss"
    click HTTP "https://github.com/diogo-vf/rythmtree/blob/master/server/app_start.rb"
    click Controllers "https://github.com/diogo-vf/rythmtree/blob/master/server/controllers/levels.rb"
    click WS "https://github.com/diogo-vf/rythmtree/blob/master/server/websocket_server/connection.rb"
    click Models "https://github.com/diogo-vf/rythmtree/blob/master/server/models/mongoDB.rb"
    click Utils "https://github.com/diogo-vf/rythmtree/blob/master/server/utils.rb"

    %% Styles
    classDef client fill:#a3d5ff,stroke:#333,stroke-width:1px
    classDef server fill:#a2f5a2,stroke:#333,stroke-width:1px
    classDef db fill:#f5d58f,stroke:#333,stroke-width:1px
    classDef tool fill:#d3d3d3,stroke:#333,stroke-width:1px
```
