---

name: architecture description: Clean/hexagonal architecture rules, folder structure, interface ownership, and dependency direction. Use when creating new packages, services, or understanding codebase structure. userInvokable: true

Clean Architecture

References: Examples

Dependency Rule

Dependencies point inward. Outer layers depend on inner, never reverse. Avoid circular dependencies.

Interface Ownership

Example

• Interfaces defined where used, not where implemented
• Each usecase defines only methods it needs (Interface Segregation)
• Interfaces are unexported and private to package
• No ports/, interfaces/, or contracts/ packages

Folder Structure

Example

Package Boundaries

• internal/ - Private to service
• pkg/ - Shared utilities for other repos

Domain Structure

Example

Each domain in internal/<domain>/ follows:

Copy<domain>/
├── input.go           # Input DTOs
├── output.go          # Output DTOs
├── usecase/
│   ├── service.go     # Business logic + interfaces
│   └── service_mock.go
├── repository/
│   └── repository.go
└── model/
    └── entity.go      # Domain entities