go-backend-architecture

Go Backend Architecture

Clean Architecture Go backend template for building maintainable, testable APIs with built-in caching and observability, designed for engineers and AI agents.

Purpose

For both engineers and AI agents. Shared rules in AGENTS.md keep structure consistent. The template:

• Provides a reusable backend starter that follows clean architecture.
• Keeps business logic isolated from frameworks and vendors.
• Offers production-ready foundations: HTTP, DB (PostgreSQL with pgvector), cache-aside user store, KV-backed auth (session/OTP/OAuth), migrations, tracing, metrics, and structured logging.
• Serves as a base repo to clone for new app projects.

Architecture and Principles

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

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.