# tcp-tech/flux_backend architecture

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

- Interactive diagram: https://gitdiagram.com/tcp-tech/flux_backend
- Repository: https://github.com/tcp-tech/flux_backend

## Overview

##### Project Type & Purpose
- This is a Go-based monolithic backend service (“Flux Backend”) exposing a versioned REST API (under `cmd/v1.go` and `internal/api`) to manage tournaments, contests, problems, users, locks, etc.
- It follows a layered/“clean” architecture: HTTP layer → API handlers → service/domain layer → data-access layer → external systems (DB, email, scheduler).

##### Main Components
A. HTTP Server (cmd/main.go)
- Entrypoint that initializes routing, middleware, service dependencies and starts `flux.exe`.
B. Middleware (middleware/jwt.go, middleware.go)
- JWT authentication, request logging, CORS, etc. sits between the HTTP server and API handlers.
C. API Handlers (internal/api/*)
- One handler per endpoint (login, signup, create_contest, get_tournament_round, etc.).
- Parse requests, validate input, call the service layer, marshal responses.
D. Service Layer (internal/service/*)
- Domain-oriented packages: auth_service, contest_service, lock_service, problem_service, scheduler_service, tournament_service, user_service.
- Encapsulates business rules, orchestrates calls to data access and external systems.
E. Data Access Layer
- SQL schema & migrations (`sql/schema/*.sql`) and queries (`sql/queries/*.sql`).
- Code generated by sqlc (`internal/database/*.sql.go`) plus `internal/database/db.go`.
- Provides strongly typed DB models and CRUD operations.
F. External Systems
1. Database (e.g., PostgreSQL)
– Stores users, roles, tokens, locks, problems, contests, tournaments, submissions, scores.
2. Email Worker (internal/email)
– A background worker sending signup/reset emails.
3. Scheduler (internal/service/scheduler_service + internal/email/worker.go)
– Plans and launches timed tasks or external job manipulations.

##### Relationships & Data Flows
- Client → HTTP Server (Listen & Serve)
- HTTP Server → Middleware (JWT auth, validation)
- Middleware → API Handler (e.g., CreateTournament)
- Handler → Service Layer (e.g., tournament_service.CreateTournament)
- Service Layer →
- Data Access (DB query via sqlc)
- External Email Worker (enqueue/send)
- Scheduler Service (plan future tasks)
- Service returns result → Handler → HTTP Response

##### Architectural Patterns & Principles
- Layered/Clean Architecture: strictly separate transport, API, business logic, persistence, and external integrations.
- Domain-driven: each service package owns its models and business rules.
- Code Generation: sqlc for type-safe SQL in Go.
- Single Binary Deployment: all layers compile into `flux.exe`.
- Unit Testing: focused on service and scheduler logic under `unit_tests`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client"]:::external

    subgraph "flux.exe (Deployment Boundary)"
        direction TB
        HTTP["HTTP Server"]:::transport
        Middleware["Middleware Layer"]:::api
        API["API Handlers"]:::api

        subgraph "Service Layer"
            direction TB
            AuthSvc["Auth Service"]:::business
            UserSvc["User Service"]:::business
            ContestSvc["Contest Service"]:::business
            ProblemSvc["Problem Service"]:::business
            LockSvc["Lock Service"]:::business
            TourSvc["Tournament Service"]:::business
            SchedSvc["Scheduler Service"]:::business
            Utils["Service Utilities"]:::business
        end

        Errors["Error Definitions"]:::business

        subgraph "Data Access Layer"
            direction TB
            DBCode["Generated SQL Code"]:::persistence
            Migrations["Raw SQL Migrations"]:::persistence
            Queries["SQL Queries"]:::persistence
        end
    end

    subgraph "External Systems"
        direction TB
        DB["Database (PostgreSQL)"]:::external
        EmailWorker["Email Worker"]:::external
        SchedulerExt["Scheduler/Worker"]:::external
    end

    %% Connections
    Client -->|"HTTP Request"| HTTP
    HTTP -->|"to Middleware"| Middleware
    Middleware -->|"calls Handler"| API

    API -->|"invoke"| AuthSvc
    API -->|"invoke"| UserSvc
    API -->|"invoke"| ContestSvc
    API -->|"invoke"| ProblemSvc
    API -->|"invoke"| LockSvc
    API -->|"invoke"| TourSvc
    API -->|"invoke"| SchedSvc

    AuthSvc -->|"uses Utils"| Utils
    UserSvc -->|"uses Utils"| Utils
    ContestSvc -->|"uses Utils"| Utils
    ProblemSvc -->|"uses Utils"| Utils
    LockSvc -->|"uses Utils"| Utils
    TourSvc -->|"uses Utils"| Utils
    SchedSvc -->|"uses Utils"| Utils

    AuthSvc -->|"SQL Query"| DBCode
    UserSvc -->|"SQL Query"| DBCode
    ContestSvc -->|"SQL Query"| DBCode
    ProblemSvc -->|"SQL Query"| DBCode
    LockSvc -->|"SQL Query"| DBCode
    TourSvc -->|"SQL Query"| DBCode

    DBCode -->|"SQL"| DB
    Migrations -->|"apply migrations"| DB
    Queries -->|"define queries"| DBCode

    AuthSvc -->|"enqueue email"| EmailWorker
    SchedSvc -->|"schedule tasks"| SchedulerExt

    %% Click Events
    click HTTP "https://github.com/tcp-tech/flux_backend/blob/main/cmd/main.go"
    click Middleware "https://github.com/tcp-tech/flux_backend/blob/main/middleware/middleware.go"
    click API "https://github.com/tcp-tech/flux_backend/tree/main/internal/api"
    click AuthSvc "https://github.com/tcp-tech/flux_backend/tree/main/internal/service/auth_service"
    click UserSvc "https://github.com/tcp-tech/flux_backend/tree/main/internal/service/user_service"
    click ContestSvc "https://github.com/tcp-tech/flux_backend/tree/main/internal/service/contest_service"
    click ProblemSvc "https://github.com/tcp-tech/flux_backend/tree/main/internal/service/problem_service"
    click LockSvc "https://github.com/tcp-tech/flux_backend/tree/main/internal/service/lock_service"
    click TourSvc "https://github.com/tcp-tech/flux_backend/tree/main/internal/service/tournament_service"
    click SchedSvc "https://github.com/tcp-tech/flux_backend/tree/main/internal/service/scheduler_service"
    click Utils "https://github.com/tcp-tech/flux_backend/blob/main/internal/service/utils.go"
    click DBCode "https://github.com/tcp-tech/flux_backend/blob/main/internal/database/db.go"
    click Migrations "https://github.com/tcp-tech/flux_backend/tree/main/sql/schema"
    click Queries "https://github.com/tcp-tech/flux_backend/tree/main/sql/queries"
    click EmailWorker "https://github.com/tcp-tech/flux_backend/blob/main/internal/email/email.go"
    click Errors "https://github.com/tcp-tech/flux_backend/blob/main/internal/flux_errors/errors.go"

    %% Styles
    classDef transport fill:#D0E8FF,stroke:#0366D6,stroke-width:2px
    classDef api fill:#E0F7F5,stroke:#009688,stroke-width:2px
    classDef business fill:#E6F4EA,stroke:#4CAF50,stroke-width:2px
    classDef persistence fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px
    classDef external fill:#FFE1B3,stroke:#FB8C00,stroke-width:2px
```
