# hexafield/catan architecture

> Architecture diagram of the GitHub repository hexafield/catan, 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/hexafield/catan
- Repository: https://github.com/hexafield/catan

## Overview

##### Project Type & Purpose
- This project is a full-stack game application that implements a demo version of the board game Catan in an XR (extended reality) context.
- It is designed for interactive gameplay using a hex grid board, dice rolls, settlement placements, and other game mechanics.
- The README mentions a “P2P Signaling server” and “client connectivity,” so there is a networked component with a dedicated backend signaling server communicating with clients.
- The main use case is to allow players to interact in a 3D/VR/AR environment—though some planned features (like VR mode, AR tabletop mode) are pending.

##### File Structure for Architectural Clues
- Top-Level Files:
- server.ts: Implements the server-side (likely the signaling server for peer-to-peer connection).
- client.js, index.html, manifest.json: Entry points for the web client.
- package.json, tsconfig.json, vite.config.ts, tailwind.config.js: Indicate use of TypeScript, Vite build tooling, and Tailwind for styling.
- Directories:
- src: Contains the React (or JSX-based) application code for game screens (e.g., GamePage.tsx, main.tsx) and several game systems.
▪ Game logic is modularized into subdirectories:
- game: e.g., DiceRollSystem.tsx, GameSystem.tsx
- hexes: e.g., HexagonGridSystem.tsx (with functions and constants)
- player: PlayerSystem.tsx
- resources: ResourceSystem.tsx
- structures: A set of files dealing with structure placement, purchase, and functions.
- public: Contains static assets, including loader decoders for various 3D assets (e.g., Basis, Draco) and worker scripts used for asynchronous BVH generation and 3D computations.
- tests: Contains a dummy test, indicating initial testing setup.
- .github/workflows: CI/CD pipelines for deployment and builds.
- These components suggest a design that separates the game’s rendering/UI logic, core gameplay systems, static asset delivery and asynchronous 3D computation workers, plus a minimal backend signaling server.

##### Core Components
- Client Application
- UI/Presentation Layer:
▪ index.html that bootstraps client.js and further loads the React components within src (e.g., GamePage.tsx, various UI components for dice roll, settlement placements, etc.)
- Game Systems Layer:
▪ Game System (GameSystem.tsx) coordinating game flow.
▪ Hexagon Grid System (HexagonGridSystem.tsx) with its helper functions/constants.
▪ Dice Roll System (DiceRollSystem.tsx), Player System (PlayerSystem.tsx), Resource System (ResourceSystem.tsx), and Structure Systems (StructurePlacementSystem.tsx, StructurePurchaseSystem.tsx, StructureSystem.tsx). Each module handles specific game mechanics.
- Supporting Subsystems:
▪ Integration of Web Workers (located under public/workers) handling tasks like BVH generation and 3D mesh processing.
▪ Loader Decoders (in public/loader_decoders) for assets in different formats (Basis, Draco) that are used to load and decode 3D models.
- Build & Configuration:
▪ Vite configuration, Tailwind CSS integration, and TypeScript strictness impacting how the game modules are built and styled.

- Server / P2P Signaling Layer
- Server.ts acts as the signaling server facilitating P2P connectivity and game session management (e.g., initiating game rounds, dice roll synchronization, resource updates).

##### Relationships and Data Flow
- User interactions (e.g., dice roll, structure placement) triggering game logic changes.
- Interactions between the Game Systems and asynchronous workers (the public/workers scripts). Indicate that computationally heavy tasks (like BVH generation) are offloaded.
- A flow for static asset loading from the Public directory (both assets and WASM decoders) into the Client.
- Optionally, denote the build/deployment pipeline from the GitHub workflows as a separate process that feeds into both the client and server deployments.

##### Architectural Patterns & Design Principles
- Separation of concerns:
- Client side handles rendering, user interactions, and game logic modularization across several systems.
- Server side deals solely with networking and P2P connectivity.
- Worker scripts handle offloading computational tasks (e.g., 3D processing) ensuring a responsive UI.
- Use modular design – each game subsystem is represented as an independent component. Their integration points (via events, callbacks, or direct function calls) should be illustrated.
- Leverage client-driven workflows: The use of Vite, Tailwind, and Typed React (tsx) suggests modern web development practices that modularize UI and business logic.

##### Relevant Technologies, Frameworks & Libraries
- Vite (highlighted in configuration files)
- TypeScript and React (inferred from .tsx files)
- Tailwind CSS (as per tailwind.config.js for UI styling)
- WASM modules along with Web Workers for optimal 3D asset processing (public/loader_decoders and public/workers)
- P2P signaling possibly using WebRTC or similar mechanisms as suggested by server.ts

