go-backend-architecture

Go Backend Architecture

Go modular-monolith backend template for building maintainable, testable APIs with built-in caching and observability.

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/KV integration, migrations, tracing, metrics, and structured logging.
• Serves as a base repo to clone for new app projects.

Architecture and Principles

• Clean Architecture
• Dependency Injection (Composition root)
• SOLID principles
• Consumer-owned interfaces
• Adapter pattern
• Decorator pattern
• Facade pattern
• Builder pattern
• Null object 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

• Echo v5 - HTTP server
• go-playground/validator/v10 - request/DTO validation (struct tags)
• pgx/v5 - PostgreSQL driver and connection pool
• sqlc - static SQL query generation
• Masterminds/squirrel - dynamic SQL construction
• pressly/goose - database migrations
• go-redis/v9 - Redis client integration
• uber-go/zap - structured logging
• air - local hot reload
• OpenAPI 3 - source of truth for HTTP contracts
• oapi-codegen - backend transport model generation from OpenAPI
• OpenTelemetry SDK + OTLP exporters - tracing, logs, and metrics
• HyperDX + OpenTelemetry Collector - local observability integration
• Docker Compose - local infrastructure orchestration

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.

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.

Optional flags:

• --service-name: sets the service identity used in .env.example and the root README title.
• --project-slug: sets the local stack slug used by docker/container/database naming.
• --api-title: sets info.title in docs/openapi.yaml.

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 account/health code is example domain—replace or remove it 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.