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

View on GitHub
# Data Patterns — Saga Pattern (Orchestration)

Distributed transaction pattern for business transactions spanning multiple services.

---

## Gate — all must be true

- [ ] A business transaction spans multiple services or databases
- [ ] Each step can fail independently and may have already partially committed
- [ ] You need compensating actions (rollbacks that can't use a single DB transaction)
- [ ] A single `BEGIN / COMMIT` across one database is NOT sufficient

**Simpler alternative first:** If all data is in one PostgreSQL database, use a database transaction. If two services are involved, call them sequentially with explicit compensation:

```go
func (s *CheckoutService) Checkout(ctx context.Context, orderID string) error {
    if err := s.inventoryClient.Reserve(ctx, orderID); err != nil {
        return fmt.Errorf("reserve inventory: %w", err)
    }
    if err := s.paymentClient.Charge(ctx, orderID); err != nil {
        _ = s.inventoryClient.Release(ctx, orderID) // compensate
        return fmt.Errorf("charge payment: %w", err)
    }
    return nil
}
```

---

## Orchestrator Saga

Use when you have 3+ steps or need durable state across retries.

```go
type SagaStep struct {
    Name       string
    Execute    func(ctx context.Context, sagaID string) error
    Compensate func(ctx context.Context, sagaID string) error
}

type SagaOrchestrator struct {
    steps []SagaStep
    store SagaStateStore
}

type SagaStateStore interface {
    SaveProgress(ctx context.Context, sagaID string, completedStep int) error
    LoadProgress(ctx context.Context, sagaID string) (int, error)
    MarkFailed(ctx context.Context, sagaID string, reason string) error
    MarkCompleted(ctx context.Context, sagaID string) error
}

func (o *SagaOrchestrator) Run(ctx context.Context, sagaID string) error {
    lastCompleted, _ := o.store.LoadProgress(ctx, sagaID)
    completed := make([]int, 0, len(o.steps))

    for i, step := range o.steps {
        if i < lastCompleted {
            completed = append(completed, i)
            continue
        }
        slog.InfoContext(ctx, "saga step executing", "saga_id", sagaID, "step", step.Name)
        if err := step.Execute(ctx, sagaID); err != nil {
            slog.ErrorContext(ctx, "saga step failed", "saga_id", sagaID, "step", step.Name, "err", err)
            _ = o.store.MarkFailed(ctx, sagaID, err.Error())
            for j := len(completed) - 1; j >= 0; j-- {
                si := completed[j]
                if o.steps[si].Compensate != nil {
                    if cerr := o.steps[si].Compensate(ctx, sagaID); cerr != nil {
                        slog.ErrorContext(ctx, "compensation failed", "step", o.steps[si].Name, "err", cerr)
                    }
                }
            }
            return fmt.Errorf("saga %s failed at step %s: %w", sagaID, step.Name, err)
        }
        completed = append(completed, i)
        _ = o.store.SaveProgress(ctx, sagaID, i+1)
    }
    return o.store.MarkCompleted(ctx, sagaID)
}
```

**PostgreSQL state store schema:**

```sql
CREATE TABLE saga_state (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    saga_type       TEXT        NOT NULL,
    status          TEXT        NOT NULL DEFAULT 'running',
    completed_steps INT         NOT NULL DEFAULT 0,
    failure_reason  TEXT,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
```

**Complexity: HIGH (4/5)** — use sequential calls with manual compensation (2 services) or a DB transaction (single DB) instead.

---

## See Also

- `data-patterns-outbox.md` — Transactional Outbox pattern (atomic DB + message publish)
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