- Client Application: subdivided into UI Layer and Game Logic Layer.
- Game Systems modules: DiceRoll, HexagonGrid, Player, Resource, Structures.
- Asynchronous Processes: Web Workers and WASM asset loaders.
- Server (P2P/Signaling): Representing server.ts.
- Data flow among UI, game systems, asset loaders, and server.
- Communication protocols (e.g., signaling for P2P connections).
- Integration points for configuration and build pipelines (optional but useful for deployment context).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Application
    subgraph "Client Application"
        %% UI/Presentation Layer
        subgraph "UI/Presentation Layer"
            HTML["Client HTML"]:::ui
            ClientJS["Client JS"]:::ui
            GamePage["GamePage Component"]:::ui
        end

        %% Game Systems Layer
        subgraph "Game Systems Layer"
            GameSystem["Game System"]:::game
            DiceRoll["Dice Roll System"]:::game
            HexGrid["Hexagon Grid System"]:::game
            PlayerSystem["Player System"]:::game
            ResourceSystem["Resource System"]:::game
            StructurePlacement["Structure Placement"]:::game
            StructurePurchase["Structure Purchase"]:::game
            StructureSystem["Structure System"]:::game
            StructureFunctions["Structure Functions"]:::game
        end

        %% Supporting Subsystems
        subgraph "Supporting Subsystems"
            subgraph "Loader Decoders"
                BasisDecoder["Basis Decoder"]:::asset
                DracoDecoder["Draco Decoder"]:::asset
            end
            subgraph "Web Workers"
                BVHWorker["BVH Worker"]:::worker
                MeshWorker["3D Mesh Worker"]:::worker
            end
        end
    end

    %% Backend / P2P Signaling Layer
    subgraph "Backend"
        SignalingServer["P2P Signaling Server"]:::server
    end

    %% Relationships and Data Flow
    HTML -->|"loads"| ClientJS
    ClientJS -->|"bootstraps"| GamePage
    GamePage -->|"initiates_game"| GameSystem

    GameSystem -->|"orchestrates"| DiceRoll
    GameSystem -->|"orchestrates"| HexGrid
    GameSystem -->|"orchestrates"| PlayerSystem
    GameSystem -->|"orchestrates"| ResourceSystem
    GameSystem -->|"orchestrates"| StructurePlacement
    GameSystem -->|"orchestrates"| StructurePurchase
    GameSystem -->|"orchestrates"| StructureSystem
    StructureSystem -->|"utilizes"| StructureFunctions

    GameSystem -->|"offloads_compute"| BVHWorker
    GameSystem -->|"offloads_compute"| MeshWorker

    GamePage -->|"loads_assets"| BasisDecoder
    GamePage -->|"loads_assets"| DracoDecoder

    GameSystem -->|"syncs_state"| SignalingServer

    %% Click Events
    click HTML "https://github.com/hexafield/catan/blob/dev/index.html"
    click ClientJS "https://github.com/hexafield/catan/blob/dev/client.js"
    click GamePage "https://github.com/hexafield/catan/blob/dev/src/GamePage.tsx"

    click GameSystem "https://github.com/hexafield/catan/blob/dev/src/game/GameSystem.tsx"
    click DiceRoll "https://github.com/hexafield/catan/blob/dev/src/game/DiceRollSystem.tsx"
    click HexGrid "https://github.com/hexafield/catan/blob/dev/src/hexes/HexagonGridSystem.tsx"
    click PlayerSystem "https://github.com/hexafield/catan/blob/dev/src/player/PlayerSystem.tsx"
    click ResourceSystem "https://github.com/hexafield/catan/blob/dev/src/resources/ResourceSystem.tsx"
    click StructurePlacement "https://github.com/hexafield/catan/blob/dev/src/structures/StructurePlacementSystem.tsx"
    click StructurePurchase "https://github.com/hexafield/catan/blob/dev/src/structures/StructurePurchaseSystem.tsx"
    click StructureSystem "https://github.com/hexafield/catan/blob/dev/src/structures/StructureSystem.tsx"
    click StructureFunctions "https://github.com/hexafield/catan/blob/dev/src/structures/StructureFunctions.ts"

    click BasisDecoder "https://github.com/hexafield/catan/blob/dev/public/loader_decoders/basis/basis_transcoder.js"
    click DracoDecoder "https://github.com/hexafield/catan/blob/dev/public/loader_decoders/draco_decoder.js"
    click BVHWorker "https://github.com/hexafield/catan/blob/dev/public/workers/generateBVHAsync.worker.js"
    click MeshWorker "https://github.com/hexafield/catan/blob/dev/public/workers/three-mesh-bvh.umd.cjs.js"

    click SignalingServer "https://github.com/hexafield/catan/blob/dev/server.ts"

    %% Styles
    classDef ui fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef game fill:#ABEBC6,stroke:#1D8348,stroke-width:2px;
    classDef worker fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef server fill:#F5B7B1,stroke:#CB4335,stroke-width:2px;
    classDef asset fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
```
