go-backend-architecture

Go Backend Architecture

Go modular-monolith backend template with Clean Architecture — clear layer boundaries, production-ready API foundations, and agent rules that keep AI-assisted changes consistent.

Included Foundations

• Multi-binary-ready composition — support for adding future workers as sibling process packages without duplicating runtime setup.
• HTTP safety and streaming — timeouts, graceful shutdown, CORS allowlists, trusted-proxy IP extraction, security headers, and reusable Server-Sent Events with a bounded health-stream demo.
• Authentication — Redis-backed sessions and OTPs, optional Resend email delivery, optional Google OAuth, and secure cookie defaults.
• Rate limiting — app-level Redis token-bucket per-IP limiting at the origin, useful without a CDN and as defense in depth behind one.
• Data stores — SQL-first PostgreSQL, Redis cache-aside store composition, and a ready-to-wire object-storage adapter — with vendor types kept inside infra.
• Observability — OpenTelemetry tracing and metrics, plus structured logging — kept behind app-owned interfaces.
• Testing — reusable repository fakes for unit tests, plus HTTP integration suites with optional real Postgres/Redis.
• Local development — local hot reload and Docker Compose for Postgres, Redis, and observability services.
• Agent rules — AI coding guidance that encodes the template's layer boundaries and patterns.

Architecture and Principles

These keep framework and infrastructure details at the edges so business logic stays independent and changes stay localized.

Architecture & structure

• Clean Architecture
• Dependency Injection (Composition root)
• SOLID principles
• Consumer-owned interfaces

Structural patterns

• Adapter pattern
• Decorator pattern
• Facade pattern

Behavioral & creational

• Builder pattern
• Strategy pattern
• Null object pattern

Data & transport

• Cache-aside pattern
• Repository pattern
• Middleware pattern

See package-level README.md files and AGENTS.md for implementation guidance and shared architecture rules for both engineers and AI agents.

Third-Party Tools

Transport

• Echo v5 - HTTP server
• go-playground/validator/v10 - request/DTO validation (struct tags)
• OpenAPI 3 - source of truth for HTTP contracts
• oapi-codegen - backend transport model generation from OpenAPI

Database

• pgx/v5 - PostgreSQL driver and connection pool
• sqlc - static SQL query generation
• Masterminds/squirrel - dynamic SQL construction
• pressly/goose - database migrations

Why SQL-first data access (no ORM)

• Raw SQL with sqlc + squirrel provides explicit query control, predictable performance tuning, and compile-time type safety.
• Common downsides are handled by:
  • sqlc generated typed mappings to reduce runtime schema/query mismatch risk.
  • squirrel composable dynamic SQL to avoid fragile string concatenation.
  • Clean Architecture + repository boundaries to isolate SQL in infra adapters and keep usecases storage-agnostic.

Cache

• go-redis/v9 - Redis client integration

Object storage

• AWS SDK for Go v2 - S3-compatible Cloudflare R2 object-storage adapter

Authentication

• golang.org/x/oauth2 - OAuth 2.0 client support for Google login
• Resend - optional OTP email delivery

Observability & logging

• uber-go/zap - structured logging
• OpenTelemetry SDK + OTLP exporters - tracing, logs, and metrics
• HyperDX + OpenTelemetry Collector - local observability integration

Development & infra

• air - local hot reload
• Docker Compose - local infrastructure orchestration

Requirements

• Go 1.26+
• Docker and Docker Compose
• GNU Make

Use as a Starter

1. Create a new repository from this template.
2. Bootstrap the project:

./scripts/bootstrap-template.sh --module github.com/your-org/your-backend

This updates module/import paths, service and stack naming, OpenAPI title, and README title.

1. If you cloned this repo directly, rename your project directory and set the Git remote to your new repository. The script does not change directory names or remotes.
2. Validate with make openapi-generate && make test.
3. Review docker-compose.yml, .env.example, and docs/openapi.yaml for project-specific values. The auth (pluggable OTP/OAuth + session), cached user store, and health modules are production-ready foundations—extend them and add your own migrations and features.
4. Review AGENTS.md and package-level README.md files before feature development.

Setup and Run

1. cp .env.example .env
2. make install
3. make dev-up && make migrate-up
4. make run
5. Verify GET /health?check=ready

Common commands: make dev-logs, make dev-down, make migrate-status, make openapi-generate, make run-stop.

Default local ports: Postgres 5432, Redis 6379, OTel 4317/4318, HyperDX 8081.

Verify

Run the unit and standard HTTP integration suites:

make test
make test-integration

With Postgres and Redis running, run the real-adapter integration suite. It loads a repository-root .env when present; explicitly exported environment variables take precedence.

make test-integration-real

To observe the bounded SSE demo while the API is running:

curl -N 'http://localhost:8080/health/stream?check=ready'