How evroon/bracket works
Project type and purpose
• Bracket is a full-stack tournament management system.
• Frontend: Next.js React app (Mantine UI).
• Backend: async Python FastAPI service with SQLAlchemy (via Alembic migrations).
• Orchestrated via Docker Compose alongside a PostgreSQL database.
File structure
• Top-level folders:
• frontend – Next.js client, pages, components, services, localization assets
• backend – FastAPI app (app.py, routes, logic, models, utils, cronjobs), migrations, cli
• docs – separate Next.js doc site
• docker-compose.yml – brings up backend, frontend, Postgres
• Backend layering:
• Routes (API endpoints)
• Logic (planning, scheduling, ranking modules)
• Models/ORM (Pydantic schemas, SQLAlchemy models under bracket/models)
• Utils (DB init, errors, security, pagination)
• Cronjobs scheduler for tasks (scheduling matches, deleting demo data)
• Frontend layering:
• Pages (Next.js routing under src/pages)
• Components (UI building blocks, modals, tables, brackets)
• Services (API adapters per domain: tournament, match, player, etc.)
• i18n localization (public/locales, next-i18next.config.js)
README insights
• Tech stack: FastAPI, Next.js, Mantine
• Features: single-elimination, round-robin, Swiss, drag-and-drop scheduling, multi-club, multi-tournament
• Deployment: Docker Compose, environment config via .env
• Cronjobs invoked inside backend container
Main components
a. User & Presentation Tier
– End users in browser → Next.js frontend (SSR/CSR)
– Separate “public” dashboard view and “admin” UI
b. API Layer
– FastAPI server exposing REST/JSON endpoints
– Routers grouped by domain (tournaments, matches, players, auth, etc.)
c. Domain/Business Logic
– Modules: planning (conflicts, match generation), scheduling (round robin, elimination), ranking (statistics, elimination), subscriptions
– Cronjobs scheduler service for periodic tasks
d. Data Access Layer
– SQLAlchemy models + Alembic migrations
– Raw SQL helpers under bracket/sql/… for optimized queries
e. Data Store
– PostgreSQL database
– Static file storage for frontend assets (served by Next.js/static)
f. Orchestration & Deployment
– Docker Compose: backend, frontend, postgres
– CI/CD pipelines (.github/workflows) publish containers, docs
Relationships and interactions
• Browser ↔ Frontend: HTTP/HTTPS requests, localized UI
• Frontend ↔ Backend API: REST calls via adapter service
• Backend ↔ Database: ORM calls + raw SQL queries
• Cronjobs ↔ Backend modules & Database: internal scheduling calls
• Docker Compose network: isolated containers, environment variables
Architectural patterns & principles
• Layered architecture (presentation → application → domain → data)
• Modularization by domain (each feature in its own module)
• Asynchronous processing with FastAPI + cronjobs for background tasks
• Separation of concerns: migration scripts vs. application logic vs. API routes
Technologies & frameworks to annotate
• Next.js (React, SSR/CSR), Mantine UI, i18next
• FastAPI, Starlette, Pydantic
• SQLAlchemy ORM, Alembic migrations
• PostgreSQL
• Docker, Docker Compose
• CI/CD: GitHub Actions, Crowdin integration for translations