hoangnguyen0403/golang-architecture

Golang Architecture

Priority: P0 (CRITICAL)

Principles

• Clean Architecture: Inner layers (Domain) rely on nothing. Outer layers (Adapters) rely on inner.
• Project Layout: Follow standard Go layout (cmd, internal, pkg).
• Dependency Injection: Pass dependencies via constructors. Avoid global singletons.
• Package Oriented Design: Organize by feature/domain, not by layer.
• Interface Segregation: Define interfaces where they used (consumer side).

Implementation Workflow

1. Set up project layout — Use cmd/ for entry points, internal/ for private packages, pkg/ for shared libraries.
2. Define domain layer — Inner-most layer with zero external dependencies.
3. Build use cases — Depend only on Domain interfaces.
4. Implement adapters — Outer layer depends on UseCase/Domain. Contains HTTP handlers, DB repos, etc.
5. Wire in main — Compose full dependency graph in main.go.

See constructor injection and wiring examples

Verification Checklist

• [ ] No global singletons or package-level mutable variables
• [ ] Dependencies explicitly passed via constructors
• [ ] Interfaces defined at consumer side
• [ ] internal/domain zero external dependencies
• [ ] Dependencies wired together in main.go

Anti-Patterns

• No global singletons: use DI; avoid package-level mutable variables.
• No layer violations: keep Domain imports isolated from adapter/infrastructure layers.
• No god services: split services into single-responsibility components.

References

• Standard Project Layout
• Clean Architecture Layers