Waitlist Backend (Go + MongoDB)

A production-ready waitlist backend that accepts frontend submissions, validates input, and persists data in MongoDB. It is designed for high concurrency and low latency, and it uses the standard net/http stack rather than Gin. This README is intentionally detailed so you can learn how a clean Go backend is structured and why each layer exists.

What you will learn

• How to structure a Go backend with clear separation of concerns.
• How to build HTTP handlers with net/http and middleware chains.
• How to validate inputs and return consistent JSON responses.
• How to use the MongoDB Go driver with connection pooling and indexes.
• How to make services resilient with timeouts, rate limits, and body limits.
• How to configure apps with environment variables and .env files.

Requirements

• Go 1.26+
• MongoDB (local or Atlas)

Quick start

Create a .env file at the repo root (already supported):

MONGO_URI=mongodb://localhost:27017
DB_NAME=waitlist
ALLOWED_ORIGINS=http://localhost:3000

Run the API:

go run ./cmd/api

API summary

• POST /api/waitlist stores a submission in MongoDB.
• GET /health checks server and MongoDB connectivity.

Success response:

{ "status": "ok", "message": "Added to waitlist" }

Error response:

{ "status": "error", "message": "Invalid email" }

Project layout (modern and easy to understand)

This structure keeps transport concerns separate from business logic and data access.

waitlistbackend/
cmd/
api/
main.go
internal/
config/
config.go
repository/
models.go
waitlist_repository.go
service/
waitlist_service.go
transport/
http/
handlers/
errors.go
health.go
json.go
waitlist.go
middleware/
cors.go
middleware.go
ratelimit.go
request.go
validation/
validation.go
app.http
go.mod
README.md

File-by-file guide

Entry point

• cmd/api/main.go
  • Bootstraps the app: loads config, connects to MongoDB, wires handlers, and starts the HTTP server.
  • Builds the middleware chain (CORS, body limit, timeout, rate limit, logging).
  • Handles graceful shutdown and ensures MongoDB disconnect on exit.

Configuration

• internal/config/config.go
  • Loads environment variables from the shell or a .env file.
  • Supports ENV_FILE override and tries .env in current and parent directories.
  • Parses typed config values (durations, ints, floats) with sensible defaults.

HTTP transport (handlers)

• internal/transport/http/handlers/waitlist.go

  • Accepts JSON requests and validates input shape.
  • Uses streaming JSON decoding with DisallowUnknownFields().
  • Calls the service layer and maps errors to HTTP responses.

• internal/transport/http/handlers/health.go

  • Pings MongoDB with a short timeout and returns health status.

• internal/transport/http/handlers/errors.go

  • Centralizes JSON error responses.

• internal/transport/http/handlers/json.go

  • Centralizes JSON success responses.

HTTP transport (middleware)

• internal/transport/http/middleware/middleware.go

  • Simple middleware chaining helper.

• internal/transport/http/middleware/cors.go

  • CORS handling for allowed origins.
  • Supports a wildcard * in ALLOWED_ORIGINS.

• internal/transport/http/middleware/request.go

  • Request logging with slog.
  • Request timeout and body size limits.

• internal/transport/http/middleware/ratelimit.go

  • Token-bucket rate limiting per IP using golang.org/x/time/rate.
  • Periodic cleanup of stale IP buckets.

Business logic

• internal/service/waitlist_service.go
  • Validates required fields and email format.
  • Creates a waitlist record with CreatedAt and delegates storage to the repository.
  • Converts repository errors to service-level errors.

Data access

• internal/repository/waitlist_repository.go

  • Inserts records into MongoDB.
  • Creates a unique index on email to prevent duplicates.
  • Normalizes duplicate-key errors.

• internal/repository/models.go

  • Defines the MongoDB document structure.

Validation utilities

• internal/validation/validation.go
  • Simple email regex validator.

Testing requests

• app.http
  • Ready-to-run HTTP examples for VS Code REST client.

Request flow (handlers -> service -> repository)

1. POST /api/waitlist hits the waitlist handler.
2. The handler parses JSON and validates the payload.
3. The service enforces business rules and prepares a record.
4. The repository inserts into MongoDB and enforces uniqueness.
5. The handler returns a JSON response.

This layered flow makes it easy to test each piece independently and scale the app later.

Configuration reference

All settings can come from shell env or .env. Values are read at startup.

• MONGO_URI (required)
• DB_NAME (required)
• ALLOWED_ORIGINS (required, comma-separated)
• PORT (default: 8080)
• REQUEST_TIMEOUT (default: 5s)
• MAX_BODY_BYTES (default: 65536)
• RATE_LIMIT_RPS (default: 5)
• RATE_LIMIT_BURST (default: 10)
• MONGO_MAX_POOL_SIZE (default: 100)
• ENV_FILE (optional path to a specific .env file)

Local development tips

• Run from the repo root so .env is found automatically.
• Use app.http to test requests without leaving VS Code.
• If you run from cmd/api, config will still search parent directories for .env.

Deployment notes

• For cloud deploys (Render, Fly, etc.), set env vars in the platform UI.
• .env is intended for local development only.

Why not Gin?

This project uses net/http to show the fundamentals. Gin is great for rapid API development, but learning the standard library first gives you a deeper understanding of middleware, handlers, and request lifecycles. You can migrate to Gin later without changing the service or repository layers.