Skip to content

henriqueatila/golang-gin-best-practices / skills/golang-gin-architect

golang-gin-architect

Verified

Software architect for Go Gin APIs. Use when making architecture decisions, evaluating complexity, designing systems, choosing patterns, or coordinating across gin skills.

FileKindSize
SKILL.mdskill md10.7 KB
metadata.jsonconfig466 B
references/adr-format-and-templates.mdmarkdown4.1 KB
references/adr-service-extraction-and-example.mdmarkdown4.0 KB
references/api-design-error-contract-docs.mdmarkdown1.8 KB
references/api-design-filtering-bulk-evolution.mdmarkdown3.8 KB
references/api-design-versioning-pagination.mdmarkdown4.3 KB
references/clean-architecture-feature-module.mdmarkdown4.5 KB
references/clean-architecture-layers-di.mdmarkdown5.2 KB
references/complexity-assessment-budget.mdmarkdown5.6 KB
references/complexity-assessment-gates.mdmarkdown4.2 KB
references/complexity-assessment-patterns.mdmarkdown5.0 KB
references/cross-cutting-health-checks.mdmarkdown1.7 KB
references/cross-cutting-observability.mdmarkdown3.9 KB
references/cross-cutting-security-config.mdmarkdown4.4 KB
references/data-ownership-boundaries.mdmarkdown4.5 KB
references/data-ownership-sync-migration.mdmarkdown4.3 KB
references/data-patterns-cqrs.mdmarkdown3.8 KB
references/data-patterns-event-sourcing-aggregate.mdmarkdown2.2 KB
references/data-patterns-event-store.mdmarkdown3.7 KB
references/data-patterns-outbox.mdmarkdown3.7 KB
references/data-patterns-read-replicas.mdmarkdown2.6 KB
references/data-patterns-saga.mdmarkdown3.6 KB
references/error-flow-domain-layers.mdmarkdown5.3 KB
references/error-flow-handler-chain.mdmarkdown4.7 KB
references/golden-main-medium-project.mdmarkdown3.0 KB
references/golden-main-medium-startup.mdmarkdown2.8 KB
references/golden-main-small-project.mdmarkdown4.0 KB
references/grpc-interop-gateway-docker.mdmarkdown2.1 KB
references/grpc-interop-server-client.mdmarkdown2.7 KB
references/grpc-interop-setup.mdmarkdown3.6 KB
references/messaging-consumer-docker.mdmarkdown1.6 KB
references/messaging-consumer-workqueues.mdmarkdown3.6 KB
references/messaging-dlq-idempotency.mdmarkdown3.1 KB
references/messaging-dlq-setup.mdmarkdown2.4 KB
references/messaging-pubsub-exchanges.mdmarkdown3.6 KB
references/messaging-rabbitmq-connection.mdmarkdown3.2 KB
references/messaging-rabbitmq-producer.mdmarkdown2.4 KB
references/object-storage-download-presign.mdmarkdown3.5 KB
references/object-storage-multipart-minio.mdmarkdown2.2 KB
references/object-storage-setup-upload.mdmarkdown4.2 KB
references/redis-cache-warming-pubsub.mdmarkdown3.2 KB
references/redis-caching-patterns.mdmarkdown4.3 KB
references/redis-session-distributed-lock.mdmarkdown3.9 KB
references/resilience-circuit-breaker-bulkhead.mdmarkdown4.3 KB
references/resilience-retry-rate-limiting.mdmarkdown4.0 KB
references/skill-orchestration-overview.mdmarkdown3.2 KB
references/skill-orchestration-workflows.mdmarkdown5.4 KB
references/system-design-bounded-contexts.mdmarkdown4.1 KB
references/system-design-c4-model.mdmarkdown4.6 KB
references/system-design-dependency-graphs.mdmarkdown2.6 KB
references/system-design-domain-modeling.mdmarkdown3.5 KB
references/system-design-project-structure.mdmarkdown4.2 KB
references/tech-debt-identification-prioritization.mdmarkdown5.1 KB
references/tech-debt-refactoring-communication.mdmarkdown4.0 KB

references/clean-architecture-feature-module.md

View on GitHub
# Clean Architecture — Feature Module Example and Decision Guide

Companion to `clean-architecture-layers-di.md` (layer mapping, dependency rule, ports & adapters, DI wiring).

