go-backend-architecture

Go Backend Architecture

A modular Go backend template built with Clean Architecture. Business workflows stay independent of delivery and infrastructure. Each runnable application wires the capabilities it needs, and new process types can reuse the same core. The template includes foundations for security, data access, observability, testing, and lifecycle management.

Table of Contents

• Included capabilities
• Architecture
• Delivery adapters
• Runtime reliability
• Observability
• Data design
• Testing and CI
• AI agent setup
• Third-party tools
• Repository map
• Use as a Starter

Included capabilities

Architecture

Go imports follow the arrows in the diagram. Usecases do not import delivery or infrastructure, so changes to a server or storage adapter stay outside business code.

The rings group code by responsibility; the arrows specify imports. Sharing a ring does not mean two packages have identical dependencies.

Multi-binary composition

Each binary has its own cmd entry point and internal/app composition root. Binaries can reuse domain, usecases, contracts, and infrastructure adapters without moving business code into delivery packages.

flowchart LR
    http[HTTP binary] --> core[Shared domain · usecases · contracts]
    grpc[gRPC binary] --> core
    future[Future worker or consumer] -.-> core

Separate binaries can be deployed and scaled independently while sharing application behavior.

SOLID in this codebase

SOLID is applied through package boundaries and dependency direction.

• S — Single responsibility: delivery maps protocols, usecases coordinate workflows, repositories define outbound needs, infrastructure integrates technologies, and app packages only compose them.
• O — Open/closed: a new delivery adapter, provider, store, decorator, or binary is normally added behind an existing contract and selected in composition. A contract still changes when the application genuinely needs new behavior.
• L — Liskov substitution: implementations of a contract preserve its result, error, context, and consistency semantics, so callers do not need implementation-specific branches when an adapter or test double is substituted.
• I — Interface segregation: contracts expose focused behavior required by a usecase or component instead of broad CRUD or vendor-shaped APIs.
• D — Dependency inversion: usecases depend on repository and shared technical contracts; app packages inject infrastructure implementations. Delivery depends on usecase behavior rather than constructing stores or clients.

Core design patterns

The complete dependency, placement, error, performance, and testing rules are in AGENTS.md.

Delivery adapters

Out of the box, the template has a browser/public HTTP application and a service-to-service gRPC application; a selected project may retain either or both. They can share business and infrastructure capabilities while each delivery package owns its transport-specific input, output, and error handling.

Public HTTP

The HTTP application is designed for browser and public API traffic. It owns user-facing authentication, server-side protections, JSON response semantics, and streaming behavior.

The request path is ordered deliberately:

body limit → observability → recovery → security/CORS → request context → rate limit → handler → usecase

See internal/delivery/http/README.md for package ownership and extension guidance.

Service-to-service gRPC

The gRPC application is designed for independently deployed backend services. A Protobuf service method is comparable to an HTTP route, a Protobuf message to a transport DTO, metadata to headers, an interceptor to middleware, and a gRPC status code to an HTTP status at the protocol boundary.

The unary and stream interceptor chain follows the same ownership model as HTTP middleware:

request context → optional caller identity → observability → recovery → service → usecase

Both chains put recovery inside observability so recovered panics appear in telemetry. HTTP starts observability before request context because Echo lets inner middleware replace the request; outer middleware reads its updated context on return. CORS runs before the limiter so preflight requests can finish early.

gRPC interceptors cannot pass an updated context back outward. Request context and optional caller identity therefore run before observability, which needs their values. Authentication and rate limiting are not universal gRPC interceptors: deployments may enforce them at a gateway or service mesh, while standalone services can add interceptors matched to their identity and quota model.

See internal/delivery/grpc/README.md and internal/infra/grpcclient/README.md for the server and outbound-client boundaries.

Runtime reliability

The template makes request limits, background work, and shutdown explicit.

• Cancellation and deadlines reach storage and outbound calls, so work can stop when a caller disconnects or its time limit expires.
• Background tasks use an application-lifecycle context, not a request context. The component that starts a goroutine controls how it stops and waits for it to finish; concurrent work is bounded.
• Retries have bounded attempts and repeat writes only when an idempotency design makes that safe.
• Shutdown stops components in reverse dependency order and reports cleanup failures.
• Errors retain their original causes; unexpected failures are logged once where they are handled.

See AGENTS.md for the corresponding implementation rules.

Observability

Tracing and metrics use interfaces in internal/observability, while structured logs use internal/logger. Their OpenTelemetry integration lives in infrastructure, so delivery adapters, usecases, and infrastructure operations can record telemetry without importing the SDK.

Trace propagation and correlation

The diagram follows one request across services; work inside a service can have its own spans and metrics.

sequenceDiagram
    participant U as Upstream caller
    participant A as This service
    participant D as Trusted downstream
    participant O as OTLP collector / HyperDX

    U->>A: Request with optional traceparent and tracestate
    A->>A: Extract parent if present, then start inbound span
    A->>A: Create child spans for selected internal work
    opt Propagation enabled for this dependency
        A->>D: Inject active trace context
        D-->>A: Response
    end
    A->>O: Export spans, metrics, and correlated logs

The OpenTelemetry SDK creates trace and span IDs locally, even when the collector is unavailable. An inbound adapter extracts valid parent context when present, and spans created during internal work inherit it. For a trusted outbound dependency, optional injection lets a downstream service that extracts the context join the same trace; external providers do not automatically receive internal correlation metadata.

