ForgeLM/.agents/rules/project-structure-go-backend.md

trigger, description

trigger	description
model_decision	When working on a Go backend project, setting up Go project structure, or organizing Go services and APIs

Go Backend Layout

Use this structure for Go backend applications. The vertical slice principle applies — features are packages, not layers.

  apps/
    backend/                          # Backend application source code
      cmd/
        api/
          main.go                     # Entry point: Wires dependencies, router, starts server
      internal/                       # Private application code
        platform/                     # Foundational technical concerns (The "Framework")
          database/                   # DB connection logic
          server/                     # HTTP server setup (Router, Middleware)
          logger/                     # Structured logging setup
        features/                     # Business Features (Vertical Slices)
          task/                       # Task management
            # --- Interface Definition ---
            service.go                # The public API of this feature (Service struct)

            # --- Delivery (HTTP) ---
            handler.go                # HTTP Handlers
            handler_test.go           # Component tests (httptest + mock service)

            # --- Domain (Business Logic) ---
            logic.go                  # Core business logic methods
            logic_test.go             # Unit tests (Pure functions + mock storage)
            models.go                 # Domain structs (Task, NewTaskRequest)
            errors.go                 # Feature-specific errors

            # --- Storage (Data Access) ---
            storage.go                # Storage Interface definition
            storage_pg.go             # Postgres implementation
            postgres_integration_test.go # Integration tests (Real DB/Testcontainers)
            storage_mock.go           # Mock implementation
            ...
          order/                      # Order management
            handler.go
            logic.go
            storage.go
          ...

Key Go conventions:

• cmd/ for entry points — each subdirectory is a separate binary
• internal/ for private packages — enforced by Go compiler (cannot be imported externally)
• platform/ for foundational concerns (database, server, logger)
• features/ for vertical business slices — each feature is self-contained
• Tests live alongside the code they test (_test.go suffix)
• go.mod at the root — single module for the entire application

Related Principles

• Project Structure @project-structure.md (core philosophy)
• Go Idioms and Patterns @go-idioms-and-patterns.md (coding idioms, error handling, naming)