---

## Complete Feature Module Layout

For medium+ projects using feature modules (recommended default):

```
internal/
├── user/
│   ├── domain/
│   │   ├── user.go           # Entity: User struct, validation
│   │   └── errors.go         # Domain errors: ErrUserNotFound, ErrDuplicateEmail
│   ├── usecase/
│   │   ├── ports.go          # Interface: UserRepository
│   │   └── user_service.go   # Business logic
│   ├── handler/
│   │   └── user_handler.go   # Gin HTTP handlers
│   └── repository/
│       └── postgres/
│           └── user_repository.go
├── order/
│   ├── domain/
│   ├── usecase/
│   ├── handler/
│   └── repository/
└── platform/                  # Shared infrastructure (not a domain)
    ├── database/
    ├── middleware/
    └── config/
```

---

## Domain Layer

```go
// internal/user/domain/user.go
type User struct {
    ID           int64     `db:"id" json:"id"`
    Email        string    `db:"email" json:"email"`
    Name         string    `db:"name" json:"name"`
    PasswordHash string    `db:"password_hash" json:"-"`
    CreatedAt    time.Time `db:"created_at" json:"created_at"`
}

// internal/user/domain/errors.go
var (
    ErrUserNotFound   = errors.New("user not found")
    ErrDuplicateEmail = errors.New("email already registered")
)
```

---

## Use Case Layer

```go
// internal/user/usecase/user_service.go
type UserService struct {
    repo   UserRepository
    logger *slog.Logger
}

func NewUserService(repo UserRepository, logger *slog.Logger) *UserService {
    return &UserService{
        repo:   repo,
        logger: logger.With("component", "user-service"),
    }
}

func (s *UserService) GetByID(ctx context.Context, id int64) (*domain.User, error) {
    user, err := s.repo.GetByID(ctx, id)
    if err != nil {
        return nil, fmt.Errorf("UserService.GetByID: %w", err)
    }
    return user, nil
}
```

---

## Common Mistakes

| Mistake | Why it's wrong | Fix |
|---|---|---|
| Interface next to implementation | Couples consumer to provider | Interface in `usecase/`, implementation in `repository/` |
| Domain type as JSON response | Leaks DB fields, breaks API contract | Use response DTOs in `handler/` |
| Business logic in handlers | Untestable without HTTP, violates SRP | Handlers: bind → call service → respond |
| Interface for everything | Over-abstraction | Only where you need to swap implementations |
| Clean arch for a 5-endpoint MVP | Over-engineering, YAGNI | Start flat, refactor when it hurts |
| Shared DB between services | Hidden coupling | Each service owns its data |
| `domain/` importing `gin` or `sqlx` | Violates dependency rule | Domain is stdlib-only |

---

## When to Use What

| Project Size | Recommended Structure | Clean Arch Level |
|---|---|---|
| MVP, < 10 endpoints, 1-2 devs | Flat: `handler/`, `service/`, `repository/`, `domain/` | Implicit layers only |
| Growing, 10-50 endpoints, 3-8 devs | Feature modules: `internal/user/`, `internal/order/` | Per-module ports in `usecase/` |
| Complex domain, 50+ endpoints, 8+ devs | Full clean arch with bounded contexts | Strict dependency rule, DTOs at boundaries |

**Rule of thumb:** Start flat. When you feel pain (circular deps, fat handlers, tests requiring real DB), introduce the next level. The moment you add a second adapter for an interface (in-memory repo for tests + postgres for prod), clean architecture has paid for itself.

### Gate — you need formal clean architecture when

- [ ] You have 2+ delivery mechanisms (HTTP + gRPC + CLI) calling the same business logic
- [ ] You need to swap infrastructure without touching business logic
- [ ] Multiple teams work on the same service and need clear ownership boundaries
- [ ] Test setup requires complex mocking because business logic is tangled with HTTP/DB

If none apply, flat layout with implicit layering (handler → service → repository) is clean architecture in spirit — without the ceremony.

---

## Cross-Skill References

- Project structure at different scales: `system-design-project-structure.md`
- Complexity budget (is this overkill?): `complexity-assessment-budget.md`
- Repository and ORM patterns: `golang-gin-database` skill
- Handler and middleware implementation: `golang-gin-api` skill
- Testing layers in isolation: `golang-gin-testing` skill
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall