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-layers-di.md

View on GitHub
# Clean Architecture — Layer Mapping, Dependency Rule, and DI

Practical guide to applying Clean Architecture in Go Gin APIs.

**Default stance:** Start with flat package layout. Adopt clean architecture layering when the codebase outgrows it — not before.

---

## Layer Mapping: Uncle Bob → Go

```
┌─────────────────────────────────────────────────────┐
│  cmd/api/main.go          ← Wiring (imports all)    │
│  ┌─────────────────────────────────────────────┐    │
│  │  handler/              ← Driving Adapters    │    │
│  │  ┌─────────────────────────────────────┐    │    │
│  │  │  usecase/ or service/               │    │    │
│  │  │  ┌─────────────────────────────┐    │    │    │
│  │  │  │  domain/  (stdlib only)     │    │    │    │
│  │  │  └─────────────────────────────┘    │    │    │
│  │  └─────────────────────────────────────┘    │    │
│  └─────────────────────────────────────────────┘    │
│  repository/              ← Driven Adapters          │
└─────────────────────────────────────────────────────┘
```

| Uncle Bob Layer | Go Package | Imports | Contains |
|---|---|---|---|
| Entities | `domain/` | stdlib only | Structs, value objects, domain errors |
| Use Cases | `usecase/` or `service/` | `domain/` only | Business logic, port interfaces |
| Interface Adapters | `handler/`, `repository/` | `usecase/`, `domain/` | Gin handlers, sqlx repos |
| Frameworks & Drivers | `cmd/api/main.go` | everything | Wiring, config, server startup |

**Go-specific twist:** Interfaces are defined in the **consuming** package (`usecase/`), not the implementing package (`repository/`). This is idiomatic Go and structurally enforces the dependency rule.

---

## The Dependency Rule

> Inner layers NEVER import outer layers. Dependencies point inward.

```
domain/    → imports: nothing (stdlib only)
usecase/   → imports: domain/
handler/   → imports: usecase/, domain/
repository/→ imports: usecase/ (for interface), domain/ (for entities)
cmd/       → imports: everything (wiring only)
```

**Compile-time interface check** — always add in the adapter package:

```go
// repository/postgres/user_repository.go
var _ usecase.UserRepository = (*UserRepository)(nil)
```

Fails at compile time if `UserRepository` doesn't satisfy the interface. Zero runtime cost.

---

## Ports & Adapters

A **port** is a Go interface. An **adapter** is an implementation.

Port (defined in usecase package):

```go
// internal/user/usecase/ports.go
type UserRepository interface {
    GetByID(ctx context.Context, id int64) (*domain.User, error)
    Create(ctx context.Context, user *domain.User) error
    GetByEmail(ctx context.Context, email string) (*domain.User, error)
}
```

Driven adapter (sqlx implementation):

```go
var _ usecase.UserRepository = (*UserRepository)(nil)

func (r *UserRepository) GetByID(ctx context.Context, id int64) (*domain.User, error) {
    var u domain.User
    err := r.db.GetContext(ctx, &u,
        `SELECT id, email, name, created_at FROM users WHERE id = $1`, id)
    if err != nil {
        return nil, fmt.Errorf("UserRepository.GetByID: %w", err)
    }
    return &u, nil
}
```

Driving adapter (Gin handler):

```go
func (h *UserHandler) GetByID(c *gin.Context) {
    id, err := strconv.ParseInt(c.Param("id"), 10, 64)
    if err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "invalid user id"})
        return
    }
    user, err := h.svc.GetByID(c.Request.Context(), id)
    if err != nil {
        c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})
        return
    }
    c.JSON(http.StatusOK, user)
}
```

---

## Wiring with Manual DI

**Manual DI in `main.go`** is the Go-idiomatic choice. Wire/fx only justifies itself at 20+ services.

```go
func main() {
    logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))

    db, err := sqlx.Connect("postgres", os.Getenv("DATABASE_URL"))
    if err != nil {
        logger.Error("database connection failed", "error", err)
        os.Exit(1)
    }

    // Wire: repo → service → handler
    userRepo := userPostgres.NewUserRepository(db)
    userSvc  := userUsecase.NewUserService(userRepo, logger)
    userH    := userHandler.NewUserHandler(userSvc)

    r := gin.New()
    r.Use(gin.Recovery())

    api := r.Group("/api/v1")
    api.GET("/users/:id", userH.GetByID)

    r.Run(":8080")
}
```

**The wiring rule:** `main.go` is the only file that knows about ALL packages.

---

## See Also

- `clean-architecture-feature-module.md` — complete feature module example, common mistakes, when to use what
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: 323kUpdated 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