CookOff 11.0 Backend

A production-level, highly scalable Go backend built using the Echo v4 HTTP framework. It utilizes connection pooled PostgreSQL via pgx/v5 and compiled type-safe database queries via SQLC, backed by Redis and structured logging via Zap.

---

Tech Stack

• HTTP Framework: Echo v4
• Database Client: pgx/v5 with connection pooling (pgxpool)
• Query Generator: SQLC for compilation-time type-safe database methods
• Database Migrations: Goose
• Configuration Parsing: caarlos0/env/v11 with .env loading using godotenv
• Structured Logging: Uber Zap
• Caching: go-redis/v9
• Validation: go-playground/validator/v10
• Hot-Reloading: Air
• API UI Documentation: Scalar API Reference

---

Directory Structure

├── cmd/
│   ├── api/                    # HTTP server entrypoint & graceful shutdown
│   ├── worker/                 # Asynq job consumer entrypoint
│   └── migrate/                # Goose migration CLI entrypoint
├── internal/
│   ├── controllers/           # HTTP handlers
│   ├── db/                    # SQLC generated code
│   ├── dto/                   # Request/Response structures & validation
│   ├── logging/               # Structured logging using Zap
│   ├── middlewares/           # Custom middlewares (JWT, Custom logger)
│   ├── queue/                 # Asynq client (producer side)
│   ├── workers/                # Asynq task handlers (consumer side)
│   └── helpers/utils/         # DB Pool, Redis, config, validator
├── database/
│   ├── queries/               # SQLC raw queries
│   └── schema/                # Goose SQL migrations
├── docs/                      # Documentation mirror explaining files
└── tests/                     # HTTP and unit test cases

---

Getting Started

Local Setup

1. Make sure you have PostgreSQL and Redis running locally.
2. Create your .env file from the example:

   cp .env.example .env

3. Initialize the database schema using Goose:

   make migrate-up

4. Run the application with hot-reloading:

   make dev

5. In a separate shell, run the worker:

   make worker

Docker Setup

There are two Docker Compose stacks, both defined by the same docker-compose.yml and a docker-compose.dev.yml overlay:

Production-mode stack (Dockerfile, compiled binaries, one-shot migration job):

make docker-up      # build + start postgres, redis, migrate, api, worker
make docker-logs    # tail logs
make docker-down    # stop

The migrate service runs goose up once and exits; api and worker wait for it to complete successfully before starting.

Hot-reload dev stack (Dockerfile.dev, air, bind-mounted source):

make dev-up         # build + start the same stack with live reload
make dev-logs
make dev-down

---

Deploying

• CORS and cookies: FRONTEND_URL and ADMIN_URL must be the exact origins of the portal and admin panel (scheme, host, no path); only those origins can call the API. Keep both on a codechefvit.com subdomain so the session cookies are same-site; COOKIE_DOMAIN can stay unset.

• Reverse proxy: GET /result/:id holds the request for up to 90s while a verdict is judged, and /runcode / /runcustom for up to 45s. Nginx's default proxy_read_timeout (60s) cuts /result short, so set it to at least 100s and turn buffering off for it:

  location /result/ {
      proxy_pass http://127.0.0.1:8080;
      proxy_read_timeout 100s;
      proxy_buffering off;
  }

  Forward the client address (proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;); behind Cloudflare the API uses CF-Connecting-IP.

• Tuning: RATE_LIMIT_MAX/RATE_LIMIT_WINDOW (per player, all routes), JUDGE0_WAIT_SLOTS (concurrent synchronous Judge0 calls; size it to the Judge0 worker count), WORKER_COUNT and POSTGRES_MAX_CONNS. See .env.example.

Interactive Documentation

Once the backend is running, navigate to:

http://localhost:8080/docs

to view the interactive API reference served via Scalar.

---

Makefile Automation

• make build: Compile all binaries (api, worker, migrate) into bin/.
• make run: Run the API server locally.
• make worker: Run the worker locally.
• make dev: Run the API with hot-reloading (air).
• make test: Run automated tests.
• make lint: Run code formatting and static analysis checkers (golangci-lint).
• make vulncheck: Scan dependencies for known security vulnerabilities (govulncheck).
• make sqlc: Compile SQL queries into Go code using SQLC.
• make migrate-up / make migrate-down / make migrate-status: Manage Goose database migrations.
• make docker-up / make docker-down / make docker-logs: Manage the production-mode Docker stack (postgres, redis, migrate, api, worker).
• make docker-migrate: Run the one-shot migration job against the Docker stack.
• make dev-up / make dev-down / make dev-logs: Manage the hot-reload Docker dev stack.
• make clean: Remove build artifacts (bin/, tmp/).
• make help: List all available targets.

---

🔄 Workflow & Code Quality

Git Hooks (Commit Message Validation)

To enforce professional commit names (following the Conventional Commits spec), run the following command to bind the git hooks path:

git config core.hooksPath .githooks

(On Linux/macOS, ensure the hook is executable: chmod +x .githooks/commit-msg)

CI/CD Pipeline

Every Pull Request and commit pushed to main/master/dev triggers a GitHub Actions pipeline validating:

• Proper Go code formatting (gofmt).
• Static analysis checks (go vet).
• Code styling & security linters (golangci-lint).
• Automated tests suite completion (go test).
• Go application compilation health (go build).

---

🔗 Related Projects

• Participant Portal: cookoff-portal-11.0
• Admin Portal: cookoff-admin-11.0

These services work together to provide the complete Cookoff 11.0 contest infrastructure.

---

🚀 Contributors

Yogesh Kumar	Harshil Maheshwari	Laksh Raja	Namit Gupta
Tejas Maurya	Atharva Sharma	VP Krishna	Vihaan Jain
Upayan Mazumder	Neharika Chinnappa	Rithish

---

📝 License

Distributed under the MIT License. See LICENSE for more information.

---

Made with ❤️ by CodeChef-VIT