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/golden-main-medium-startup.md

View on GitHub
# Golden main.go — Medium Project: Startup Sequence and Patterns

RegisterRoutes pattern, startup order, and graceful shutdown for medium projects.

Companion to `golden-main-medium-project.md` (complete main.go).

---

## RegisterRoutes Pattern

Each handler package owns its route registration:

```go
// internal/features/user/userhandler/routes.go
func RegisterRoutes(rg *gin.RouterGroup, h *Handler) {
	users := rg.Group("/users")
	users.GET("/:id", h.GetByID)
	users.POST("", h.Create)
	users.PUT("/:id", h.Update)
	users.DELETE("/:id", h.Delete)
}

// internal/features/order/orderhandler/routes.go
func RegisterRoutes(rg *gin.RouterGroup, h *Handler) {
	orders := rg.Group("/orders")
	orders.GET("/:id", h.GetByID)
	orders.POST("", h.Create)
	admin := orders.Group("", middleware.RequireRole("admin"))
	admin.DELETE("/:id", h.Delete)
}
```

---

## Startup Sequence (Strict Order)

```
1. Logger       → needed by every subsequent step
2. Config       → all components read from it; fail fast on missing required vars
3. Database     → repos depend on *sqlx.DB; configure pool immediately after connect
4. Repositories → services depend on repo interfaces
5. Services     → handlers depend on service interfaces
6. Handlers     → routes depend on handler methods
7. Router       → gin.New(); global middleware: Recovery → RequestID → Logger → CORS
8. Routes       → health (no auth), then authenticated groups
9. http.Server  → explicit timeouts; start in goroutine
10. Signal wait → block on SIGINT/SIGTERM; graceful shutdown with context timeout
```

**Why `gin.New()` not `gin.Default()`:** `gin.Default()` adds a non-structured logger conflicting with `slog`, and silently adds `Recovery()`. Use `gin.New()` so middleware stack is explicit and auditable.

---

## Graceful Shutdown

```
Signal received
      │
      ▼
srv.Shutdown(ctx)   ← stops new connections, drains in-flight
      │
      ▼
db.Close()          ← via defer, runs after Shutdown returns
      │
      ▼
logger.Info("stopped")
```

```go
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
if err := srv.Shutdown(ctx); err != nil {
	logger.Error("shutdown timeout, forcing close", "error", err)
	_ = srv.Close()
}
```

Rules: `ShutdownTimeout` > longest expected request. Never call `srv.Close()` before `srv.Shutdown()`. Handlers must propagate `c.Request.Context()` so in-flight DB queries terminate cleanly.

---

## Cross-Skill References

| Topic | Skill |
|---|---|
| Handler patterns, `ShouldBind*` | `golang-gin-api` |
| Repository patterns, sqlx, migrations | `golang-gin-database` |
| JWT middleware, auth groups | `golang-gin-auth` |
| Docker, env config, health checks | `golang-gin-deploy` |
| Clean architecture folder structure | `clean-architecture-feature-module.md` |
| Small project template | `golden-main-small-project.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: 323kUpdated 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