# hxtnv/fuseball architecture

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

## Overview

##### Project Type & Purpose
- This is a full-stack multiplayer game. The client is a modern React-based web application that handles the UI, including game overlays and p5.js sketches for the game rendering.
- The server implements the core game logic using WebSockets for real-time multiplayer communication, lobby management, game loop updates and even OAuth (with providers like Discord and Google) for account creation.
- Other features include in-game chat and news feeds, with planned improvements for leaderboards and tournament modes.

##### Main Components
- Client Side:
- UI Components: Organized into common (button, input, skeleton, switcher), domain-specific (footer, navbar, news, player preview), modals (disconnected, game-loader, sign-in), and lobby components.
- Context & Hooks: Managing game and WebSocket states, modal functionalities, and utility hooks for mobile and horizontal view support.

- Server Side:
- WebSocket Server & Game Loop: Located in “server/src/websocket-server.ts” and “server/src/lib/game-loop.ts” along with a series of helper functions and a dedicated “lobby-manager” for managing player lobbies (e.g., creation, updates, state management, player movement).
- OAuth and Authentication: The “server/src/features/oauth” subdirectory shows integrations with Discord and Google for authentication.
- REST & Other Business Logic: Additional features like news handling and self-profile functions.
- Data Management: Use of Prisma (in “server/prisma/schema.prisma”) for modeling database interactions and a logger and utility functions for supporting operations.

##### Relationships & Interactions
- Client ↔ Server:
- Bi-directional communication via WebSockets that facilitates real-time game state updates, in-game chat, and lobby interactions.
- REST API endpoints that might be used for account creation/authentication or fetching news.
- In the server, detail the flow:
- Incoming WebSocket messages are handled by dedicated handlers (connection-handler, message-handler).
- The game loop and lobby manager coordinate game ticks, update player positions, verify scoring (goal detection), and manage chats.
- Authentication flows through the OAuth modules and associated helper functions.
- Additionally, the client’s use of context providers (e.g., game.context, websocket.context) should be shown as a layer managing state and communication between UI components and the networking layer.

##### Architectural Patterns and Technologies
- Component-based architecture for the client leveraging React and Vite for the build.
- Separation between presentation (UI components/layout) and domain logic (game state and interaction hooks).
- Real-time bi-directional communication via a custom WebSocket server on the backend.
- Use of modern TypeScript throughout both client and server enhances type safety and maintainability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client Side"
        UI["UI Components"]:::client
        COMMON["Common Components"]:::client
        DOMAIN["Domain-specific Components"]:::client
        MODALS["Modals"]:::client
        LOBBY_UI["Lobby Components"]:::client
        GS["Game Sketch (p5.js)"]:::client
        CONTEXT["Context Providers"]:::client
        HOOKS["Hooks"]:::client
        ASSETS["Assets & Styling"]:::client

        UI --> COMMON
        UI --> DOMAIN
        UI --> MODALS
        UI --> LOBBY_UI
    end

    %% Server Side
    subgraph "Server Side"
        WS["WebSocket Server"]:::server
        GL["Game Loop"]:::server
        LM["Lobby Manager"]:::server
        OAUTH["OAuth Integration"]:::server
        NEWS["News Handling"]:::server
        SELF["Self Profile Functions"]:::server

        subgraph "Data Management"
            PRISMA["Prisma Schema"]:::database
            LOGGER["Logger"]:::database
            UTILS["Utils"]:::database
        end
    end

    %% Client to Server communications
    CONTEXT -->|"sendsUpdates"| WS
    GS -->|"sendsActions"| WS

    %% Server internal flows
    WS -->|"gameCommands"| GL
    WS -->|"lobbyCommands"| LM
    WS -->|"authRequests"| OAUTH
    WS -->|"newsRequests"| NEWS
    WS -->|"profileRequests"| SELF

    %% Server to Data Management interactions
    GL -->|"persistState"| PRISMA
    LM -->|"logEvents"| LOGGER
    OAUTH -->|"useUtils"| UTILS

    %% Server back to Client state updates
    WS -->|"stateUpdates"| CONTEXT

    %% Styles
    classDef client fill:#add8e6,stroke:#0000ff,color:#000;
    classDef server fill:#90ee90,stroke:#008000,color:#000;
    classDef database fill:#f08080,stroke:#ff0000,color:#000;

    %% Click Events - Client Components
    click COMMON "https://github.com/hxtnv/fuseball/tree/master/client/src/components/common/"
    click DOMAIN "https://github.com/hxtnv/fuseball/tree/master/client/src/components/domain/"
    click MODALS "https://github.com/hxtnv/fuseball/tree/master/client/src/components/modals/"
    click LOBBY_UI "https://github.com/hxtnv/fuseball/tree/master/client/src/components/lobby/"
    click GS "https://github.com/hxtnv/fuseball/tree/master/client/src/views/game-sketch/"
    click CONTEXT "https://github.com/hxtnv/fuseball/tree/master/client/src/context/"
    click HOOKS "https://github.com/hxtnv/fuseball/tree/master/client/src/hooks/"
    click ASSETS "https://github.com/hxtnv/fuseball/tree/master/client/src/assets/"

    %% Click Events - Server Components
    click WS "https://github.com/hxtnv/fuseball/blob/master/server/src/websocket-server.ts"
    click GL "https://github.com/hxtnv/fuseball/blob/master/server/src/lib/game-loop.ts"
    click LM "https://github.com/hxtnv/fuseball/tree/master/server/src/lib/lobby-manager/"
    click OAUTH "https://github.com/hxtnv/fuseball/tree/master/server/src/features/oauth/"
    click NEWS "https://github.com/hxtnv/fuseball/blob/master/server/src/features/news.ts"
    click SELF "https://github.com/hxtnv/fuseball/blob/master/server/src/features/self.ts"
    click PRISMA "https://github.com/hxtnv/fuseball/blob/master/server/prisma/schema.prisma"
    click LOGGER "https://github.com/hxtnv/fuseball/blob/master/server/src/lib/logger.ts"
    click UTILS "https://github.com/hxtnv/fuseball/blob/master/server/src/lib/utils.ts"
```
