# sarachehab/gluttonio architecture

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

- Interactive diagram: https://gitdiagram.com/sarachehab/gluttonio
- Repository: https://github.com/sarachehab/gluttonio

## Overview

##### Main components
1. FPGA Subsystem
- Quartus RTL design (clk_divider, debounce, fir, top.v)
- Hardware testbench (C++ testbench, script)
- On-board software apps (main.c, latency_app)
- VM simulation environment (Python scripts: demo.py, fir_tester.py, etc.)
2. Game Client (Unity)
- Scenes & Assets (Menu, SampleScene, GameOver, sprites, sounds)
- C# scripts (ServerConnect.cs, FpgaController.cs, PlayerMovement.cs, etc.)
- TextMesh Pro UI
3. Game Server
- Node.js / TypeScript service (Express / WS)
- Domain model (Game.ts, Player.ts, Blob.ts, Food.ts, Bot.ts, MessageType.ts)
- Utilities (db.ts for persistence, PlayerUtils.ts)
- Tests (Jest or ts-node tests under /tests)
- Dev-only simulation scripts (game_development/*.js, brownian_motion)
4. External services & deployment
- AWS (EC2 or Elastic Beanstalk for server)
- Database (could be AWS RDS or a file-based DB)

##### Component relationships and data flows
– The Unity client opens a WebSocket connection to the Game Server and
exchanges JSON-encoded messages (ClientMessage ↔ ServerMessage).
– The server updates game state (positions, scores, spawns) and writes
persistent data via the DB utility.
– FPGA subsystem is developed, tested, and optionally connected via
JTAG/UART; the Unity client’s FpgaController class can interface
directly with a hardware board or a VM simulation (demo.py).
– Dev scripts under server/game_development allow local JavaScript
prototyping of game logic before server deployment.

##### Architectural patterns & principles
– Separation of concerns:
- Hardware design | Hardware-side software | Simulation VM
- Front-end (Unity) | Back-end (Node.js) | Persistence (DB)
– Event-driven, bidirectional messaging via WebSockets
– Layered architecture:
- Presentation (Unity UI + input handling)
- Application (C# game logic, state sync)
- Domain services (Node.js game loop, rule enforcement)
- Data layer (database abstraction)

##### Final remarks
– Be exhaustive: include all directories only if they play a runtime role (skip Unity’s Meta files).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% FPGA Subsystem (blue)
    subgraph "FPGA Subsystem"
        direction TB
        subgraph "Quartus RTL Modules"
            direction TB
            clk["clk_divider.v"]:::rtl
            debounce["debounce.v"]:::rtl
            fir["fir.v"]:::rtl
            top["top.v"]:::rtl
        end
        subgraph "Hardware Testbench"
            direction TB
            tb1["debounce_tb.cpp"]:::tb
            tb2["testbench.h"]:::tb
            tb3["test.sh"]:::tb
        end
        subgraph "On-board Software Apps"
            direction TB
            mainc["main.c"]:::sw
            mainelf["main.elf"]:::sw
            genapp["generate_app.sh"]:::sw
            latc["main.c (latency_app)"]:::sw
            latelf["main.elf (latency_app)"]:::sw
            lattest["test.py"]:::sw
        end
        subgraph "VM Simulation Environment"
            direction TB
            demo["demo.py"]:::vm
            firt["fir_tester.py"]:::vm
            fird["fir_data.py"]:::vm
            mainvm["main.py"]:::vm
            data["data.txt"]:::vm
            readme["README.md"]:::vm
        end

        clk -->|"Quartus Build"| buildFPGA["/ FPGA Build /"]:::build
        buildFPGA --> FPGAboard["[FPGA Board]"]:::hw
        mainc -->|"JTAG/UART"| FPGAboard
        latc -->|"JTAG/UART"| FPGAboard
        FPGAboard -->|"Data"| mainc
        demo -->|"Sim Data"| clk
    end

    %% Unity Client (green)
    subgraph "Unity Client"
        direction TB
        scenes["Scenes & Assets"]:::client
        sounds["Sounds"]:::client
        sprites["Sprites"]:::client
        scripts["C# Scripts"]:::client
        textui["TextMesh Pro UI"]:::client

        scenes --> Unity["Unity Engine"]:::client
        sounds --> Unity
        sprites --> Unity
        scripts --> Unity
        textui --> Unity
    end

    %% Game Server (orange)
    subgraph "Game Server Service"
        direction TB
        svc["Node.js/TypeScript Service"]:::server
        domain["Domain Model Classes"]:::server
        utils["Utilities"]:::server
        tests["Tests"]:::server
        devsim["Dev-only Simulation Scripts"]:::server
        DB["((Game DB))"]:::db
        AWS["(AWS EC2/Elastic Beanstalk)"]:::cloud

        svc --> domain
        domain --> utils
        utils --> DB
        svc -->|"WebSocket JSON"| DB
        svc -->|"WebSocket JSON"| Unity
        devsim -.-> domain
        AWS --> svc
    end

    %% Connections between subsystems
    Unity -->|"WebSocket JSON"| svc
    scripts -->|"Hardware Interface"| FPGAboard
    scripts -->|"Simulation API"| demo

    %% Click Events - FPGA
    click clk "https://github.com/sarachehab/gluttonio/blob/main/fpga/quartus/rtl/clk_divider.v"
    click debounce "https://github.com/sarachehab/gluttonio/blob/main/fpga/quartus/rtl/debounce.v"
    click fir "https://github.com/sarachehab/gluttonio/blob/main/fpga/quartus/rtl/fir.v"
    click top "https://github.com/sarachehab/gluttonio/blob/main/fpga/quartus/rtl/top.v"
    click tb1 "https://github.com/sarachehab/gluttonio/blob/main/fpga/quartus/tb/debounce_tb.cpp"
    click tb2 "https://github.com/sarachehab/gluttonio/blob/main/fpga/quartus/tb/testbench.h"
    click tb3 "https://github.com/sarachehab/gluttonio/blob/main/fpga/quartus/test.sh"
    click mainc "https://github.com/sarachehab/gluttonio/blob/main/fpga/software/app/main.c"
    click mainelf "https://github.com/sarachehab/gluttonio/blob/main/fpga/software/app/main.elf"
    click genapp "https://github.com/sarachehab/gluttonio/blob/main/fpga/software/generate_app.sh"
    click latc "https://github.com/sarachehab/gluttonio/blob/main/fpga/software/latency_app/main.c"
    click latelf "https://github.com/sarachehab/gluttonio/blob/main/fpga/software/latency_app/main.elf"
    click lattest "https://github.com/sarachehab/gluttonio/blob/main/fpga/software/latency_app/test.py"
    click demo "https://github.com/sarachehab/gluttonio/blob/main/fpga/vm/demo.py"
    click firt "https://github.com/sarachehab/gluttonio/blob/main/fpga/vm/fir_tester.py"
    click fird "https://github.com/sarachehab/gluttonio/blob/main/fpga/vm/fir_data.py"
    click mainvm "https://github.com/sarachehab/gluttonio/blob/main/fpga/vm/main.py"
    click data "https://github.com/sarachehab/gluttonio/blob/main/fpga/vm/data/data.txt"
    click readme "https://github.com/sarachehab/gluttonio/blob/main/fpga/vm/README.md"

    %% Click Events - Unity
    click scenes "https://github.com/sarachehab/gluttonio/blob/main/game/Assets/Scenes/Menu.unity"
    click sounds "https://github.com/sarachehab/gluttonio/blob/main/game/Assets/Sounds/food.mp3"
    click sprites "https://github.com/sarachehab/gluttonio/tree/main/game/Assets/sprites"
    click scripts "https://github.com/sarachehab/gluttonio/blob/main/game/Assets/scripts/ServerConnect.cs"
    click textui "https://github.com/sarachehab/gluttonio/tree/main/game/Assets/TextMesh Pro"

    %% Click Events - Server
    click svc "https://github.com/sarachehab/gluttonio/blob/main/server/server-side/src/index.ts"
    click domain "https://github.com/sarachehab/gluttonio/blob/main/server/server-side/classes/Game.ts"
    click utils "https://github.com/sarachehab/gluttonio/blob/main/server/server-side/utils/db.ts"
    click tests "https://github.com/sarachehab/gluttonio/blob/main/server/server-side/tests/Blob.test.ts"
    click devsim "https://github.com/sarachehab/gluttonio/blob/main/server/game_development/blob.js"

    %% Styles
    classDef rtl fill:#cce5ff,stroke:#3399ff
    classDef tb fill:#e6f2ff,stroke:#66b2ff
    classDef sw fill:#cceeff,stroke:#3399ff
    classDef vm fill:#e0f7fa,stroke:#00acc1
    classDef build fill:#b3e5fc,stroke:#0288d1
    classDef hw fill:#99ccff,stroke:#336699
    classDef client fill:#dcedc8,stroke:#8bc34a
    classDef server fill:#ffe0b2,stroke:#fb8c00
    classDef db fill:#eeeeee,stroke:#9e9e9e
    classDef cloud fill:#f5f5f5,stroke:#bdbdbd
```
