gostack

---
name: gostack
description: Go backend service architecture: fx DI, Huma+Fiber HTTP, SQLC database access, pgx pools, atomic-string money values, feature-based directory layout. Opinionated defaults for building production Go services. Use when building Go backend services, adding features to a gostack-style codebase, or invokes /gostack.
license: MIT
---

# gostack

An opinionated-defaults architecture for Go backend services.

gostack is not a framework you import -- it is a set of conventions, library
choices, and directory patterns that work well together. You can adopt all of it
or just the parts you need. The goal is to eliminate bikeshedding on project
structure so you can focus on domain logic.

## Stack at a glance

> Full details: [STACK.md](./STACK.md)

| Layer | Choice |
|---|---|
| DI | `go.uber.org/fx` -- runtime injection, lifecycle hooks |
| HTTP | Huma on Fiber -- typed handlers, automatic OpenAPI |
| Database | pgx pool + SQLC codegen -- SQL-first, no ORM |
| Cache | go-redis -- caching, Pub/Sub, Streams |
| Logging | `log/slog` (stdlib) -- structured, zero deps |
| Migrations | golang-migrate -- forward/backward SQL |

## Directory layout

> Full details: [LAYOUT.md](./LAYOUT.md)

Feature-based. One feature = one directory under `internal/feature/`. Each
feature contains its service, handlers, routes, types, and SQLC-generated
repository -- everything needed to understand the feature in one place.

A feature can live in one service or be split across multiple services without
changing the feature code. The `internal/wire/` layer controls composition.

## Coding conventions

> Full details: [CONVENTIONS.md](./CONVENTIONS.md)

- **SQLC-only DB access**: write SQL, generate Go. No raw queries in application code.
- **Descriptive identifiers**: every name tells you what it represents.
- **Thin handlers**: extract context, call service, wrap result.
- **Service holds logic**: the service struct is where domain behavior lives.
- **File per concern**: split by domain concern when files grow, not by abstraction layer.

## Money handling

> Full details: [MONEY.md](./MONEY.md)

All monetary and price values are **atomic strings** end-to-end: `NUMERIC(38,18)`
in Postgres, `string` in Go, quoted `"123.456"` in JSON. Arithmetic uses
`math/big.Rat` at calculation boundaries only. Never `float64` for money.

## Architecture Decision Records

> Full details: [ADR.md](./ADR.md)

ADRs are HTML-only, stored in `docs/adr/`, and generated with the `to-adr` skill.
They document architectural decisions with context, alternatives, and consequences.

## Related skills

- **`go-tests`** -- testing conventions, table-driven tests, integration test patterns
- **`swarm`** -- coordinating large multi-file builds across agents
- **`to-adr`** -- generating Architecture Decision Records

## When to use this skill

- Starting a new Go backend service
- Adding a feature to an existing gostack-style codebase
- Reviewing code for convention compliance
- Deciding how to structure a multi-service monorepo
- Choosing between library alternatives for a Go service

## When NOT to use this skill

- Frontend code (use `frontend-design`)
- Testing specifics (use `go-tests`)
- Non-Go backends
- Infrastructure/deployment (Terraform, K8s, etc.)

---
**Part of the gostack framework** -- https://github.com/developerAKX/skills
**Install**: `npx skills add developerAKX/skills/gostack`
**License**: MIT
**Version pin policy**: All version numbers are intentionally pinned to specific
stable releases verified on 2026-05-26. Do NOT auto-bump in CI. Re-verify and
update manually only when there is a security advisory or a needed feature.