# vctt94/pong-bisonrelay architecture

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

- Interactive diagram: https://gitdiagram.com/vctt94/pong-bisonrelay
- Repository: https://github.com/vctt94/pong-bisonrelay

## Overview

##### Overall Project Type and Purpose
- The project is a full-stack application centered around a Pong game. It not only implements the game logic (in ponggame) and matchmaking (waiting rooms) but also integrates a betting system that uses real DCR transactions (via Bison Relay).
- It provides two main UI options—a terminal-based client (using BubbleTea) and a Flutter-based UI—while the backend bot (pongbot) and gRPC API support all the gaming, matchmaking, and payment functions.

##### Primary Components
a. UI Clients:
- Terminal UI Client (cmd/pongclient) – A lightweight client that connects to the server via gRPC.
- Flutter UI Client (pongui) – A full-feature Flutter-based client offering richer graphics and interactions.
b. Game Server / Bot:
- Pongbot (cmd/pongbot) – Acts as the game server and betting engine. It handles game sessions, waiting room logic, and processes transactions.
- Server Components (server folder) – Handles HTTP and RPC endpoints, betting logic, and possibly database interactions (serverdb subcomponent).
c. Game Engine:
- Core Game Logic (ponggame) – Contains the physics, player handling, and overall game engine that implements the Pong gameplay.
d. gRPC API Layer:
- gRPC Definitions and APIs (pongrpc) – Provides the protocol buffer files and generated code, enabling RPC communication between clients (or bot) and the game server.
e. Payment and Betting Integration:
- Bison Relay RPC Client Integration – Although external to this project, the configuration and dependency for managing DCR betting transactions (visible in the README configuration examples) should be noted.
f. Shared Libraries:
- Golib and Golibbuilder – These act as utility and helper libraries for command handling, logging, profiling, and cross-platform support.

##### Relationships and Data Flow
- The gRPC service (pongrpc) acts as a central hub that communicates with the game engine (ponggame) to synchronize game state, control matchmaking (waiting room logic), and trigger game start when both players are ready.
- Pongbot receives tipping inputs from clients to set betting amounts and then, using the Bison Relay RPC client integration, processes secure DCR transactions. This betting flow should be shown as a secure external link to the Bison Relay client/payment system.
- The server components and “serverdb” modules interact with the game engine and are used for configuration, logging, and potentially persistence, so include these connections.
- Additionally, highlight that there is logic for notifications (client/notifications.go and other messaging components) that feeds back to the UI clients.

##### Architectural Patterns and Design Principles
- Clearly separate the “frontend” components (terminal UI and Flutter UI) from the “backend service” components (pongbot, server logic, game engine, and gRPC API).
- Modularity by displaying shared libraries (golib) that assist multiple components.
- Pattern of dependency injection between components where configuration files are auto-generated on first run – details that speak to configuration flexibility.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI1["Terminal UI Client (Go)"]:::frontend
        UI2["Flutter UI Client (Flutter)"]:::frontend
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        RPC["gRPC API Service (Go)"]:::backend
        Bot["Pongbot Server (Game Server & Betting Engine) (Go)"]:::backend
        Engine["Game Engine (Pong Game Logic) (Go)"]:::backend
        ServerComp["Server Components (HTTP handlers & betting logic) (Go)"]:::backend
        subgraph "Shared Libraries"
            Lib["golib"]:::library
            LibBuilder["golibbuilder"]:::library
        end
    end

    %% External Integrations
    subgraph "External Integrations"
        Payment["External Payment System (Bison Relay RPC Client)"]:::integration
    end

    %% Connections between layers and components
    UI1 -->|"calls"| RPC
    UI2 -->|"calls"| RPC

    RPC <-->|"sync"| Bot
    Bot <-->|"controls"| Engine

    Bot -->|"logs/config"| ServerComp
    ServerComp -->|"notify"| UI1
    ServerComp -->|"notify"| UI2

    Bot -->|"process payment"| Payment

    Lib -.-> Bot
    LibBuilder -.-> RPC

    %% Click Events
    click UI1 "https://github.com/vctt94/pong-bisonrelay/tree/master/cmd/pongclient"
    click UI2 "https://github.com/vctt94/pong-bisonrelay/tree/master/pongui/pongui"
    click Bot "https://github.com/vctt94/pong-bisonrelay/tree/master/cmd/pongbot"
    click Engine "https://github.com/vctt94/pong-bisonrelay/tree/master/ponggame"
    click RPC "https://github.com/vctt94/pong-bisonrelay/tree/master/pongrpc"
    click ServerComp "https://github.com/vctt94/pong-bisonrelay/tree/master/server"
    click Lib "https://github.com/vctt94/pong-bisonrelay/tree/master/golib"
    click LibBuilder "https://github.com/vctt94/pong-bisonrelay/tree/master/golibbuilder"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#FFCCCB,stroke:#000,stroke-width:2px;
    classDef integration fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef library fill:#FFFACD,stroke:#000,stroke-width:2px;
```
