backend-dev-guidelines

Clean Architecture separates your Go backend into layers: handlers receive HTTP requests, services contain business logic, and the database layer executes type-safe queries. This layering reduces coupling, improves testability, and makes your codebase maintainable as it grows.

Use sqlc to generate type-safe SQL queries from your schema. sqlc eliminates runtime query errors by catching mistakes at compile time, ensuring your Go code and PostgreSQL queries stay synchronized without manual mapping.

Define authentication middleware using jwt/v5 to validate tokens on protected routes, then pass the authenticated user context to your handlers and services. Combine this with structured logging and correlation IDs to track authenticated requests end-to-end.

Interfaces enable interface-first design, letting you define service contracts before implementation and swap implementations for testing. Go's compile-time interface verification catches missing methods early, making your layered architecture robust and testable.

Use zerolog for structured logging with correlation IDs attached to requests, and define typed errors for different failure modes. Structured logs and typed errors make debugging faster and enable better observability across your API.

Yes. Chi integrates seamlessly into the handler layer of Clean Architecture. Chi routes map HTTP requests to handlers, which delegate to services for business logic, keeping routing concerns separate from domain logic.