How hmajid2301/banterbus works
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.