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-outbox.md

View on GitHub
# Data Patterns — Transactional Outbox

Atomic DB + message delivery pattern. Companion to `data-patterns-saga.md`.

---

## Gate — all must be true

- [ ] You need to atomically update a database record AND publish a message/event
- [ ] "At-least-once" delivery is a requirement (losing messages is not acceptable)
- [ ] You cannot use a distributed transaction (2PC) or it is too expensive

---

## Schema

```sql
CREATE TABLE outbox (
    id           UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
    topic        TEXT        NOT NULL,
    payload      JSONB       NOT NULL,
    status       TEXT        NOT NULL DEFAULT 'pending',
    created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    processed_at TIMESTAMPTZ
);
CREATE INDEX ON outbox(status, created_at) WHERE status = 'pending';
```

---

## Writer — Atomic DB Update + Outbox Insert

```go
func (r *Repository) CreateWithOutbox(ctx context.Context, cmd CreateOrderCommand) (string, error) {
    tx, err := r.db.BeginTxx(ctx, nil)
    if err != nil {
        return "", fmt.Errorf("begin tx: %w", err)
    }
    defer tx.Rollback()

    var id string
    err = tx.QueryRowContext(ctx,
        `INSERT INTO orders (user_id, status) VALUES ($1, 'pending') RETURNING id`,
        cmd.UserID,
    ).Scan(&id)
    if err != nil {
        return "", fmt.Errorf("insert order: %w", err)
    }

    payload, _ := json.Marshal(map[string]string{"order_id": id, "user_id": cmd.UserID})
    _, err = tx.ExecContext(ctx,
        `INSERT INTO outbox (topic, payload) VALUES ('order.created', $1)`, payload)
    if err != nil {
        return "", fmt.Errorf("insert outbox: %w", err)
    }
    return id, tx.Commit()
}
```

---

## Publisher — Poll and Dispatch

```go
type MessageBroker interface {
    Publish(ctx context.Context, topic string, payload json.RawMessage) error
}

type OutboxPublisher struct {
    db     *sqlx.DB
    broker MessageBroker
}

func (p *OutboxPublisher) Run(ctx context.Context, interval time.Duration) {
    ticker := time.NewTicker(interval)
    defer ticker.Stop()
    for {
        select {
        case <-ticker.C:
            if err := p.processBatch(ctx); err != nil {
                slog.ErrorContext(ctx, "outbox publish failed", "err", err)
            }
        case <-ctx.Done():
            return
        }
    }
}

type outboxRow struct {
    ID      string          `db:"id"`
    Topic   string          `db:"topic"`
    Payload json.RawMessage `db:"payload"`
}

func (p *OutboxPublisher) processBatch(ctx context.Context) error {
    var rows []outboxRow
    err := p.db.SelectContext(ctx, &rows,
        `SELECT id, topic, payload FROM outbox WHERE status = 'pending'
         ORDER BY created_at LIMIT 100 FOR UPDATE SKIP LOCKED`)
    if err != nil {
        return fmt.Errorf("select outbox: %w", err)
    }
    for _, row := range rows {
        if err := p.broker.Publish(ctx, row.Topic, row.Payload); err != nil {
            _, _ = p.db.ExecContext(ctx,
                `UPDATE outbox SET status = 'failed' WHERE id = $1`, row.ID)
            continue
        }
        _, _ = p.db.ExecContext(ctx,
            `UPDATE outbox SET status = 'sent', processed_at = NOW() WHERE id = $1`, row.ID)
    }
    return nil
}
```

**Idempotent consumers:** Each consumer must deduplicate by `outbox.id`. Store processed IDs in a `processed_messages(id UUID PRIMARY KEY, processed_at TIMESTAMPTZ)` table.

---

## Pattern Comparison

| Pattern | Complexity | When to Use | Simple Alternative |
|---|---|---|---|
| Saga (Orchestrator) | HIGH (4/5) | 3+ cross-service steps + compensations | Sequential calls with manual compensation |
| Transactional Outbox | MEDIUM (3/5) | Atomic DB + message publish required | Write DB then publish; retry on failure |
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