SourceBans++ Documentation

The documentation repository is organized as follows:

The repository is organized into the following main directories and files:

• web/: Contains the PHP web panel, JSON API, and tests.
• game/addons/: Contains SourceMod plugin sources (.sp), configurations, and translations.
• docker/: Contains the local development stack (Dockerfile, database initialization, and PHP configuration).
• docker-compose.yml: Orchestrates the web panel, MariaDB database, Adminer, and Mailpit.
• sbpp.sh: A wrapper script for managing the development stack and running quality gates.
• .github/workflows/: CI/CD configurations for PHPStan, testing, TypeScript checking, API contract validation, and releases.
• docs/: The Starlight-based documentation site (covering installation, upgrades, and configuration).

.
├── web/                  PHP web panel (panel + JSON API + tests)
├── game/addons/          SourceMod plugin sources (.sp / configs / translations)
├── docker/               Local dev stack (Dockerfile, db-init, php config)
├── docker-compose.yml    web + db (MariaDB) + adminer + mailpit
├── sbpp.sh               Wrapper for the dev stack and quality gates
├── .github/workflows/    CI gates (phpstan, test, ts-check, api-contract, release)
├── README.md             Landing page — short, links to docs / AGENTS / ARCHITECTURE
├── ARCHITECTURE.md       This file — codebase overview
├── AGENTS.md             Conventions for AI agents / contributors
├── CHANGELOG.md         Release notes
├── docs/                 Starlight docs site (install / upgrade / configure)
├── LICENSE.txt           Elastic License 2.0 (web panel)
├── LICENSE-plugins.txt   GPLv3 (SourceMod plugins)
├── CLA.md                Contributor License Agreement (web/** PRs)
└── THIRD-PARTY-NOTICES.txt

The SourceBans++ export subsystem is a one-shot, stateless process designed to generate data bundles (ZIP files) containing entity exports (admins, bans, comms, logs, etc.) and associated demo files. It operates in two primary modes:

1. ZIP Mode: A streaming mode that writes directly to php://output. It is uncapped because it uses Zip64, allowing for arbitrarily large bundles. It uses real-time flushing to allow browser download progress bars to move.
2. S3 Mode: A staging mode that builds the ZIP to a temporary file in SB_CACHE/exports/<uuid>.zip before uploading it via a single PUT request to an operator-supplied presigned URL. This mode is subject to a size cap (approximately 5 GiB) due to the structural limits of single-PUT S3/R2/MinIO uploads.

The process follows a strict lifecycle: Pre-flight pass (ManifestBuilder) $\rightarrow$ Orchestration (BundleWriter) $\rightarrow$ Emission (EntityExporter) $\rightarrow$ Upload (if S3 mode).

Every export is a Zip64 archive. The manifest.json is the first central-directory entry, allowing consumers to read metadata without downloading the entire bundle.

Archive Layout:

sbpp-export-<uuid>.zip
├── manifest.json
├── entities/
│   ├── admins.jsonl
│   ├── admins_servers_groups.jsonl
│   ├── banlog.jsonl
│   ├── bans.jsonl
│   ├── comms.jsonl
│   ├── comments.jsonl
│   ├── demos.jsonl
│   ├── groups.jsonl
│   ├── log.jsonl
│   ├── mods.jsonl
│   ├── notes.jsonl
│   ├── overrides.jsonl
│   ├── protests.jsonl
│   ├── server_groups.jsonl
│   ├── servers.jsonl
│   ├── servers_groups.jsonl
│   ├── settings.jsonl
│   ├── srvgroups.jsonl
│   ├── srvgroups_overrides.jsonl
│   └── submissions.jsonl
└── demos/
    ├── <filename>.dem
    └── ...

Manifest Fields (manifest.json):

• format_version: integer (currently 1).
• bundle_id: UUIDv4 string.
• created_at: integer unix seconds (UTC).
• panel_version: string matching the panel's data-version footer.
• row_counts: dict of <entity>: <int>.
• demo_total_bytes: integer.
• estimated_bundle_bytes: integer.
• cap_bytes: integer (S3 PUT cap: 5 GiB minus 64 MiB safety margin).
• exceeds_cap: bool (true if estimated_bundle_bytes > cap_bytes).
• pii_policy: dict declaring scope (e.g., includes_admin_emails, includes_ip_addresses, password_hashes: "never").

The production Docker stack uses several named volumes. It is critical to back up dbdata and demos to prevent data loss.

Backup Commands:

Database Backup:

docker compose -f docker-compose.prod.yml exec db \
    mariadb-dump -uroot -p"$DB_ROOT_PASS" --single-transaction sourcebans \
    > backup-$(date +%F).sql

Demos Backup:

docker run --rm -v <stack>_demos:/data -v "$PWD:/backup" alpine \
    tar -czf /backup/demos-$(date +%F).tar.gz -C /data .

Note: Replace <stack> with your compose project name (usually the directory basename).

SourceBans++ consists of two main components that coordinate through a single shared database (MySQL or MariaDB). There is no direct API communication between the components; they synchronize by reading and writing to the same SQL tables.

Components

• Web panel (PHP): The administrative interface where admins log in to manage bans, groups, and servers. It is installed on a web server capable of running PHP and reaching the database.
• SourceMod plugins (.smx): Installed on each individual game server. These plugins enforce bans (disconnecting players) and mutes (comm blocks) in-game, and write admin actions back to the database.
• Database (MySQL/MariaDB): The central source of truth shared by both the web panel and all game server plugins.

Key Architectural Implications

• Distributed Hosting: The web panel and game servers can reside on different physical hosts as long as both have network access to the central database.
• Scalability: Adding a new game server only requires adding a new row to the database, rather than configuring a network handshake with the panel.
• Synchronization: Because they share a database, the only way for the two halves to desync is during a database outage.