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-c4-model.md

View on GitHub
# System Design — C4 Model for Go APIs

When and how to use C4 diagrams for Go Gin API architecture documentation.

> **Default stance:** A CRUD API with a single team does NOT need C4 diagrams. Use when complexity is real and measured, not anticipated.

---

## When to Use Each Level

| Level | Use when |
|---|---|
| **Context** | Always — one diagram, 5 min to draw, answers "what does this system do and who talks to it?" |
| **Container** | You have multiple deployable units (API + worker + frontend + DB) |
| **Component** | A single container has enough internal complexity that new devs get lost |
| **Code** | Almost never. Use Go doc comments + package structure instead. |

If you have a single Gin API talking to one PostgreSQL database: draw Context, stop there.

---

## Level 1 — Context Diagram

Shows the system boundary and its actors/external systems. One box per external thing.

```mermaid
C4Context
    title System Context — Order API

    Person(customer, "Customer", "Browses catalog, places orders")
    Person(admin, "Admin", "Manages inventory, views reports")

    System(orderApi, "Order API", "Go/Gin REST API handling orders, catalog, payments")

    System_Ext(paymentGw, "Payment Gateway", "Stripe — processes card payments")
    System_Ext(emailSvc, "Email Service", "SendGrid — transactional email")
    System_Ext(shippingSvc, "Shipping API", "FedEx — label generation, tracking")

    Rel(customer, orderApi, "Uses", "HTTPS/JSON")
    Rel(admin, orderApi, "Uses", "HTTPS/JSON")
    Rel(orderApi, paymentGw, "Charges cards", "HTTPS")
    Rel(orderApi, emailSvc, "Sends confirmations", "HTTPS")
    Rel(orderApi, shippingSvc, "Creates shipments", "HTTPS")
```

**Rule:** If you can't fit this on one page, you have too many external dependencies — that's the real problem to solve.

---

## Level 2 — Container Diagram

Shows deployable units. Use when you have more than one process running.

```mermaid
C4Container
    title Container Diagram — Order Platform

    Person(customer, "Customer")

    Container(webApp, "Web App", "React SPA", "Browser-side UI")
    Container(apiGateway, "API Gateway", "nginx", "TLS termination, routing")
    Container(orderApi, "Order API", "Go/Gin", "Core business logic")
    Container(workerService, "Background Worker", "Go", "Async jobs: emails, shipping")
    ContainerDb(postgres, "PostgreSQL", "Database", "Orders, users, catalog")
    ContainerDb(redis, "Redis", "Cache + Queue", "Sessions, job queue")

    Rel(customer, webApp, "Uses", "HTTPS")
    Rel(webApp, apiGateway, "Calls", "HTTPS/JSON")
    Rel(apiGateway, orderApi, "Routes to", "HTTP")
    Rel(orderApi, postgres, "Reads/writes", "TCP/5432")
    Rel(orderApi, redis, "Caches, enqueues", "TCP/6379")
    Rel(workerService, redis, "Dequeues from", "TCP/6379")
    Rel(workerService, postgres, "Updates state", "TCP/5432")
```

---

## Level 3 — Component Diagram

Shows internal structure of one container. Use only when a container has 5+ distinct responsibilities and onboarding new devs takes more than a day.

```mermaid
C4Component
    title Component Diagram — Order API (internal)

    Component(userCmp, "User Module", "internal/user", "Registration, auth, profile")
    Component(orderCmp, "Order Module", "internal/order", "Cart, checkout, order lifecycle")
    Component(catalogCmp, "Catalog Module", "internal/catalog", "Products, categories, search")
    Component(notifCmp, "Notification Module", "internal/notification", "Email, push triggers")
    Component(platform, "Platform", "internal/platform", "DB pool, auth middleware, logger")

    Rel(orderCmp, userCmp, "Looks up user", "interface UserLookup")
    Rel(orderCmp, catalogCmp, "Validates items", "interface ProductLookup")
    Rel(orderCmp, notifCmp, "Emits events", "interface EventPublisher")
    Rel(userCmp, platform, "Uses DB, auth")
    Rel(orderCmp, platform, "Uses DB")
    Rel(catalogCmp, platform, "Uses DB")
```

**Go-specific mapping:** Each C4 component maps to a Go package under `internal/`. The arrows between components must be satisfied by Go interfaces — this prevents import cycles and enforces boundaries.

## Level 4 — Code Level

Skip it. Go package documentation, `go doc`, and readable package structure do this better with zero maintenance cost.

---

## Cross-Skill References

- For bounded context analysis: see **[system-design-bounded-contexts.md](system-design-bounded-contexts.md)**
- For project structure by scale: see **[system-design-project-structure.md](system-design-project-structure.md)**
- For complexity budget: see **[complexity-assessment.md](complexity-assessment.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