# leweyg/freedgames architecture

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

- Interactive diagram: https://gitdiagram.com/leweyg/freedgames
- Repository: https://github.com/leweyg/freedgames

## Overview

##### Project Type and Purpose
- This repository houses two related projects—Freed Go and Shuzzle—each provided in two incarnations:
a. A modern, pure client-side JavaScript/WebGL (three.js) “v2” web app under docs/
b. A “v1” C++ OpenGL/GLUT desktop implementation under cpp/ (and mirrored in v1/ JSON assets)
- Both web apps are static sites (HTML/CSS/JS), served from a CDN or static host, which connect to a Google-based backend for cloud storage and real-time multiplayer.

##### File-Structure Analysis
Top level:
- cpp/Shuzzle/Shuzzle/… → The complete C++ legacy codebase (core logic, rendering via GLUT/OpenGL, OS bindings, IO, networking)
- docs/FreedGo/… & docs/Shuzzle/… → HTML, CSS, JS for the v2 web clients
- v1/… → JSON asset exports of boards/puzzles and a copy of the C++ code for reference
- Static root files: index.html, README.md, LICENSE

##### README Insights
- Confirms static, client-only JavaScript apps using embedded three.js
- Mentions “Google server” for cloud-storage and multiplayer room management
- Legacy C++ code used as reference, with board definitions exported in JSON

