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/system-design-project-structure.md

View on GitHub
# System Design — Go Package Layout at Scale

Package layout patterns for Go Gin APIs at different team/endpoint scales.

Companion to `system-design-dependency-graphs.md` (no-cycles rule, dependency inversion).

---

## Small: 1-3 devs, < 20 endpoints — Flat Layout

```
myapp/
├── cmd/api/main.go
├── internal/
│   ├── handler/          # All HTTP handlers
│   ├── service/          # All business logic
│   ├── repository/       # All data access
│   └── domain/           # Entities, interfaces, errors
├── pkg/
│   └── middleware/
└── go.mod
```

One package per layer. Works until the team grows or domains conflict.

---

## Medium: 3-8 devs, 20-100 endpoints — Feature Modules

```
myapp/
├── cmd/api/main.go
├── internal/
│   ├── user/
│   │   ├── handler.go
│   │   ├── service.go
│   │   ├── repository.go
│   │   ├── model.go
│   │   └── ports.go        # interfaces this module needs from others
│   ├── order/
│   │   ├── handler.go
│   │   ├── service.go
│   │   ├── repository.go
│   │   ├── model.go
│   │   └── ports.go
│   └── platform/           # shared infrastructure — not a business domain
│       ├── database/
│       ├── auth/
│       └── middleware/
├── pkg/
│   └── httputil/
└── go.mod
```

Each feature module owns its full vertical slice. `ports.go` defines external interface contracts.

**The `platform/` package** is infrastructure — not a domain. Business modules import from `platform/`, never the reverse.

---

## Large: 8+ devs, 100+ endpoints — Evaluate Extraction

Before extracting to microservices, all 3 must be true for the same module:

1. Independent scaling requirements (measured, not hypothetical)
2. Need to deploy independently (different release cadence, different team)
3. Clear, stable interface that won't change frequently

```
myapp/                         extracted/
├── cmd/api/main.go            ├── cmd/catalog-api/main.go
├── internal/                  ├── internal/
│   ├── user/                  │   └── catalog/
│   ├── order/                 └── go.mod
│   └── platform/
└── go.mod
```

**The extracted service talks to the monolith via HTTP or gRPC, not shared DB tables.**

---

## Shared Infrastructure in `platform/`

```go
// internal/platform/database/db.go
package database

type Config struct {
    DSN             string
    MaxOpenConns    int
    MaxIdleConns    int
    ConnMaxLifetime time.Duration
}

func New(cfg Config, logger *slog.Logger) (*sqlx.DB, error) {
    db, err := sqlx.Connect("postgres", cfg.DSN)
    if err != nil {
        return nil, fmt.Errorf("database.New: %w", err)
    }
    db.SetMaxOpenConns(cfg.MaxOpenConns)
    db.SetMaxIdleConns(cfg.MaxIdleConns)
    db.SetConnMaxLifetime(cfg.ConnMaxLifetime)
    logger.Info("database connected")
    return db, nil
}
```

Each feature module receives `*sqlx.DB` via constructor injection from `main.go`. They never construct their own DB connections.

---

## Module Boundary Design

**Default: one module for everything.** Split only when:

| Reason to split | Example |
|---|---|
| Independently versioned library | `github.com/myorg/myapp-sdk` |
| Separate deployment unit | A CLI tool distributed separately |
| Third-party shared package | `github.com/myorg/shared-middleware` |

**Rule:** Put everything in `internal/` by default. Only move to `pkg/` if you have a genuine external consumer.

**Anti-pattern: the "types" package**

```
// Do NOT do this
internal/
└── types/
    ├── user.go      ← everything imports this, nobody owns it
    ├── order.go
    └── product.go
```

Distribute types to their owning modules instead.

---

## Cross-Skill References

- For dependency graphs: see **[system-design-dependency-graphs.md](system-design-dependency-graphs.md)**
- For bounded context analysis: see **[system-design-bounded-contexts.md](system-design-bounded-contexts.md)**
- For C4 diagrams: see **[system-design-c4-model.md](system-design-c4-model.md)**
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