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/data-patterns-cqrs.md

View on GitHub
# Data Patterns — CQRS (Command Query Responsibility Segregation)

High-complexity pattern for Go Gin APIs with divergent read/write models.

Companion to `data-patterns-read-replicas.md` (read replica pool, replication lag handling).

**Default stance:** PostgreSQL + clean repositories handles more than you think.

---

## Gate — all must be true

- [ ] Read and write models are fundamentally different shapes (not just different subsets of the same row)
- [ ] Read volume is 10x+ write volume AND the read path is the bottleneck
- [ ] A single PostgreSQL primary + read replica is not enough
- [ ] Your team has at least 3 engineers who understand the pattern

**Simpler alternative first:** Separate `ReadUser()` / `WriteUser()` methods in the same repository. Add a PostgreSQL materialized view for denormalized reads.

```sql
-- Read-optimized view — refresh on schedule or via trigger
CREATE MATERIALIZED VIEW order_summary AS
SELECT o.id, o.user_id, u.name AS user_name,
       COUNT(oi.id) AS item_count,
       SUM(oi.price * oi.quantity) AS total_amount,
       o.status, o.created_at
FROM orders o
JOIN users u ON u.id = o.user_id
JOIN order_items oi ON oi.order_id = o.id
GROUP BY o.id, o.user_id, u.name, o.status, o.created_at;

CREATE UNIQUE INDEX ON order_summary(id);
```

---

## Go Implementation

```go
// internal/order/command.go — Write side: normalized domain model
package order

type CreateOrderCommand struct {
    UserID string
    Items  []OrderItemInput
}

type OrderWriteRepo interface {
    Create(ctx context.Context, userID string, items []OrderItemInput) (string, error)
}

type OrderCommandHandler struct{ repo OrderWriteRepo }

func (h *OrderCommandHandler) CreateOrder(ctx context.Context, cmd CreateOrderCommand) (string, error) {
    if len(cmd.Items) == 0 {
        return "", fmt.Errorf("order must have at least one item")
    }
    id, err := h.repo.Create(ctx, cmd.UserID, cmd.Items)
    if err != nil {
        return "", fmt.Errorf("create order: %w", err)
    }
    return id, nil
}
```

```go
// internal/order/query.go — Read side: denormalized view
package order

type OrderView struct {
    ID          string    `db:"id"`
    UserName    string    `db:"user_name"`
    ItemCount   int       `db:"item_count"`
    TotalAmount int64     `db:"total_amount"`
    Status      string    `db:"status"`
    CreatedAt   time.Time `db:"created_at"`
}

type OrderQueryHandler struct{ db *sqlx.DB }

func (h *OrderQueryHandler) ListOrders(ctx context.Context, userID string, page, limit int) ([]OrderView, error) {
    var views []OrderView
    q := `SELECT * FROM order_summary WHERE user_id = $1 ORDER BY created_at DESC LIMIT $2 OFFSET $3`
    if err := h.db.SelectContext(ctx, &views, q, userID, limit, (page-1)*limit); err != nil {
        return nil, fmt.Errorf("list orders: %w", err)
    }
    return views, nil
}
```

```go
// internal/order/handler.go — Wire both sides
type Handler struct {
    cmd   *OrderCommandHandler
    query *OrderQueryHandler
}

func (h *Handler) Create(c *gin.Context) {
    var cmd CreateOrderCommand
    if err := c.ShouldBindJSON(&cmd); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    id, err := h.cmd.CreateOrder(c.Request.Context(), cmd)
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"error": "internal error"})
        return
    }
    c.JSON(http.StatusCreated, gin.H{"id": id})
}
```

---

## Pattern Comparison

| Pattern | Complexity | When Prerequisites Are Met | Simple Alternative |
|---|---|---|---|
| CQRS | HIGH (4/5) | Read/write shapes diverge + 10x read volume + replica not enough | Separate read/write methods + materialized view |
| Read Replicas | MEDIUM (3/5) | Read/write ratio > 5:1 AND primary is measured bottleneck | Add indexes; run EXPLAIN ANALYZE |
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