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/grpc-interop-setup.md

View on GitHub
# gRPC Interoperability — When to Use and Project Setup

**Default stance:** Do not add gRPC unless you have a real need. REST with Gin is sufficient for most projects. gRPC adds protobuf compilation, code generation, and operational complexity.

**Cost: HIGH (4/5).** Only justified when REST genuinely cannot meet requirements.

---

## When to Use gRPC

```
START: Do you need gRPC?
  ├── All clients are web/mobile? → No. REST with Gin. Stop.
  └── Service-to-service communication?
      ├── < 5 services, simple payloads? → REST is fine. Stop.
      └── High throughput, strict contracts, streaming needed?
          ├── Streaming (bidirectional)? → gRPC. Worth the complexity.
          └── Just strict contracts + perf? → gRPC, but consider
                gRPC-Gateway for external REST consumers.
```

**You DO need gRPC when:** bidirectional or server-side streaming; tight latency budgets (< 10ms p99); strict schema contracts enforced at build time; 10+ internal services.

**You do NOT need gRPC when:** all consumers are browsers or mobile apps; fewer than 5 services; team unfamiliar with protobuf toolchain; no existing gRPC infrastructure.

---

## Project Structure

```
myapp/
├── cmd/
│   ├── api/main.go          # HTTP entry point (Gin)
│   └── server/main.go       # Combined HTTP + gRPC entry point
├── internal/user/
│   ├── domain/user.go       # Domain types (shared)
│   ├── usecase/             # Business logic (shared by both handlers)
│   ├── handler/             # Gin HTTP handlers
│   ├── grpchandler/         # gRPC handlers (calls same usecase)
│   └── repository/
├── proto/
│   ├── buf.yaml
│   ├── buf.gen.yaml
│   └── user/v1/user.proto
└── gen/                     # Generated protobuf Go code (do not edit)
    └── user/v1/
```

Key principle: both `handler/` (HTTP) and `grpchandler/` (gRPC) import from `usecase/`. Business logic lives once.

### buf.yaml

```yaml
version: v2
modules:
  - path: proto
deps:
  - buf.build/googleapis/googleapis
```

### buf.gen.yaml

```yaml
version: v2
plugins:
  - remote: buf.build/protocolbuffers/go
    out: gen
    opt:
      - paths=source_relative
  - remote: buf.build/grpc/go
    out: gen
    opt:
      - paths=source_relative
```

Generate with: `buf generate`

---

## Shared Service Layer

Both handlers call the same `UserService`. Business logic is never duplicated.

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

func (s *UserService) GetByID(ctx context.Context, id string) (*domain.User, error) {
    return s.repo.FindByID(ctx, id)
}
```

```go
// internal/user/handler/user_handler.go — HTTP (Gin)
func (h *UserHandler) GetByID(c *gin.Context) {
    id := c.Param("id")
    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, gin.H{"id": user.ID, "name": user.Name})
}
```

```go
// internal/user/grpchandler/user_handler.go — gRPC
func (h *UserGRPCHandler) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.GetUserResponse, error) {
    user, err := h.svc.GetByID(ctx, req.GetId())
    if err != nil {
        return nil, err // wrap with grpc/status codes in production
    }
    return &pb.GetUserResponse{Id: user.ID, Name: user.Name}, nil
}
```

---

## See Also

- `grpc-interop-server-client.md` — gRPC server setup, cmux multiplexer, client, gateway, Docker
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