Skip to content

Developer Guide

Jump to bottom
c0bra edited this page Jul 24, 2026 · 1 revision

Developer Guide

This page is for contributors working on Battlevive Bot.

Project layout

  • app/main.py - entry point.
  • app/battlevive_bot/ - runtime modules such as bot.py, API sync, database access, image rendering, roles, models, logging, and settings.
  • app/init-db/ - numbered PostgreSQL bootstrap and migration SQL files.
  • app/assets/ - bundled assets such as fonts.
  • app/data/ and app/logs/ - runtime data and logs.
  • utils/ - setup helpers and environment generation.
  • tests/ - pytest suite.

Local validation

Use the repository's documented checks:

python -m compileall app utils
pytest
podman build . --file Dockerfile --tag battlevive-bot:local

For live validation, generate a fresh local .env from utils/.env.example, fill only local/test credentials, then run Compose from the repository root.

Data flow

The bot periodically refreshes Battlevive data:

  • Tokens are revalidated every 30 minutes.
  • Users are refreshed hourly.
  • Lobbies and season ratings are refreshed every 30 seconds.
  • Manual /refresh fetches users, lobbies, and season ratings, syncs the database, updates roles, and requests leaderboard reconciliation.

users.discord_id is bot-owned local state. Sync logic must preserve it and never overwrite it from upstream payloads.

Database changes

Keep SQL changes as numbered files under app/init-db/. Fresh databases run the complete set automatically; existing volumes need idempotent migrations applied manually. Update the Database Schema wiki page when persistence changes.

Discord commands in code

Validate command names and permissions against app/battlevive_bot/bot.py when documenting or changing command behavior:

  • /rank
  • /refresh - Manage Server, guild-only.
  • /create_roles
  • /config leaderboard channel - Manage Server, guild-only.
  • /config leaderboard limit - Manage Server, guild-only.
  • /config reset leaderboard - Manage Server, guild-only.
  • /config show - Manage Server, guild-only.

Debug dump commands

/debug_get_db_data and /debug_get_battlevive_data dump users, lobbies, and ratings as JSON files. Treat them as developer/operator diagnostics only: they can expose synced user and match data, should not be run casually in shared servers, and should never be used to paste secrets or private data into issues or chat.

Clone this wiki locally