Go Backend Project Structure

Field	Value
Type	Agent Reference
Source	~/.copilot/agents/_refs/go-backend-engineer/project-structure.md
Description	Not specified

Source Content

Go Backend Project Structure

Standardized directory tree for every Go service produced by the Go Backend Engineer agent. Follows clean architecture (handler → service → repository → domain) with explicit DI seams. Every service looks the same so engineers can move between them without re-learning layout.

Tree

/project-root
  /cmd
    /api                    # HTTP API entrypoint
      main.go
    /cli                    # CLI tool entrypoint (Kong)
      main.go
    /worker                 # Background worker entrypoint
      main.go
  /internal                 # Private application code
    /api                    # HTTP API layer
      /middleware           # HTTP middleware
        auth.go
        logging.go          # Zap + OpenTelemetry integration
        metrics.go          # Prometheus metrics
        recovery.go
        tracing.go          # OpenTelemetry tracing
      /<resource>           # One package per REST resource (e.g. user, auth)
        handler.go          # Fiber handlers
        request.get.go      # GET request DTOs
        request.post.go     # POST request DTOs
        request.put.go      # PUT request DTOs
        request.patch.go    # PATCH request DTOs
        request.delete.go   # DELETE request DTOs
        response.get.go     # GET response DTOs
        response.post.go    # POST response DTOs
        response.put.go     # PUT response DTOs
        response.list.go    # LIST/collection responses
        routes.go           # Route registration
    /service                # Business logic layer
      <resource>.go         # Service interface + impl per domain
    /repository             # Data access layer
      <resource>.go         # Repository interface
      /postgres             # PostgreSQL implementations
        <resource>.go
    /domain                 # Domain models and errors
      <resource>.go         # Core business entities
      errors.go             # Domain-specific errors
    /config                 # Configuration with Viper
      config.go             # Config structs
      viper.go              # Viper initialization
    /telemetry              # Observability wiring
      logger.go             # Zap setup
      tracing.go            # OpenTelemetry setup
      metrics.go            # Prometheus metrics
    /templates              # Go templates (html/text)
      /email
        welcome.html.tmpl
      /reports
        summary.txt.tmpl
  /pkg                      # Public/importable libraries
    /pool                   # Object pooling (sync.Pool wrappers)
    /validator              # Request validation helpers
    /errors                 # Error utilities
    /types                  # Shared types
  /api                      # OpenAPI specifications
    openapi.yaml            # Generated OpenAPI 3.1 spec
  /migrations               # Database migrations (Atlas or goose)
    000001_create_users.up.sql
    000001_create_users.down.sql
  /test                     # Test utilities
    /fixtures
    /mocks
    /testdata
  /scripts                  # Build/deploy scripts
  /configs                  # Configuration files
    config.yaml
    config.production.yaml
  /.p3                      # Platform-3 deployment artifacts (see SRE agent)
    /helm
    /argocd
  Taskfile.yml              # Task runner definitions
  .air.toml                 # Air hot-reload config
  .env.example
  go.mod
  go.sum
  Dockerfile                # Multi-stage, distroless final image

Per-layer responsibility

Layer	Responsibility	Imports allowed
cmd/*	Process entrypoint, DI wiring, signal handling	internal/*, pkg/*
internal/api/*	HTTP transport, request/response DTOs, validation	internal/service, internal/domain, internal/telemetry
internal/service/*	Business logic, transactions, orchestration	internal/repository, internal/domain, internal/telemetry
internal/repository/*	Persistence only, no business rules	internal/domain, GORM/sqlc/pgx
internal/domain/*	Pure types, errors, no I/O	stdlib only
internal/config	Viper loader, struct unmarshalling	Viper
internal/telemetry	Zap, OTel, Prometheus init	observability libs
pkg/*	Reusable, importable from outside	stdlib + minimal deps

Hard rules

• No upward imports — repository never imports service; domain never imports anything in internal/.
• One resource = one package under internal/api, internal/service, internal/repository.
• Interfaces live with the consumer, not the implementer (Go idiom). Service defines UserRepository; postgres package implements it.
• Function size limit: 75 lines. Split if longer.
• interface{} / any only at framework boundaries — never in business logic signatures.