Bracket

Bracket is a self‑hosted, full‑stack application for managing competitive tournaments. It exposes a REST/GraphQL API built with FastAPI and serves a modern React front‑end powered by Next.js and the Mantine component library. The system is intentionally lightweight yet feature‑rich, supporting single elimination, round‑robin and Swiss formats out of the box. Its core goal is to give developers a plug‑and‑play platform that can be extended or embedded into larger ecosystems while remaining easy to deploy on Kubernetes, Docker Compose, or a bare‑metal server.

Technical Stack & Architecture

• Backend – Asynchronous Python 3.11, FastAPI, Pydantic for data validation, SQLAlchemy ORM (async support), Alembic migrations. The API layer is split into routers for clubs, tournaments, teams, matches, and users, each following RESTful conventions.
• Frontend – Next.js 13 with the App Router, React Server Components, and TypeScript. Mantine provides a cohesive UI layer that can be themed or replaced without touching the core logic.
• Database – PostgreSQL 15+, accessed via asyncpg through SQLAlchemy. The schema is versioned with Alembic, allowing zero‑downtime migrations in production.
• Background Tasks – FastAPI’s BackgroundTasks and optional Celery workers (via Redis) handle time‑sensitive operations such as Swiss pairing generation, match scheduling, and email notifications.
• Containerization – Dockerfiles for both backend and frontend expose health‑check endpoints. A single docker-compose.yml orchestrates PostgreSQL, backend, frontend, and optional Redis, making it trivial to spin up a dev environment.

Core Capabilities & Developer APIs

• Tournament Modeling – Developers can programmatically create multi‑stage tournaments, inject custom stages (e.g., qualifiers → finals), and define groupings or brackets within each stage. The API returns fully hydrated tournament objects, including bracket trees and match status.
• Dynamic Swiss Pairing – An algorithmic engine automatically generates pairings for each round, respecting rank, previous opponents, and user‑defined constraints. The pairing logic is exposed as a service endpoint that can be called from external workflows.
• Drag‑and‑Drop Scheduling – The front‑end exposes WebSocket endpoints (via FastAPI’s WebSocket support) to update match start times or court assignments in real time. This can be consumed by custom dashboards or integration tools.
• Webhooks & Callbacks – Bracket can emit events (match_started, score_updated, tournament_completed) to external URLs. Conversely, it accepts inbound webhooks for score submissions or user authentication via OAuth2 providers.
• Extensibility Hooks – The application ships with a simple plugin interface: developers can drop Python modules into a plugins/ directory, register new routers or background jobs, and the system will auto‑discover them on startup.

Deployment & Infrastructure

Bracket is designed for self‑hosting with minimal prerequisites:

• Docker Compose – One command (docker compose up -d) spins up the stack. For production, a Helm chart can be generated by templating the Compose file for Kubernetes.
• Scalability – The API can be horizontally scaled behind a reverse proxy (NGINX, Traefik). PostgreSQL is the single point of contention; read replicas or a managed Postgres service can be used for high‑throughput scenarios.
• Observability – Built‑in OpenTelemetry instrumentation exposes metrics to Prometheus, and logs are structured JSON for easy ingestion into ELK or Loki stacks.
• Persistence – Data is stored in PostgreSQL; backups can be automated via pg_dump or managed cloud snapshots. The front‑end is stateless, enabling zero‑downtime deployments.

Integration & Extensibility

• SDKs – While no official SDK exists, the OpenAPI spec (/openapi.json) can be used to generate client libraries in any language (Python, TypeScript, Go, etc.) with tools like openapi-generator.
• Custom Themes – Mantine’s theming system allows overriding colors, fonts, and component styles via a JSON config file or CSS variables. This is ideal for brand‑specific dashboards.
• Single Sign‑On – FastAPI’s OAuth2 support can be wired to any SAML or OIDC provider, enabling integration with corporate identity systems.
• Plugins – The plugin API lets developers add new endpoints, modify database models, or inject custom business logic without forking the repository.

Developer Experience

• Documentation – Comprehensive docs are hosted at docs.bracketapp.nl, covering architecture, API reference, and deployment guides. The docs are auto‑generated from code comments and Swagger UI.
• Community & Support – The project is actively maintained on GitHub, with frequent releases and a responsive issue tracker. Contributions are welcomed through pull requests; the codebase follows PEP‑8 and uses type hints throughout.
• Testing – High coverage (codecov badge) with pytest and httpx for API tests. Continuous integration ensures regressions are caught early.

Use Cases