golang-gin-architect — Pragmatic Software Architect

Think like a Staff Engineer who knows how to build the complex but chooses the simple. This skill guides architecture decisions for Go Gin APIs — system design, pattern selection, API evolution, and cross-cutting concerns. Orchestrates all other gin skills.

Core principle: Every recommendation has a complexity cost. The default answer is the simplest one that works. Complex patterns require justification.

Greenfield Quickstart

Starting a new Gin project from scratch? Follow this sequence:

1. golang-gin-architect — Define complexity budget, choose project structure (small/medium/large)
2. golang-gin-api — Scaffold project: cmd/api/main.go, handlers, AppError, middleware
3. golang-gin-database — Add PostgreSQL: repository pattern, connection pooling, migrations
4. golang-gin-auth — Add JWT auth + RBAC middleware (if needed)
5. golang-gin-testing — Write unit + integration tests with testcontainers
6. golang-gin-deploy — Containerize: multi-stage Dockerfile, docker-compose, CI/CD

Skip steps 4-6 until you actually need them. Steps 1-3 cover most MVPs.

When to Use

• Making architecture decisions (monolith vs microservices, sync vs async, SQL vs NoSQL)
• Evaluating if a pattern is overkill for the problem
• Designing a new system or major feature
• Planning API versioning and evolution strategy
• Setting up observability, caching, or security architecture
• Writing Architecture Decision Records (ADRs)
• Coordinating work across multiple gin skills
• Assessing and prioritizing tech debt

Complexity Budget — Ask This First

Before recommending any pattern, run this checklist:

| Question | If Yes → | If No → | |---|---|---| | Team < 5 devs? | Keep it simple — monolith, flat structure | Consider bounded modules | | < 10K RPM? | Standard Gin, PostgreSQL, no cache | Evaluate caching, read replicas | | Single deployment target? | Monolith with clean packages | Consider service boundaries | | Feature ships in < 1 week? | Direct implementation, no patterns | Plan architecture properly | | Will this code change again soon? | Keep flexible but don't over-abstract | Optimize for clarity | | Only 1 consumer of this API? | Internal contract, iterate fast | Version carefully |

The DEFAULT path is always the simple one. You need a reason to move right on the complexity scale.

Simple ──────────────────────────────── Complex
Direct SQL → Repository → CQRS → Event Sourcing
Monolith  → Modular Mono → Services → Microservices
REST      → REST+Events  → Full Async → Event Mesh

Architecture Decision Tree

"Should I use microservices?"

START: Do you have independent scaling needs?
  ├── No → MONOLITH. Stop here.
  └── Yes → Do you have 3+ teams that need to deploy independently?
      ├── No → MODULAR MONOLITH with clean package boundaries.
      └── Yes → Do you have the infra maturity (CI/CD, monitoring, tracing)?
          ├── No → MODULAR MONOLITH. Build infra maturity first.
          └── Yes → Extract the 1-2 services with clearest boundaries.
                    Keep everything else in the monolith.

Rule: Never start with microservices. Extract when pain is real and measured.

"Do I need CQRS / Event Sourcing?"

START: Are reads and writes fundamentally different in shape?
  ├── No → Standard repository pattern. Stop here.
  └── Yes → Is read volume 10x+ write volume?
      ├── No → Separate read/write models in the same service.
      └── Yes → Do you need a full audit trail of every state change?
          ├── No → CQRS with materialized views. Skip event sourcing.
          └── Yes → Event sourcing. But understand the operational cost.

"Sync or async?"

START: Does the caller need the result immediately?
  ├── Yes → Synchronous HTTP. Done.
  └── No → Is failure acceptable (retry later is OK)?
      ├── No → Synchronous with timeout + retry.
      └── Yes → Async with a message queue.
          └── Do you need exactly-once delivery?
              ├── No → Simple queue (Redis streams, SQS).
              └── Yes → Transactional outbox + idempotent consumers.

Project Structure by Scale

Small (1-3 devs, < 20 endpoints) — Flat Package Layout

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

Skills: golang-gin-api + golang-gin-database + golang-gin-testing. That's it.

Medium (3-8 devs, 20-100 endpoints) — Feature Modules

myapp/
├── cmd/api/main.go
├── internal/
│   ├── user/          # Feature module
│   │   ├── handler.go
│   │   ├── service.go
│   │   ├── repository.go
│   │   └── model.go
│   ├── order/         # Feature module
│   │   ├── handler.go
│   │   ├── service.go
│   │   ├── repository.go
│   │   └── model.go
│   └── shared/        # Cross-cutting
│       ├── auth/
│       └── errors/
├── pkg/middleware/
└── go.mod

