Skip to main content

Project Structure Guidelines

Layer Boundaries​

  • router MUST only define routes and attach middleware.
  • handlers MUST parse requests, validate input, call domain logic, and return responses.
  • services SHOULD own business rules and multi-step workflows.
  • models and repository MUST handle persistence concerns.
  • schemas MUST define transport contracts for request/response bodies.
  • internal/* MUST NOT be imported outside the module.

Dependency Management (go mod)​

  • Direct dependencies MUST be explicit in go.mod.
  • Teams MUST run go mod tidy after dependency updates.
  • CI SHOULD run go mod verify.
  • Local replace directives MUST NOT be committed unless intentionally required.

Startup Composition​

  • App bootstrap SHOULD initialize config, database clients, caches, and external clients once.
  • Shared clients MUST be injected downward; avoid hidden package globals for new features.
  • Startup-blocking failures SHOULD fail fast with clear logs.