# hmajid2301/banterbus architecture

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

- Interactive diagram: https://gitdiagram.com/hmajid2301/banterbus
- Repository: https://github.com/hmajid2301/banterbus

## Overview

##### Project Type & Purpose
- Banter Bus is a full-stack web application for a party game.
- The project implements game logic and services (lobby management, player handling, questioning, rounds, etc.) in Go while rendering the frontend via templated HTML with minimal JavaScript (htmx and alpinejs).
- It uses websockets for real-time communication and supports Pub/Sub (with Redis) and a Postgres database for persistence.

##### Analyzing the File Structure
- The top-level directories and files (such as README.md, Taskfile.yml, docker-compose.yml, and Nix related files) indicate integrated development, deployment via containers and CI/CD (GitLab pipelines, pre-commit hooks, etc.).
- The “internal” directory contains multiple subdirectories:
– “internal/service” houses the game-specific business logic (lobbyservice, playerservice, questionservice, roundservice, etc.) along with tests.
– “internal/transport” is split into “http” (for standard HTTP endpoints, health checks, game, and question handlers) and “websockets” (handling live game interactions, lobby, players, rounds).
– “internal/store” manages database interactions (with PostgreSQL) and pub/sub logic, which is critical for game state updates.
- Additional directories like “static” host assets like CSS, JS, fonts, and images.

##### Key Components
a. Frontend Client:
– User interface rendered by templating (internal/views) and served as static assets.
– Uses htmx for dynamic behavior with alpinejs for lightweight interactivity.
– All assets are bundled under “static” (CSS, JS, fonts, images) and then enhanced via Tailwind CSS.
b. Backend Server:
– Built in Go, the core server code (main.go) handles HTTP requests and upgrades connections for websockets.
– Components in the “internal” folder are split into:
- Configuration and Logging (internal/config, internal/logging)
- Service Layer (internal/service, which includes game logic components like lobby, player, rounds, questions, randomizer)
- Transport Layers:
– HTTP Endpoints (internal/transport/http) handling REST-like and templated page requests.
– Websocket endpoints (internal/transport/websockets) handling real-time game communication.
- Data Store Layer (internal/store) incorporating:
– Database interactions with Postgres (internal/store/db)
– Pub/Sub mechanisms (internal/store/pubsub) likely backed by Redis.
- Telemetry and Observability (internal/telemetry) for metrics and state monitoring.
c. Infrastructure & DevOps:
– Docker configuration (docker/, docker-compose.yml) for service containers (including Prometheus, Tempo, Loki, Otel Collector).
– Nix Flakes and associated files (flake.nix, shell.nix, default.nix, gomod2nix.toml) ensuring reproducibility.
– CI/CD integration through GitLab pipeline files (.gitlab-ci.yml) and Taskfile runner (Taskfile.yml).

##### Relationships & Data Flow
- Directional flows:
– Clients (browsers) making HTTP requests and establishing websocket connections to the Go backend.
– The server’s HTTP layer responds with pages, while the Websocket layer manages real-time game updates.
– Game services interact with the Data Store for transactional operations (via SQL queries and migrations found in internal/store/db/sqlc/migrations), and they also communicate with the Pub/Sub system for asynchronous events (e.g., game state updates).
– Telemetry components collect and report operational metrics.
- Internal dependencies (e.g., service layer using helper functions, references between different game services) and outward dependencies (database, Redis, external monitoring).

##### Architectural Patterns & Design Principles
- Modularity – separate packages for game logic, transport, storage, and views.
- Separation of Concerns – clear delineation between the UI (templated views/static assets) and backend processing (services & transport layers).
- Real-Time Communication – leveraging websockets alongside traditional HTTP.
- DevOps Focus – reproducible builds through Nix, containerization via Docker, and CI/CD pipelines.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        UB("User Browser"):::frontend
        T("Templates"):::frontend
        SA("Static Assets"):::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BS("Backend Server Core"):::backend
        CL("Configuration"):::backend
        LG("Logging"):::backend
        subgraph "Transport Layers"
            HTTP("HTTP Endpoints"):::backend
            MW("HTTP Middleware"):::backend
            WS("WebSocket Endpoints"):::backend
        end
        GS("Game Service Layer"):::backend
        subgraph "Data Store Layer"
            DB("Database (Postgres)"):::backend
            PS("Pub/Sub Manager"):::backend
        end
        TEL("Telemetry & Observability"):::backend
    end

    %% Infrastructure & DevOps
    subgraph "Infrastructure & DevOps"
        DC("Docker Configuration"):::infra
        CICD("CI/CD Pipeline"):::infra
        NIX("Dev Setup (Nix)"):::infra
    end

    %% Connections between Frontend and Backend
    UB -->|"HTTPRequest"| HTTP
    UB -->|"WSConnection"| WS
    HTTP -->|"uses"| MW
    MW -->|"processes"| GS
    WS -->|"relays"| GS
    GS -->|"queries"| DB
    GS -->|"pubsub"| PS
    GS -->|"metrics"| TEL

    %% Backend core dependencies
    BS --> HTTP
    BS --> WS
    BS --> GS
    BS --> TEL
    CL --> BS
    LG --> BS

    %% Serving Templates and Static Assets
    HTTP -->|"renders"| T
    HTTP -->|"serves"| SA
    T -->|"delivers"| UB
    SA -->|"delivers"| UB

    %% Infrastructure deployment connections
    DC --> BS
    CICD --> BS
    NIX --> BS

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef backend fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef infra fill:#FFCDD2,stroke:#333,stroke-width:2px;

    %% Click Events
    click T "https://github.com/hmajid2301/banterbus/tree/main/internal/views/"
    click SA "https://github.com/hmajid2301/banterbus/tree/main/static/"
    click BS "https://github.com/hmajid2301/banterbus/blob/main/main.go"
    click CL "https://github.com/hmajid2301/banterbus/blob/main/internal/config/config.go"
    click LG "https://github.com/hmajid2301/banterbus/blob/main/internal/logging/logging.go"
    click GS "https://github.com/hmajid2301/banterbus/tree/main/internal/service/"
    click HTTP "https://github.com/hmajid2301/banterbus/tree/main/internal/transport/http/"
    click MW "https://github.com/hmajid2301/banterbus/tree/main/internal/transport/http/middleware/"
    click WS "https://github.com/hmajid2301/banterbus/tree/main/internal/transport/websockets/"
    click DB "https://github.com/hmajid2301/banterbus/tree/main/internal/store/db/"
    click PS "https://github.com/hmajid2301/banterbus/tree/main/internal/store/pubsub/"
    click TEL "https://github.com/hmajid2301/banterbus/tree/main/internal/telemetry/"
    click DC "https://github.com/hmajid2301/banterbus/tree/main/docker/"
    click CICD "https://github.com/hmajid2301/banterbus/blob/main/.gitlab-ci.yml"
    click NIX "https://github.com/hmajid2301/banterbus/blob/main/flake.nix"
```
