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).4---56<objective>7Structure Go 1.22+ backend services: the standard cmd/internal layout, choosing an8HTTP router (net/http ServeMux, chi, echo/gin/fiber), constructor-based dependency9injection, and type-safe database access with sqlc + pgx. Covers laying out a new10Go project, choosing a router or DB layer, wiring dependencies, and reviewing an11existing service's structure. Does not cover goroutines/channels concurrency12patterns (see go-concurrency) or general language idioms (see go-core-idioms).13</objective>1415# Go Architecture1617Opinionated, 2026-current guidance for structuring Go backend services. Favors the18standard library and small, composable libraries over heavy frameworks.1920**Use when:**21- Laying out a new Go module or service (directory structure, `cmd/`, `internal/`)22- Choosing an HTTP router (stdlib `net/http` ServeMux, chi, echo/gin/fiber)23- Choosing a database layer (sqlc + pgx, GORM) or wiring queries24- Wiring dependencies (constructors, DI without a framework)25- Reviewing an existing Go service for structural / architectural issues2627**Do NOT use for:**28- Writing tests, benchmarks, fuzzing, coverage — use `go-testing-quality`29- SOLID line-limit / interface-placement enforcement — use `fuse-solid:solid-go`30- Non-Go backends (Laravel, Next.js, Rust) — use the matching expert31- Frontend / UI work — use `fuse-design` or a framework expert3233---3435## Decision Map3637| Question | Load |38|----------|------|39| Where do files/packages go? | [project-layout.md](references/project-layout.md) |40| Which HTTP router? How do I route? | [http-routing.md](references/http-routing.md) |41| How do I talk to the database? | [database-access.md](references/database-access.md) |42| How do I wire dependencies? | [dependency-injection.md](references/dependency-injection.md) |43| I need a full working example | [templates/rest-service.md](references/templates/rest-service.md) |4445---4647## Core Principles (2026)48491. **Standard library first.** Since Go 1.22 the `net/http.ServeMux` supports50 method matching and path wildcards (`GET /posts/{id}`, `req.PathValue("id")`).51 Most services no longer need a routing framework.52 Source: https://go.dev/blog/routing-enhancements532. **`internal/` is the default home for service logic.** A server binary is54 self-contained; keep packages under `internal/` and binaries under `cmd/`.55 There is no official `pkg/` requirement — do not cargo-cult it.56 Source: https://go.dev/doc/modules/layout573. **Constructor injection, no DI framework by default.** Pass dependencies as58 interface parameters to `New…` constructors; wire them in `main`.594. **Type-safe SQL is the 2026 default.** `sqlc` generates idiomatic Go from raw60 SQL; run it on top of the `pgx` driver for PostgreSQL. GORM still works but is61 in relative decline for new services — see database-access.md for the nuance.62 Sources: https://docs.sqlc.dev + https://pkg.go.dev/github.com/jackc/pgx/v56364---6566## Workflow67681. **Explore** the existing tree first (do not assume layout).692. **Load** the relevant reference from the Decision Map above.703. **Cross-check** the version-sensitive claims (router, sqlc/pgx) against the71 source URLs before writing code — APIs move.724. **Scaffold** from [templates/rest-service.md](references/templates/rest-service.md)73 when starting fresh.745. **Keep files small** and interfaces separated (defer to `fuse-solid:solid-go`).756. **Validate** with `go-testing-quality` + sniper after any code change.7677---7879## Boundaries (cross-referenced, not copied)8081The community skill set at `github.com/samber/cc-skills-golang` covers overlapping82Go territory. This skill deliberately scopes to **architecture / structure /83routing / DB wiring** and hands testing off to `go-testing-quality`. When in84doubt about which skill owns a topic, prefer the more specific one.
fusengine