Skills: All gin skills. Feature teams own modules end-to-end.

Large (8+ devs, 100+ endpoints) — Consider extraction only now

At this scale, evaluate whether specific modules should become separate services. See references/system-design.md for bounded context analysis.

C4 Context Diagram Example

Use this template to document your system's external boundaries:

C4Context
    title System Context — My Gin API

    Person(user, "End User", "Uses the web/mobile app")
    System(api, "Gin API", "Go backend — handles business logic and data")

    System_Ext(payment, "Payment Gateway", "Stripe / MercadoPago")
    System_Ext(email, "Email Service", "SendGrid / SES")
    SystemDb_Ext(postgres, "PostgreSQL", "Primary data store")

    Rel(user, api, "HTTPS/JSON")
    Rel(api, postgres, "sqlx / GORM")
    Rel(api, payment, "REST API")
    Rel(api, email, "SMTP / API")

For full C4 model guidance (Container, Component levels): see references/system-design.md.

API Design Quick Rules

| Rule | Do | Don't | |---|---|---| | Versioning | URL prefix: /api/v1/ | Header versioning (hard to test/debug) | | Nouns | GET /api/v1/users | GET /api/v1/getUsers | | Plurals | /users, /orders | /user, /order | | Nesting | Max 2 levels: /users/:id/orders | /users/:id/orders/:oid/items/:iid | | Pagination | Cursor-based for large sets, offset for small | Unbounded GET /items | | Filtering | Query params: ?status=active&role=admin | Request body for GET | | Bulk ops | POST /users/bulk with array body | Individual calls in a loop | | Errors | {"error": "message", "code": "USER_NOT_FOUND"} | Plain strings or HTML |

Backwards compatibility rule: Never remove a field, never change a field type, never change semantics. Add new fields, add new endpoints, deprecate old ones.

For complete API design patterns: see references/api-design.md.

Skill Orchestration — When to Call What

| Task | Primary Skill | Supporting Skills | |---|---|---| | New CRUD endpoint | golang-gin-api | golang-gin-database, golang-gin-testing | | Add authentication | golang-gin-auth | golang-gin-api (route setup) | | Schema design / migration | golang-gin-psql-dba | golang-gin-database (tooling) | | Repository / ORM setup | golang-gin-database | golang-gin-psql-dba (schema decisions) | | Performance issue | golang-gin-psql-dba | golang-gin-testing (benchmarks) | | Containerize / deploy | golang-gin-deploy | golang-gin-testing (CI integration) | | Write tests | golang-gin-testing | (reads all other skills) | | Architecture decision | golang-gin-architect | Routes to others as needed |

Orchestration rules:

1. Always start with golang-gin-architect for architecture decisions — it routes to specific skills
2. golang-gin-api + golang-gin-database are the daily workhorses — most features only need these
3. golang-gin-psql-dba is for database decisions (schema, indexes, perf); golang-gin-database is for code (GORM/sqlx)
4. golang-gin-auth is standalone — activate only when adding/modifying auth flows
5. golang-gin-deploy is end-of-cycle — containerize after features work locally
6. golang-gin-testing is continuous — activate after every implementation

For detailed orchestration flows: see references/skill-orchestration.md.

Cross-Cutting Concerns Quick Reference

Observability Stack

// Structured logging — log/slog (stdlib)
logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo}))
logger.Info("request handled", "method", c.Request.Method, "path", c.FullPath(), "status", c.Writer.Status())

// Metrics — prometheus/client_golang
httpRequestsTotal := prometheus.NewCounterVec(prometheus.CounterOpts{
    Name: "http_requests_total",
    Help: "Total HTTP requests",
}, []string{"method", "path", "status"})

// Tracing — OpenTelemetry
// Use go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin
r.Use(otelgin.Middleware("myapp"))

Caching Decision

START: Is data read more than written?
  ├── No → No cache needed.
  └── Yes → Is data the same for all users?
      ├── Yes → HTTP Cache-Control headers. Cheapest option.
      └── No → Is data < 100MB total?
          ├── Yes → In-memory cache (sync.Map or github.com/dgraph-io/ristretto).
          └── No → Redis. But measure first — PostgreSQL with proper indexes
                    handles more than you think.

Security Architecture Checklist