Zap output and OTLP logs read trace and span IDs from the active OpenTelemetry span context. HyperDX can therefore navigate between a log and its trace when both signals arrive with those native IDs. Local logs remain useful when export is unavailable, but they are a diagnostic fallback—not a replacement for the spans that were not collected.

x-request-id is a separate, optional convention for gateways, support workflows, or systems that do not share trace context. The current HTTP and gRPC adapters accept valid caller-provided IDs under configurable keys and may return them; they do not generate an ID when absent. Selected internal clients can propagate it explicitly.

Traces or logs can record request-specific details such as the exact path /users/42, an error message, or an ID when safe. Metrics instead use stable labels such as the route pattern /users/:id and status code; individual paths or IDs would create a separate metric series for many requests.

See internal/observability/README.md and the transport instrumentation guides for HTTP and gRPC.

Data design

SQL-first PostgreSQL

SQL stays behind repository contracts, keeping PostgreSQL and generated types out of business APIs. Rather than relying on an ORM to generate queries, the template writes SQL directly. This keeps joins, batching, locking, and selected columns explicit, making query behavior easier to review and important queries easier to tune with query plans. The tradeoff is more SQL and mapping code; an ORM can be reasonable for a CRUD-heavy application where convenience matters more.

AGENTS.md also gives guidance for repository operations and SQL: methods should follow usecase needs rather than generic CRUD. Related reads should be shaped to avoid N+1 access; stable cacheable data may be separated from volatile data when the extra round trip has a measured consistency or reuse benefit. Multi-write workflows should expose one atomic repository operation, leaving transaction handles inside the PostgreSQL adapter. Indexes and material query changes should be evaluated against actual access patterns and query plans.

Redis caching and state

Redis serves two roles here. Cached data can be reloaded from a primary store, while short-lived state such as sessions, OTPs, and rate-limit counters directly affects feature behavior. Separate adapters let each role define its own failure policy.

A composed adapter can implement the cache policy a feature needs—for example, read-through, write-through, write-behind, or explicit invalidation. That policy must define acceptable staleness and how cache read, write, and invalidation failures affect the operation.

See internal/infra/db/postgres/store/README.md and internal/infra/composed/README.md for adapter-specific guidance.

Testing and CI

Unit tests check one component with its dependencies controlled. Integration tests check real boundaries, such as a storage adapter with its database or a server's request path through its delivery code.

See AGENTS.md for test-double and concurrency-test rules.

AI agent setup

The repository keeps coding guidance in one place so agents follow the same conventions.

See the Codex AGENTS.md guide and Cursor rules documentation for how they load repository instructions.

Third-party tools

Repository map

cmd/                         process entry points
contracts/                   OpenAPI and Protobuf sources
internal/
├── app/                     composition roots and shared runtime lifecycle
├── delivery/                HTTP and gRPC inbound adapters
├── domain/                  business entities and reusable invariants
├── usecase/                 application workflows
├── repository/              outbound capability contracts
├── infra/                   database, cache, provider, security, and telemetry adapters
├── logger/                  shared logging contract
├── observability/           shared telemetry contracts and context helpers
└── security/                shared security contracts
make/                        capability-owned Make targets
tools/                       one-time profile selection and project bootstrap

Use as a Starter

Requirements

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

1. Choose the source shape

Keep both applications, or preview and apply one profile before bootstrapping:

# Preview first; no files are changed.
go run ./tools/profile-selector --profile public-http
go run ./tools/profile-selector --profile service-grpc

# Keep exactly one profile.
go run ./tools/profile-selector --profile public-http --apply
# or
go run ./tools/profile-selector --profile service-grpc --apply

The selector requires a clean checkout, removes the unused capability and itself, installs the selected .air.toml, sqlc.yaml, and .env.example, and writes .template-profile. Commit the selection before the next step.

2. Bootstrap project identity

./tools/bootstrap-template.sh --module github.com/your-org/your-backend
go mod tidy

The bootstrap updates module/import paths, service and local resource names, contract package paths, and the README title. It does not rename the checkout directory or configure the Git remote.

3. Start local dependencies and the application

cp .env.example .env
make install
make dev-up
make migrate-up  # when the selected source includes database migrations

Run the default installed application with make run, or choose explicitly when both are present:

make run-httpapi  # HTTP on :8080
make run-grpcapi  # gRPC on :9090

Verify the HTTP health endpoint:

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

With grpcurl installed and local reflection enabled, verify the standard gRPC health service:

grpcurl -plaintext \
  -d '{"service":"diagnostics.v1.DiagnosticsService"}' \
  localhost:9090 grpc.health.v1.Health/Check

The local stack exposes PostgreSQL on 5432, Redis on 6379, HyperDX on 8081, and OTLP on 4317/4318.

4. Verify the project

make check             # formatting, vet, and build
make test              # unit tests
make test-race         # unit tests with race detection
make test-integration  # HTTP, gRPC, and storage integration tests
make ci                # complete sequence once the project has a contract baseline

During the initial identity bootstrap, use the individual checks before comparing contracts with an earlier commit. Later, make ci runs contract compatibility checks against the configured Git baseline as well as the complete test sequence.

Contract-specific commands are available when their capability is installed:

make openapi-generate openapi-check
make proto-generate proto-check

Use make dev-logs to follow local infrastructure and make dev-down to stop it. The transport processes can be stopped separately with make run-httpapi-stop or make run-grpcapi-stop.