Go Architecture
Opinionated, 2026-current guidance for structuring Go backend services. Favors the
standard library and small, composable libraries over heavy frameworks.
Use when:
- Laying out a new Go module or service (directory structure,
cmd/, internal/)
- Choosing an HTTP router (stdlib
net/http ServeMux, chi, echo/gin/fiber)
- Choosing a database layer (sqlc + pgx, GORM) or wiring queries
- Wiring dependencies (constructors, DI without a framework)
- Reviewing an existing Go service for structural / architectural issues
Do NOT use for:
- Writing tests, benchmarks, fuzzing, coverage — use
go-testing-quality
- SOLID line-limit / interface-placement enforcement — use
fuse-solid:solid-go
- Non-Go backends (Laravel, Next.js, Rust) — use the matching expert
- Frontend / UI work — use
fuse-design or a framework expert
Decision Map
| Question |
Load |
| Where do files/packages go? |
project-layout.md |
| Which HTTP router? How do I route? |
http-routing.md |
| How do I talk to the database? |
database-access.md |
| How do I wire dependencies? |
dependency-injection.md |
| I need a full working example |
templates/rest-service.md |
Core Principles (2026)
- Standard library first. Since Go 1.22 the
net/http.ServeMux supports
method matching and path wildcards (GET /posts/{id}, req.PathValue("id")).
Most services no longer need a routing framework.
Source: https://go.dev/blog/routing-enhancements
internal/ is the default home for service logic. A server binary is
self-contained; keep packages under internal/ and binaries under cmd/.
There is no official pkg/ requirement — do not cargo-cult it.
Source: https://go.dev/doc/modules/layout
- Constructor injection, no DI framework by default. Pass dependencies as
interface parameters to
New… constructors; wire them in main.
- Type-safe SQL is the 2026 default.
sqlc generates idiomatic Go from raw
SQL; run it on top of the pgx driver for PostgreSQL. GORM still works but is
in relative decline for new services — see database-access.md for the nuance.
Sources: https://docs.sqlc.dev + https://pkg.go.dev/github.com/jackc/pgx/v5
Workflow
- Explore the existing tree first (do not assume layout).
- Load the relevant reference from the Decision Map above.
- Cross-check the version-sensitive claims (router, sqlc/pgx) against the
source URLs before writing code — APIs move.
- Scaffold from templates/rest-service.md
when starting fresh.
- Keep files small and interfaces separated (defer to
fuse-solid:solid-go).
- Validate with
go-testing-quality + sniper after any code change.
Boundaries (cross-referenced, not copied)
The community skill set at github.com/samber/cc-skills-golang covers overlapping
Go territory. This skill deliberately scopes to architecture / structure /
routing / DB wiring and hands testing off to go-testing-quality. When in
doubt about which skill owns a topic, prefer the more specific one.
1---2name: go-architecture3description: Use when laying out a new Go service, choosing an HTTP router or DB layer, or wiring dependencies. Not for concurrency (go-concurrency) or language idioms (go-core-idioms).4metadata:5 source: https://skillmd.com/skills/fusengine/go-architecture6---78<objective>9Structure Go 1.22+ backend services: the standard cmd/internal layout, choosing an10HTTP router (net/http ServeMux, chi, echo/gin/fiber), constructor-based dependency11injection, and type-safe database access with sqlc + pgx. Covers laying out a new12Go project, choosing a router or DB layer, wiring dependencies, and reviewing an13existing service's structure. Does not cover goroutines/channels concurrency14patterns (see go-concurrency) or general language idioms (see go-core-idioms).15</objective>1617# Go Architecture1819Opinionated, 2026-current guidance for structuring Go backend services. Favors the20standard library and small, composable libraries over heavy frameworks.2122**Use when:**23- Laying out a new Go module or service (directory structure, `cmd/`, `internal/`)24- Choosing an HTTP router (stdlib `net/http` ServeMux, chi, echo/gin/fiber)25- Choosing a database layer (sqlc + pgx, GORM) or wiring queries26- Wiring dependencies (constructors, DI without a framework)27- Reviewing an existing Go service for structural / architectural issues2829**Do NOT use for:**30- Writing tests, benchmarks, fuzzing, coverage — use `go-testing-quality`31- SOLID line-limit / interface-placement enforcement — use `fuse-solid:solid-go`32- Non-Go backends (Laravel, Next.js, Rust) — use the matching expert33- Frontend / UI work — use `fuse-design` or a framework expert3435---3637## Decision Map3839| Question | Load |40|----------|------|41| Where do files/packages go? | [project-layout.md](references/project-layout.md) |42| Which HTTP router? How do I route? | [http-routing.md](references/http-routing.md) |43| How do I talk to the database? | [database-access.md](references/database-access.md) |44| How do I wire dependencies? | [dependency-injection.md](references/dependency-injection.md) |45| I need a full working example | [templates/rest-service.md](references/templates/rest-service.md) |4647---4849## Core Principles (2026)50511. **Standard library first.** Since Go 1.22 the `net/http.ServeMux` supports52 method matching and path wildcards (`GET /posts/{id}`, `req.PathValue("id")`).53 Most services no longer need a routing framework.54 Source: https://go.dev/blog/routing-enhancements552. **`internal/` is the default home for service logic.** A server binary is56 self-contained; keep packages under `internal/` and binaries under `cmd/`.57 There is no official `pkg/` requirement — do not cargo-cult it.58 Source: https://go.dev/doc/modules/layout593. **Constructor injection, no DI framework by default.** Pass dependencies as60 interface parameters to `New…` constructors; wire them in `main`.614. **Type-safe SQL is the 2026 default.** `sqlc` generates idiomatic Go from raw62 SQL; run it on top of the `pgx` driver for PostgreSQL. GORM still works but is63 in relative decline for new services — see database-access.md for the nuance.64 Sources: https://docs.sqlc.dev + https://pkg.go.dev/github.com/jackc/pgx/v56566---6768## Workflow69701. **Explore** the existing tree first (do not assume layout).712. **Load** the relevant reference from the Decision Map above.723. **Cross-check** the version-sensitive claims (router, sqlc/pgx) against the73 source URLs before writing code — APIs move.744. **Scaffold** from [templates/rest-service.md](references/templates/rest-service.md)75 when starting fresh.765. **Keep files small** and interfaces separated (defer to `fuse-solid:solid-go`).776. **Validate** with `go-testing-quality` + sniper after any code change.7879---8081## Boundaries (cross-referenced, not copied)8283The community skill set at `github.com/samber/cc-skills-golang` covers overlapping84Go territory. This skill deliberately scopes to **architecture / structure /85routing / DB wiring** and hands testing off to `go-testing-quality`. When in86doubt about which skill owns a topic, prefer the more specific one.