National Hackathon Portal — High-Concurrency Go Backend

A production-ready, high-concurrency REST API backend built in Go (1.24+) using Fiber v2 and PostgreSQL 17 (pgxpool v5).

Designed specifically for a 1-month national hackathon registration portal, this architecture cleanly handles sudden traffic spikes of thousands of concurrent registration requests on a single VPS without connection starvation, goroutine leaks, or crashes.

---

Key Architectural Highlights

• Zero Global State / Clean Dependency Injection: Explicit wiring from configuration -> database pool -> repository -> handlers -> Fiber router.
• Connection Multiplexing (pgxpool v5): Tuned pool (MaxConns=50, MinConns=10, MaxConnLifetime=30m, MaxConnIdleTime=5m, MaxConnLifetimeJitter=2m) that safely multiplexes hundreds of concurrent HTTP workers across bounded PostgreSQL backend processes.
• Pipelined Atomic Transactions (pgx.Batch): Team creation and all member insertions run inside a single ACID transaction (BEGIN ... COMMIT) using tx.SendBatch, inserting all team members in a single network round-trip.
• Strict 3-Second Context Timeouts: Every database operation enforces context.WithTimeout(ctx, 3*time.Second) to prevent hung queries from exhausting the connection pool.
• Zero-DB Input Validation: Strict sanitization and validation (email RFC parsing, phone regex, allowed tracks, and duplicate email checks across leader/members) occur entirely in memory before acquiring a database connection.
• Production Middleware:
  • Global panic recovery with structured JSON stack logging (log/slog).
  • Configured CORS restricted to allowed frontend origins.
  • Sliding-window, in-memory IP rate limiting protecting POST /api/v1/register from bot spam.
• Graceful Shutdown: Listens for SIGINT / SIGTERM, drains in-flight HTTP requests within a 10-second deadline, and cleanly closes pgxpool.

---

Project Structure

hackathon-backend/
├── cmd/
│   └── api/
│       ├── main.go                  # Application entrypoint, DI wiring, graceful shutdown
│       └── main_test.go             # Live TCP E2E test & 5,000-request burst load benchmark
├── internal/
│   ├── config/
│   │   └── config.go                # Environment configuration & VPS pool defaults
│   ├── database/
│   │   └── postgres.go              # pgxpool v5 initialization & health ping
│   ├── handlers/
│   │   ├── handlers.go              # HealthCheck & RegisterTeam HTTP handlers
│   │   └── handlers_test.go         # Handler unit tests (201, 409 Conflict, 429 Rate Limit)
│   ├── middleware/
│   │   └── middleware.go            # Panic recovery, CORS, and sliding-window rate limiter
│   ├── models/
│   │   ├── registration.go          # Request/Response envelopes & strict input validation
│   │   └── registration_test.go     # Validation & sanitization unit tests
│   └── repository/
│       └── registration_repo.go     # Atomic transactions, pgx.Batch, and 3s timeouts
├── migrations/
│   └── 001_init.sql                 # PostgreSQL schema, unique constraints, and indexes
├── Dockerfile                       # Multi-stage static distroless build
├── docker-compose.yml               # Go API + tuned PostgreSQL 17 with healthchecks
└── go.mod

---

Prerequisites

• Go 1.24+ (for local development and running tests)
• Docker & Docker Compose (for running PostgreSQL 17 and/or containerized deployment)

---

Quick Start

Option 1: Run Everything via Docker Compose (Recommended for Production/Staging)

Spin up both the tuned PostgreSQL 17 container (which automatically applies migrations/001_init.sql on first boot) and the compiled Go API container:

docker compose up --build -d

Check container status and logs:

docker compose ps
docker compose logs -f api

---

Option 2: Local Go Development + Docker PostgreSQL

1. Start only the PostgreSQL 17 container:

   docker compose up -d postgres

2. Install Go dependencies:

   go mod tidy

3. Run the API server locally:

   go run ./cmd/api

   The server will start on http://localhost:8080.

---

Environment Variables

All settings have sensible production defaults in internal/config/config.go and can be overridden via environment variables:

