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/complexity-assessment-patterns.md

View on GitHub
# Complexity Assessment — Pattern Selection Matrix and Right-Size Thinking

Pattern selection with complexity costs, gates, and the right-size matrix by team/stage.

---

## Right-Size Thinking Matrix

Find the row that best matches your situation. Use "Max Pattern Score" as a ceiling.

| Team Size | Stage | Traffic (RPM) | Data Complexity | Recommended Architecture | Max Score |
|---|---|---|---|---|---|
| 1–3 | MVP | < 1K | CRUD | Flat layout, direct SQL with sqlx | 5–8 |
| 1–3 | MVP | < 1K | Relational | handler → service → repository, PostgreSQL | 8–10 |
| 1–3 | Growth | 1K–10K | Relational | Same + Redis for caching hot reads | 10–13 |
| 3–8 | MVP | < 10K | Relational | Feature modules, shared repository interfaces | 12–15 |
| 3–8 | Growth | 10K–100K | Relational + events | Feature modules + async worker, Redis queue | 15–20 |
| 3–8 | Growth | 10K–100K | Complex rules | Domain services per bounded area | 16–20 |
| 8–15 | Growth | 10K–100K | Relational | Modular monolith, consider 1–2 service extractions | 18–22 |
| 8–15 | Mature | 100K+ | Mixed | Limited microservices (proven pain only), CQRS for read-heavy | 22–28 |
| 15+ | Mature | 100K+ | Event-driven | Multiple services, event sourcing for audit-critical domains | 28+ |

---

## Pattern Selection Matrix

### Repository Pattern

| | |
|---|---|
| Complexity cost | 1 |
| What it solves | Decouples business logic from data access; enables mocking in tests |
| You need it when | You want to mock the DB in unit tests, or have more than one data source |
| You DON'T need it if | Building a prototype where tests aren't required |

```go
type Repository interface {
    GetByID(ctx context.Context, id string) (*User, error)
    Create(ctx context.Context, u *User) error
}
```

### Service Layer

| | |
|---|---|
| Complexity cost | 1 |
| What it solves | Business logic outside handlers; testable without HTTP |
| You need it when | You have business logic beyond "validate + persist" |
| You DON'T need it if | Handler literally only validates, calls one repo method, returns result |

### CQRS

| | |
|---|---|
| Complexity cost | 4 |
| What it solves | Separate read and write models; optimize each independently |
| Simpler alternative | Single model with `ListXxx` method returning a DTO |
| You need it when | Read queries require joining 5+ tables and are 10x the volume of writes |

### Event Sourcing

| | |
|---|---|
| Complexity cost | 5 |
| What it solves | Complete audit trail; rebuild any past state; temporal queries |
| Simpler alternative | Append-only audit log table in PostgreSQL |
| You need it when | Need to reconstruct state at any point in time AND complex state transitions AND team has operational experience |

### Saga / Choreography

| | |
|---|---|
| Complexity cost | 4 |
| What it solves | Distributed transactions across multiple services without 2PC |
| Simpler alternative | Database transactions (if same DB) or a single service owning the workflow |
| You need it when | Multi-step workflow spanning 3+ services with partial failure compensation |

### Circuit Breaker

| | |
|---|---|
| Complexity cost | 2 |
| What it solves | Prevents cascade failure when a downstream dependency is unhealthy |
| Simpler alternative | Timeout + retry with backoff |
| You need it when | Dependency fails in a way that ties up goroutines (slow failures) |

```go
cb := gobreaker.NewCircuitBreaker(gobreaker.Settings{
    Name:        "payment-service",
    MaxRequests: 5,
    Interval:    10 * time.Second,
    Timeout:     30 * time.Second,
    ReadyToTrip: func(counts gobreaker.Counts) bool {
        failRatio := float64(counts.TotalFailures) / float64(counts.Requests)
        return counts.Requests >= 10 && failRatio >= 0.6
    },
})
```

### Feature Flags

| | |
|---|---|
| Complexity cost | 2 |
| What it solves | Deploy code without activating it; gradual rollouts; A/B testing |
| Simpler alternative | Environment variables (for simple on/off by deployment) |
| You need it when | Per-user or per-percentage rollouts, or to roll back without redeploying |

```go
func (s *FeatureService) IsEnabled(ctx context.Context, flag, userID string) bool {
    f, err := s.repo.GetFlag(ctx, flag)
    if err != nil || !f.Enabled { return false }
    if slices.Contains(f.UserIDs, userID) { return true }
    h := fnv.New32a()
    h.Write([]byte(userID + flag))
    return int(h.Sum32()%100) < f.RolloutPct
}
```

### API Gateway

| | |
|---|---|
| Complexity cost | 3 |
| What it solves | Single entry point for routing, auth, rate limiting, SSL termination |
| Simpler alternative | Nginx or Caddy reverse proxy |
| You need it when | 3+ services with different auth models, request transformation or fan-out needed |

### Service Mesh

| | |
|---|---|
| Complexity cost | 5 |
| What it solves | mTLS between services, observability at network layer, traffic management |
| Simpler alternative | Application-level TLS + OpenTelemetry + circuit breaker |
| You need it when | 10+ services, strict mTLS compliance, dedicated platform team |
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