How tcp-tech/flux_backend works
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.