Variable	Default	Description
PORT	8080	HTTP server listening port
DATABASE_URL	postgres://hackathon:hackathon_secret@localhost:5432/hackathon_db?sslmode=disable	PostgreSQL connection string
ALLOWED_ORIGINS	http://localhost:3000,https://hackathon.national.org	Comma-separated CORS origins
DB_MAX_CONNS	50	Maximum concurrent connections in pgxpool
DB_MIN_CONNS	10	Minimum idle connections kept warm in pgxpool
DB_MAX_CONN_LIFETIME	30m	Maximum lifetime of a connection before recycling
DB_MAX_CONN_IDLE_TIME	5m	Maximum idle time before closing excess connections
DB_HEALTH_CHECK_PERIOD	1m	Background health check interval for idle connections
RATE_LIMIT_MAX	10	Max registration attempts per IP per window
RATE_LIMIT_WINDOW	1m	Sliding window duration for the registration rate limiter

---

API Reference

1. Health Check

• Endpoint: GET /healthz
• Description: Verifies API readiness and pings PostgreSQL with a 3-second timeout.

curl -i http://localhost:8080/healthz

Response (200 OK):

{
  "success": true,
  "message": "OK",
  "data": {
    "status": "healthy"
  },
  "timestamp": "2026-11-04T10:00:00Z"
}

---

2. Register a Team

• Endpoint: POST /api/v1/register
• Allowed Tracks: ai-ml, fintech, healthtech, climate-tech, cybersecurity, open-innovation
• Team Size: 1 to 5 members (with unique emails across the leader and all members)

curl -X POST http://localhost:8080/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "team_name": "Quantum Pioneers",
    "track": "ai-ml",
    "project_summary": "Real-time edge inference for rural medical diagnostics.",
    "leader": {
      "name": "Ada Lovelace",
      "email": "ada@university.edu",
      "phone": "+1-555-234-5678",
      "institution": "National Tech University"
    },
    "members": [
      {
        "full_name": "Alan Turing",
        "email": "alan@university.edu",
        "role": "Backend & ML Engineer",
        "github_url": "https://github.com/turing"
      },
      {
        "full_name": "Grace Hopper",
        "email": "grace@university.edu",
        "role": "Systems Architect",
        "github_url": "https://github.com/hopper"
      }
    ]
  }'

Success Response (201 Created):

{
  "success": true,
  "message": "Team registered successfully",
  "data": {
    "team_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "team_name": "Quantum Pioneers",
    "track": "ai-ml",
    "leader_email": "ada@university.edu",
    "member_count": 2,
    "created_at": "2026-11-04T10:01:23.456789Z"
  },
  "timestamp": "2026-11-04T10:01:23.457Z"
}

Status Codes:

• 201 Created — Team and members atomically persisted.
• 400 Bad Request — Malformed JSON body.
• 409 Conflict — Team name or leader email is already registered.
• 422 Unprocessable Entity — Field-level validation failed (returns structured errors array).
• 429 Too Many Requests — IP rate limit exceeded.
• 504 Gateway Timeout — Database transaction exceeded the 3-second deadline under heavy load.

---

Running Tests & High-Concurrency Benchmarks

Run All Unit, Handler, and E2E Tests

go test -v -count=1 ./...

Run with the Go Race Detector

go test -v -race -count=1 ./...

Run the 5,000-Request High-Concurrency Burst Load Test

With the postgres container running (docker compose up -d postgres), run:

go test -v -count=1 ./cmd/api -run TestHighVolumeLoadTest_5000Requests

Note: TestHighVolumeLoadTest_5000Requests automatically initializes the schema and runs TRUNCATE TABLE team_members, teams RESTART IDENTITY CASCADE before firing 5,000 concurrent registration transactions (15,000 total rows inserted) across 250 concurrent worker goroutines.

Benchmark Results on Single Host (PostgreSQL 17 + pgxpool MaxConns=50)

=====================================================================
  HIGH-CONCURRENCY BURST STRESS TEST REPORT (PostgreSQL 17 (pgxpool MaxConns=50))
=====================================================================
  Total Requests      : 5000
  Concurrent Workers  : 250
  Total Wall Time     : 1.022s
  Throughput (RPS)    : 4,890.52 req/sec
  201 Created         : 5000
  409 Conflict        : 0
  Errors / Timeouts   : 0
  Latency (Avg)       : 49.61ms
  Latency (p50)       : 44.69ms
  Latency (p95)       : 87.78ms
  Latency (p99)       : 159.82ms
  Latency (Max)       : 190.68ms
=====================================================================

Manually Resetting the Database

To wipe all test registrations from the running PostgreSQL container at any time:

docker exec -i hackathon-postgres psql -U hackathon -d hackathon_db -c "TRUNCATE TABLE team_members, teams RESTART IDENTITY CASCADE;"