# evroon/bracket architecture

> Architecture diagram of the GitHub repository evroon/bracket, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/evroon/bracket
- Repository: https://github.com/evroon/bracket

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation & UI Layer
    subgraph "Presentation & UI Layer"
        direction TB
        User["End User"]:::infra
        NextJs["Next.js Frontend"]:::ui
        Pages["Frontend Pages"]:::ui
        Components["UI Components"]:::ui
        Services["API Adapters"]:::ui
        Localization["Localization Assets"]:::ui
        Config["i18next Config"]:::ui
        DocsSite["Documentation Site"]:::ui
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        FastAPIServer["FastAPI Server"]:::api
        CLI["Backend CLI"]:::api
        Uvicorn["Uvicorn Launcher"]:::api
        Routers["API Routers"]:::api
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        Logic["Domain Logic"]:::logic
        subgraph "Modules"
            direction TB
            Planning["Planning Modules"]:::logic
            Scheduling["Scheduling Modules"]:::logic
            Ranking["Ranking Modules"]:::logic
            Subscriptions["Subscriptions Logic"]:::logic
        end
        Cronjobs["Cronjobs Scheduler"]:::logic
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        direction TB
        ORM["ORM Models"]:::data
        Pydantic["Pydantic Schemas"]:::data
        RawSQL["Raw SQL Helpers"]:::data
    end

    %% Data Store
    subgraph "Data Store"
        direction TB
        DB["PostgreSQL"]:::data
        Migrations["Alembic Migrations"]:::data
    end

    %% Orchestration & Deployment
    subgraph "Orchestration & Deployment"
        direction TB
        DockerCompose["Docker Compose"]:::infra
        FrontendDocker["Frontend Dockerfile"]:::infra
        BackendDocker["Backend Dockerfile"]:::infra
        CICD["CI/CD Pipelines"]:::infra
    end

    %% Connections
    User -->|"browses UI"| NextJs
    User -->|"views docs"| DocsSite
    NextJs --> Pages
    NextJs --> Components
    NextJs --> Services
    NextJs --> Localization
    NextJs --> Config

    NextJs -->|"REST API calls"| FastAPIServer
    CLI --> FastAPIServer
    Uvicorn --> FastAPIServer
    FastAPIServer --> Routers
    Routers --> Logic

    Logic --> Planning
    Logic --> Scheduling
    Logic --> Ranking
    Logic --> Subscriptions
    Cronjobs --> Logic
    Cronjobs --> DB

    Logic --> ORM
    Logic --> RawSQL
    ORM --> DB
    RawSQL --> DB
    Migrations --> DB

    DockerCompose --> NextJs
    DockerCompose --> FastAPIServer
    DockerCompose --> DB
    FrontendDocker --> DockerCompose
    BackendDocker --> DockerCompose
    CICD --> DockerCompose
    CICD --> DocsSite

    %% Click Events
    click NextJs "https://github.com/evroon/bracket/tree/master/frontend/"
    click Pages "https://github.com/evroon/bracket/tree/master/frontend/src/pages/"
    click Components "https://github.com/evroon/bracket/tree/master/frontend/src/components/"
    click Services "https://github.com/evroon/bracket/tree/master/frontend/src/services/"
    click Localization "https://github.com/evroon/bracket/tree/master/frontend/public/locales/"
    click Config "https://github.com/evroon/bracket/blob/master/frontend/next-i18next.config.js"
    click FastAPIServer "https://github.com/evroon/bracket/blob/master/backend/bracket/app.py"
    click CLI "https://github.com/evroon/bracket/blob/master/backend/cli.py"
    click Uvicorn "https://github.com/evroon/bracket/blob/master/backend/bracket/uvicorn.py"
    click Routers "https://github.com/evroon/bracket/tree/master/backend/bracket/routes/"
    click Planning "https://github.com/evroon/bracket/tree/master/backend/bracket/logic/planning/"
    click Scheduling "https://github.com/evroon/bracket/tree/master/backend/bracket/logic/scheduling/"
    click Ranking "https://github.com/evroon/bracket/tree/master/backend/bracket/logic/ranking/"
    click Subscriptions "https://github.com/evroon/bracket/blob/master/backend/bracket/logic/subscriptions.py"
    click ORM "https://github.com/evroon/bracket/tree/master/backend/bracket/models/db/"
    click Pydantic "https://github.com/evroon/bracket/blob/master/backend/bracket/schema.py"
    click RawSQL "https://github.com/evroon/bracket/tree/master/backend/bracket/sql/"
    click Cronjobs "https://github.com/evroon/bracket/tree/master/backend/bracket/cronjobs/"
    click Migrations "https://github.com/evroon/bracket/tree/master/backend/alembic/"
    click DockerCompose "https://github.com/evroon/bracket/blob/master/docker-compose.yml"
    click BackendDocker "https://github.com/evroon/bracket/tree/master/backend/Dockerfile"
    click FrontendDocker "https://github.com/evroon/bracket/tree/master/frontend/Dockerfile"
    click DocsSite "https://github.com/evroon/bracket/tree/master/docs/"
    click CICD "https://github.com/evroon/bracket/tree/master/.github/workflows/"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#70AFFF
    classDef api fill:#DFFFE0,stroke:#70D000
    classDef logic fill:#FFF8D0,stroke:#D0A000
    classDef data fill:#FFE0C0,stroke:#FF8000
    classDef infra fill:#F0F0F0,stroke:#A0A0A0
```
