gorstack

---
name: gorstack
description: Go + React monorepo architecture: Bun + Turborepo workspace with Go backend (fx, Huma, SQLC) and React web apps (Vite, TanStack, Radix/shadcn, Tailwind v4). Opinionated defaults for full-stack TypeScript+Go projects. Use when building a Go+React monorepo, adding full-stack features, or invokes /gorstack.
license: MIT
---

# gorstack — Go + React Monorepo Architecture

## What is gorstack

A full-stack architecture skill for projects that pair a **Go backend** with a **React web frontend** inside a single monorepo. It extends the `gostack` skill (backend-only) with web layer conventions, monorepo tooling, and integration patterns.

Use this skill when:
- Setting up a new Go + React monorepo
- Adding full-stack features that span backend and frontend
- Making architectural decisions about how the two stacks communicate
- Choosing or upgrading frontend libraries in a gorstack project

## Monorepo Layout

**Bun workspaces + Turborepo** manage the multi-package repository. The Go backend lives alongside React web apps under `apps/`, with shared packages under `packages/`.

See [MONOREPO.md](./MONOREPO.md) for directory structure, Turborepo pipeline config, pinned versions, and security notes.

## Backend

The Go backend follows the same conventions as the standalone `gostack` skill: **fx** for DI, **Huma** for typed REST, **SQLC** for DB access, **pgx** for Postgres, **go-redis** for caching.

See [BACKEND.md](./BACKEND.md) for the condensed reference. Install the `gostack` skill for full backend details.

## Web

The React web layer uses **React 19**, **Vite 8** (Rolldown-based), the **TanStack** ecosystem (Router, Query, Form, Table), **shadcn/ui** patterns (Radix + Tailwind + CVA), **Zustand** for client state, and **Zod** for validation.

See [WEB.md](./WEB.md) for the full library table, pinned versions, security notes, file structure, and component patterns.

## Integration

Backend and frontend communicate via typed REST endpoints. Huma auto-generates OpenAPI specs; optional `openapi-typescript` generates TS types from that spec. Prices are atomic strings end-to-end.

See [INTEGRATION.md](./INTEGRATION.md) for API contract, type generation, error envelope, TanStack Query patterns, env config, and CORS.

## Conventions

Cross-stack rules that apply to both Go and React code: string-typed prices, UUID and timestamp formats, error codes, linting, naming.

See [CONVENTIONS.md](./CONVENTIONS.md) for the full ruleset.

## ADR

Architectural decisions are recorded as HTML files under `docs/adr/`. Use the `to-adr` skill to create them.

See [ADR.md](./ADR.md) for the format and workflow.

## Workflow

1. **New monorepo**: Read MONOREPO.md first, then BACKEND.md and WEB.md for each stack.
2. **New feature**: Read INTEGRATION.md for how the stacks connect, then CONVENTIONS.md for shared rules.
3. **Library upgrade**: Check pinned versions in WEB.md and BACKEND.md. Follow the version pin policy below.
4. **Architecture decision**: Use the `to-adr` skill. See ADR.md.

## Related Skills

| Skill | When to use |
|---|---|
| `gostack` | Backend-only Go projects, or deep-dive on Go conventions |
| `go-tests` | Backend testing patterns (unit, integration, fixtures) |
| `swarm` | Parallel builds and CI orchestration |
| `to-adr` | Recording architectural decisions |

---
**Part of the gostack framework** — https://github.com/developerAKX/skills
**Install**: `npx skills add developerAKX/skills/gorstack`
**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.