a. Main Components
1. Static Web Host
- Serves docs/ content (HTML/CSS/JS & JSON assets)
2. Web Client (browser)
- Presentation Layer: index.html + main.css
- Renderer: three.js engine
- Game Logic: freed_go.js or shuzzle_core.js + game modules (FreedGo boards loader, puzzle logic, UI controls)
- Data Layer: JSON board/puzzle definitions (docs/.../*.json)
- Network Layer: JS code invoking Google REST/WebSocket APIs
3. Cloud Backend (Google)
- Authentication & user/session management
- Real-time database or pub/sub for multiplayer rooms
- Cloud storage for saved games
4. (Legacy) Desktop C++ App
- Core: GoGame.cpp / ShuzzleGame.cpp + core modules (Board, Utils, matrixclass, pnt, gennet)
- Graphics: GoCore_GLUT.cpp, ShuzzleCore_GLUT.cpp, etc.
- OS Binding: OSBinding*.cpp for Win32, SDL, GLUT
- I/O & Networking: IOUtils.cpp, LCNet.h

b. Relationships and Interactions
- Browser ←→ Static Host: HTTP GET for HTML/CSS/JS and JSON assets
- Browser ←→ Google Backend: REST or WebSocket calls for cloud storage & multiplayer sync
- JS Game Logic invokes three.js for rendering each frame
- Legacy C++ app is standalone: event loop → render via OpenGL → user input via GLUT/SDL → optional LCNet for network

c. Architectural Patterns & Design Principles
- Web version: Client-Side MVC/MVVM
- Model: JSON boards + in-memory game state
- View: three.js scene graph + DOM UI
- Controller: input handlers + game logic modules
- Clear separation of concerns: rendering (three.js) vs. logic (game modules) vs. data (JSON) vs. network
- Static hosting plus thin client—no custom backend code in this repo
- Legacy desktop: modular C++ code layering core logic, graphics, OS binding, networking

d. Key Technologies
- three.js (WebGL rendering)
- Plain JavaScript modules (no bundler shown)
- JSON for board definitions
- Google Cloud services (likely Firebase Realtime Database or Firestore + Auth)
- C++17 (or earlier) with OpenGL/GLUT, SDL, Win32

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Static Hosting"
        StaticHost["Static Web Host"]:::external
    end

    subgraph "Web Client (Browser)"
        subgraph "Presentation Layer"
            DocsRoot["docs/index.html"]:::frontend
            FGIndex["FreedGo index.html"]:::frontend
            FGMainCSS["FreedGo main.css"]:::frontend
            SHIndex["Shuzzle index.html"]:::frontend
            SHMainCSS["Shuzzle main.css"]:::frontend
        end
        subgraph "Renderer"
            FGThree["FreedGo three.js"]:::frontend
            SHThree["Shuzzle three.js"]:::frontend
        end
        subgraph "Game Logic"
            FGLogic["freed_go.js"]:::frontend
            FGBoardsAll["boards_all.js"]:::frontend
            SHCore["shuzzle_core.js"]:::frontend
            SHGame["shuzzle_game.js"]:::frontend
            SHBoardsJS["shuzzle_boards.js"]:::frontend
        end
        subgraph "Data Layer"
            FGBoardsJSON["boards/*.go_3d.json"]:::frontend
            FGMobius["mobius.go_3d.json.js"]:::frontend
        end
        subgraph "Network Layer"
            Network["JS Google REST/WebSocket"]:::frontend
        end
    end

    subgraph "Google Cloud Backend"
        Auth["Authentication & Session"]:::external
        RealtimeDB["Realtime DB / PubSub"]:::external
        Storage["Cloud Storage"]:::external
    end

    subgraph "Legacy Desktop C++ App"
        subgraph "Core Logic"
            GoGame["GoGame.cpp"]:::legacy
            ShuzzleGame["ShuzzleGame.cpp"]:::legacy
            BoardCPP["Board.cpp"]:::legacy
            UtilsH["Utils.h"]:::legacy
            MatrixCPP["matrixclass.cpp"]:::legacy
            PntCPP["pnt.cpp"]:::legacy
            GennetH["gennet.h"]:::legacy
        end
        subgraph "Graphics (OpenGL/GLUT)"
            GoCoreGLUT["GoCore_GLUT.cpp"]:::legacy
            ShuzzleCoreGLUT["ShuzzleCore_GLUT.cpp"]:::legacy
            GraphicsTest["GraphisTestCore_GLUT.cpp"]:::legacy
            InvasionGLUT["InvasionCore_GLUT.cpp"]:::legacy
            MineGLUT["MineCore_GLUT.cpp"]:::legacy
        end
        subgraph "OS Bindings"
            OSBinding["OSBinding.cpp"]:::legacy
            SDLBinding["OSBinding_SDL.cpp"]:::legacy
            Win32Binding["OSBinding_Win32.cpp"]:::legacy
        end
        subgraph "I/O & Networking"
            IOUtils["IOUtils.cpp"]:::legacy
            LCNetH["LCNet.h"]:::legacy
        end
        mainCPP["main.cpp"]:::legacy
    end

    StaticHost -->|"HTTP GET"| DocsRoot
    StaticHost -->|"HTTP GET"| FGIndex
    StaticHost -->|"HTTP GET"| SHIndex

    FGBoardsJSON -->|"load JSON"| FGLogic
    FGMobius -->|"load JSON"| FGLogic
    SHBoardsJS -->|"embedded boards"| SHCore

    FGLogic -->|"render()"| FGThree
    SHCore -->|"render()"| SHThree

    Network -->|"REST/WebSocket"| Auth
    Network -->|"Real-time sync"| RealtimeDB
    Network -->|"Storage API"| Storage

    mainCPP --> GoGame
    mainCPP --> ShuzzleGame
    mainCPP --> GoCoreGLUT
    mainCPP --> OSBinding
    mainCPP --> IOUtils

    click StaticHost "https://github.com/leweyg/freedgames/tree/main/docs/"
    click DocsRoot "https://github.com/leweyg/freedgames/blob/main/docs/index.html"
    click FGIndex "https://github.com/leweyg/freedgames/blob/main/docs/FreedGo/index.html"
    click FGMainCSS "https://github.com/leweyg/freedgames/blob/main/docs/FreedGo/main.css"
    click SHIndex "https://github.com/leweyg/freedgames/blob/main/docs/Shuzzle/index.html"
    click SHMainCSS "https://github.com/leweyg/freedgames/blob/main/docs/Shuzzle/main.css"
    click FGThree "https://github.com/leweyg/freedgames/blob/main/docs/FreedGo/three.js"
    click SHThree "https://github.com/leweyg/freedgames/blob/main/docs/Shuzzle/three.js"
    click FGLogic "https://github.com/leweyg/freedgames/blob/main/docs/FreedGo/freed_go.js"
    click FGBoardsAll "https://github.com/leweyg/freedgames/blob/main/docs/FreedGo/boards_all.js"
    click SHCore "https://github.com/leweyg/freedgames/blob/main/docs/Shuzzle/shuzzle_core.js"
    click SHGame "https://github.com/leweyg/freedgames/blob/main/docs/Shuzzle/shuzzle_game.js"
    click SHBoardsJS "https://github.com/leweyg/freedgames/blob/main/docs/Shuzzle/shuzzle_boards.js"
    click FGBoardsJSON "https://github.com/leweyg/freedgames/tree/main/docs/FreedGo/boards/"
    click FGMobius "https://github.com/leweyg/freedgames/blob/main/docs/FreedGo/mobius.go_3d.json.js"
    click GoGame "https://github.com/leweyg/freedgames/blob/main/cpp/Shuzzle/Shuzzle/GoGame.cpp"
    click ShuzzleGame "https://github.com/leweyg/freedgames/blob/main/cpp/Shuzzle/Shuzzle/ShuzzleGame.cpp"
    click BoardCPP "https://github.com/leweyg/freedgames/blob/main/cpp/Shuzzle/Shuzzle/Board.cpp"
    click UtilsH "https://github.com/leweyg/freedgames/blob/main/cpp/Shuzzle/Shuzzle/Utils.h"
    click MatrixCPP "https://github.com/leweyg/freedgames/blob/main/cpp/Shuzzle/Shuzzle/matrixclass.cpp"
    click PntCPP "https://github.com/leweyg/freedgames/blob/main/cpp/Shuzzle/Shuzzle/pnt.cpp"
    click GennetH "https://github.com/leweyg/freedgames/blob/main/cpp/Shuzzle/Shuzzle/gennet.h"
    click GoCoreGLUT "https://github.com/leweyg/freedgames/blob/main/cpp/Shuzzle/Shuzzle/GoCore_GLUT.cpp"
    click ShuzzleCoreGLUT "https://github.com/leweyg/freedgames/blob/main/cpp/Shuzzle/Shuzzle/ShuzzleCore_GLUT.cpp"
    click GraphicsTest "https://github.com/leweyg/freedgames/blob/main/cpp/Shuzzle/Shuzzle/GraphisTestCore_GLUT.cpp"
    click InvasionGLUT "https://github.com/leweyg/freedgames/blob/main/cpp/Shuzzle/Shuzzle/InvasionCore_GLUT.cpp"
    click MineGLUT "https://github.com/leweyg/freedgames/blob/main/cpp/Shuzzle/Shuzzle/MineCore_GLUT.cpp"
    click OSBinding "https://github.com/leweyg/freedgames/blob/main/cpp/Shuzzle/Shuzzle/OSBinding.cpp"
    click SDLBinding "https://github.com/leweyg/freedgames/blob/main/cpp/Shuzzle/Shuzzle/OSBinding_SDL.cpp"
    click Win32Binding "https://github.com/leweyg/freedgames/blob/main/cpp/Shuzzle/Shuzzle/OSBinding_Win32.cpp"
    click IOUtils "https://github.com/leweyg/freedgames/blob/main/cpp/Shuzzle/Shuzzle/IOUtils.cpp"
    click LCNetH "https://github.com/leweyg/freedgames/blob/main/cpp/Shuzzle/Shuzzle/LCNet.h"
    click mainCPP "https://github.com/leweyg/freedgames/blob/main/cpp/Shuzzle/Shuzzle/main.cpp"

    classDef frontend fill:#D0E8FF,stroke:#0066CC
    classDef external fill:#DFFFE0,stroke:#33AA00
    classDef legacy fill:#EFEFEF,stroke:#777777
```
