golang-architecture

name	golang-architecture
description	Standards for structural design, Clean Architecture, and project layout in Golang. Use when structuring Go projects or applying Clean Architecture in Go. (triggers: go.mod, internal/**, architecture, structure, folder layout, clean arch, dependency injection)

Golang Architecture Standards

Priority: P0 (CRITICAL)

Principles

• Clean Architecture: Separate concerns. Inner layers (Domain) rely on nothing. Outer layers (Adapters) rely on Inner.
• Project Layout: Follow standard Go project layout (cmd, internal, pkg).
• Dependency Injection: Explicitly pass dependencies via constructors. Avoid global singletons.
• Package Oriented Design: Organize by feature/domain, not by layer (avoid controllers/, services/ at root).
• Interface Segregation: Define interfaces where they are used (Consumer implementation).

Standard Project Layout

See Standard Project Layout for directory tree.

Layer Rules

• Domain: Inner-most. No deps.
• UseCase: Depends on Domain.
• Adapter: Outer-most. Depends on UseCase/Domain.

Guidelines

• Use Constructors: NewService(repo Repository) *Service.
• Inversion of Control: Service depends on Repository interface, not SQLRepository struct.
• Wire up in Main: Main function composes the dependency graph.

Verification Checklist (Mandatory)

• No Globals: Are there any global singletons or package-level variables being mutated?
• DI: Are dependencies explicitly passed via constructors?
• Interfaces: Are interfaces defined at the consumer side (where they are used)?
• Layering: Does internal/domain have zero external dependencies?
• Composition: Are dependencies wired together in main.go?

Anti-Patterns

• No Global Singletons: Use DI; avoid package-level mutable variables.
• No Layer Violations: Domain must not import from adapter/infrastructure layers.
• No God Services: Split large services into single-responsibility components.

References

• Standard Project Layout
• Clean Architecture Layers