• [ ] Input validation on all endpoints (ShouldBind + sanitize) → golang-gin-api
• [ ] JWT auth with short-lived tokens + refresh → golang-gin-auth
• [ ] RBAC middleware on protected routes → golang-gin-auth
• [ ] Rate limiting per IP and per user → golang-gin-api (rate-limiting reference)
• [ ] CORS configured for known origins only → golang-gin-api (middleware reference)
• [ ] SQL injection prevention (parameterized queries) → golang-gin-database
• [ ] Row-level security for multi-tenant → golang-gin-psql-dba
• [ ] Secrets in environment variables, never in code → golang-gin-deploy
• [ ] HTTPS termination at load balancer → golang-gin-deploy
• [ ] Dependency scanning in CI → golang-gin-deploy

For complete cross-cutting patterns: see references/cross-cutting-concerns.md.

ADR Template (Lightweight)

# ADR-NNN: Title

**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**Date:** YYYY-MM-DD
**Context:** What's the problem? Why are we deciding now?
**Decision:** What did we choose?
**Alternatives considered:**
- Option A: [why rejected]
- Option B: [why rejected]
**Consequences:** What changes? What's the trade-off?

Store ADRs in docs/adr/ in your project. Number sequentially. Never delete — mark as superseded.

For templates for common decisions (database choice, auth strategy, caching layer): see references/adr-templates.md.

Tech Debt Quick Assessment

| Category | Symptoms | Priority | |---|---|---| | Critical | Security vulnerabilities, data loss risk, broken builds | Fix NOW | | High | No tests for critical paths, hardcoded secrets, missing error handling | Next sprint | | Medium | Duplicated code, inconsistent patterns, missing docs | Plan it | | Low | Style inconsistencies, unused imports, verbose code | Boy scout rule |

Rule of thumb: If it slows down every PR, it's at least Medium. If it could wake you up at 3 AM, it's Critical.

For tech debt measurement framework and communication templates: see references/tech-debt-management.md.

Reference Files

Load these for deeper detail:

• references/complexity-assessment.md — Full decision trees, complexity budget framework, right-size thinking calibrated to team/product stage, pattern selection matrix, "you don't need this yet" gates
• references/system-design.md — C4 model, bounded context analysis, domain modeling, dependency graphs, module boundary design, Go package layout at scale
• references/data-patterns.md — CQRS, event sourcing, saga orchestration, transactional outbox, read replicas — high-complexity patterns, each with prerequisite gates and Go examples
• references/resilience-patterns.md — Circuit breaker, bulkhead, retry with exponential backoff, rate limiting at architecture level — low-cost patterns for external dependency resilience
• references/api-design.md — Versioning strategies, pagination contracts (cursor + offset), filtering, sorting, bulk operations, deprecation, backwards compatibility rules
• references/cross-cutting-concerns.md — Observability (slog, Prometheus, OpenTelemetry), caching (in-memory, Redis, HTTP), security architecture, feature flags, configuration management
• references/adr-templates.md — ADR format, templates for database choice, auth strategy, caching layer, service extraction, with worked examples
• references/skill-orchestration.md — Detailed decision matrix for when to activate each gingo skill, common workflow sequences, skill composition patterns
• references/tech-debt-management.md — Debt quadrant (reckless/prudent × deliberate/inadvertent), measurement framework, prioritization matrix, stakeholder communication templates
• references/clean-architecture.md — Uncle Bob's layers mapped to Go packages, dependency rule, ports & adapters (hexagonal), manual DI wiring, complete feature module example, common mistakes
• references/redis-caching-strategy.md — Smart caching: decision matrix by data type, cache stampede prevention (singleflight), warming, pub/sub invalidation, session storage, distributed locking
• references/messaging-patterns.md — Async messaging with RabbitMQ: producer/consumer, work queues, pub/sub exchanges, dead letter queues, idempotent consumers
• references/object-storage.md — S3-compatible storage (AWS, MinIO, R2): upload/download, presigned URLs, multipart upload, MinIO for local dev
• references/error-flow-architecture.md — How errors flow domain→service→handler, wrapping conventions, sentinel vs custom types, errors.Is/As, complete error chain example
• references/golden-main-template.md — Production-ready cmd/api/main.go templates (small + medium), startup sequence, graceful shutdown, dependency wiring
• references/grpc-interop.md — Running Gin HTTP + gRPC in same project, shared service layer, cmux multiplexer, buf toolchain, gRPC-Gateway
• references/data-ownership.md — Database-per-service, API composition, data sync strategies, shared reference data, migration path from monolith

Cross-Skill References

• For REST endpoint implementation patterns: see the golang-gin-api skill
• For JWT auth and RBAC: see the golang-gin-auth skill
• For PostgreSQL schema and query decisions: see the golang-gin-psql-dba skill
• For GORM/sqlx repository code: see the golang-gin-database skill
• For testing strategies: see the golang-gin-testing skill
• For Docker, K8s, and CI/CD: see the golang-gin-deploy skill