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-event-store.md

View on GitHub
# Data Patterns — Event Sourcing: Gate, Schema, and Event Store

Event sourcing pattern for Go Gin APIs when full audit trail and temporal queries are required.

---

## Gate — all must be true

- [ ] Full audit trail of every state change is a business or compliance requirement (not "nice to have")
- [ ] You need temporal queries: "what was the state at time T?"
- [ ] Multiple different projections of the same data are needed now (not speculatively)
- [ ] You accept: event store ops, projection rebuilds, eventual consistency, snapshot management
- [ ] Team has experience operating event-sourced systems

**Simpler alternative first:** An `audit_log` table covers 95% of audit requirements:

```sql
CREATE TABLE audit_log (
    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    entity_id   UUID        NOT NULL,
    entity_type TEXT        NOT NULL,
    action      TEXT        NOT NULL,  -- 'created', 'updated', 'deleted'
    actor_id    UUID,
    diff        JSONB,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX ON audit_log(entity_id, created_at DESC);
```

---

## Schema

```sql
CREATE TABLE events (
    id             BIGSERIAL PRIMARY KEY,
    aggregate_id   UUID        NOT NULL,
    aggregate_type TEXT        NOT NULL,
    event_type     TEXT        NOT NULL,
    payload        JSONB       NOT NULL,
    version        INT         NOT NULL,
    occurred_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    UNIQUE (aggregate_id, version)
);

CREATE TABLE snapshots (
    aggregate_id UUID PRIMARY KEY,
    version      INT  NOT NULL,
    state        JSONB NOT NULL
);
```

---

## Event Store

```go
type Event struct {
    ID            int64           `db:"id"`
    AggregateID   string          `db:"aggregate_id"`
    AggregateType string          `db:"aggregate_type"`
    EventType     string          `db:"event_type"`
    Payload       json.RawMessage `db:"payload"`
    Version       int             `db:"version"`
    OccurredAt    time.Time       `db:"occurred_at"`
}

type EventStore struct{ db *sqlx.DB }

// Append inserts events with optimistic concurrency via expectedVersion.
func (s *EventStore) Append(ctx context.Context, aggregateID string, events []Event, expectedVersion int) error {
    tx, err := s.db.BeginTxx(ctx, nil)
    if err != nil {
        return fmt.Errorf("begin tx: %w", err)
    }
    defer tx.Rollback()

    var currentVersion int
    err = tx.QueryRowContext(ctx,
        `SELECT COALESCE(MAX(version), 0) FROM events WHERE aggregate_id = $1`,
        aggregateID,
    ).Scan(&currentVersion)
    if err != nil {
        return fmt.Errorf("read version: %w", err)
    }
    if currentVersion != expectedVersion {
        return fmt.Errorf("optimistic lock: expected version %d, got %d", expectedVersion, currentVersion)
    }

    for i, e := range events {
        _, err = tx.ExecContext(ctx,
            `INSERT INTO events (aggregate_id, aggregate_type, event_type, payload, version, occurred_at)
             VALUES ($1, $2, $3, $4, $5, NOW())`,
            aggregateID, e.AggregateType, e.EventType, e.Payload, expectedVersion+i+1,
        )
        if err != nil {
            return fmt.Errorf("insert event: %w", err)
        }
    }
    return tx.Commit()
}

// Load retrieves all events for an aggregate, ordered by version.
func (s *EventStore) Load(ctx context.Context, aggregateID string) ([]Event, error) {
    var events []Event
    err := s.db.SelectContext(ctx, &events,
        `SELECT * FROM events WHERE aggregate_id = $1 ORDER BY version ASC`,
        aggregateID,
    )
    if err != nil {
        return nil, fmt.Errorf("load events: %w", err)
    }
    return events, nil
}
```

---

## See Also

- `data-patterns-event-sourcing-aggregate.md` — aggregate reconstruction, snapshot optimization, cost summary
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