# Resources — v2 Architecture (Hexagonal + CQRS + sqlc)

High-trust only. External sources are the canon (the people who named the patterns) plus the
Go-specific reference implementation. In-repo sources are ground truth for how *this* team applies
them. Never trust parametric memory over these.

## Primary sources (external — verified)

### Hexagonal / Ports & Adapters
- **Alistair Cockburn — "Hexagonal Architecture" (the original, 2005)** —
  <https://alistair.cockburn.us/hexagonal-architecture/>
  The man who named it. "Allow an application to equally be driven by users, programs, automated
  test or batch scripts, and to be developed and tested in isolation from its eventual run-time
  devices and databases." THE primary source for Part 1.
- **Wikipedia — Hexagonal architecture (software)** —
  <https://en.wikipedia.org/wiki/Hexagonal_architecture_(software)>
  Good neutral summary of ports, adapters, driving vs driven sides.

### CQRS
- **Martin Fowler — "CQRS" (bliki, 2011)** — <https://martinfowler.com/bliki/CQRS.html>
  "Use a different model to update information than the model you use to read information." Crucially
  honest: *"for most systems CQRS adds risky complexity"* and *"should only be used on specific
  portions of a system."* THE primary source for Part 2 — and the caveat matters.
- **Martin Fowler — "CommandQuerySeparation"** —
  <https://martinfowler.com/bliki/CommandQuerySeparation.html>
  The older, method-level idea CQRS is named after (not the same thing — CQS ≠ CQRS).

### sqlc
- **sqlc official documentation** — <https://docs.sqlc.dev/>
  "Generates fully type-safe idiomatic Go code from SQL." Query annotations, config, `emit_*`
  options. THE primary source for Part 3.
- **sqlc on GitHub** — <https://github.com/sqlc-dev/sqlc>

### The Go-specific bridge (how these combine idiomatically in Go)
- **Three Dots Labs — "Combining DDD, CQRS, and Clean Architecture in Go"** —
  <https://threedots.tech/post/ddd-cqrs-clean-architecture-combined/>
  The single best article on exactly this stack in Go.
- **Three Dots Labs — "How to use basic CQRS in Go"** —
  <https://threedots.tech/post/basic-cqrs-in-go/>
- **Three Dots Labs — "Clean Architecture in Go"** —
  <https://threedots.tech/post/introducing-clean-architecture/>
- **Wild Workouts (reference implementation)** —
  <https://github.com/ThreeDotsLabs/wild-workouts-go-ddd-example>
  A complete Go project applying DDD + Clean/Hexagonal + CQRS. The closest public analogue to this
  repo's v2 shape.

## In-repo ground truth (the real spec)

These are more prescriptive than the human-facing docs — treat them as the authority for *this
repo's* conventions.

- `internal/eureka/CLAUDE.md` — the richest v2 doc: the module template, the **Read/Write data-access
  rule table** (read via sqlc directly; write via repo interface only), the sqlc query packages,
  manual service wiring.
- `internal/eureka/v2/readme.md` — "LMS 2.0"; the transport/usecase/domain/repository layering; the
  loose-coupling rule ("Interface should not have any related types of dependencies like Postgres").
- `internal/spike/CLAUDE.md` — "CQRS + hexagonal (ports & adapters)"; the `modules/email` layout;
  the layering rules; the send-email data flow.
- `internal/notification/CLAUDE.md` — two-generation service; the module-quality table
  (`system_notification` ✅ canonical; `announcement` leaks `pgtype`; `tagmgmt` ❌ legacy).
- `.claude/rules/eureka-v2-conventions.md` — storage.go purity, **Querier injection**,
  constructor-not-literal, error translation across layers, mock strategy by layer.
- `.claude/rules/sqlc-queries.md` — sqlc path layout, dynamic-filter annotations, query annotations.
- `.claude/rules/go-code-style.md`, `.claude/rules/security.md` — naming, RBAC, `resource_path`, soft-delete.

## Reference (in this workspace)
- [reference/repo-v2-map.md](reference/repo-v2-map.md) — the ground-truth map: where each pattern
  lives, with `file:line`.
- [reference/GLOSSARY.md](reference/GLOSSARY.md) — canonical vocabulary (port, adapter, command,
  query, querier, composition root…).
- [reference/cheat-sheet.md](reference/cheat-sheet.md) — the module skeleton, the read/write rule,
  the sqlc flow, interview one-liners.

## Community (for wisdom)
- **r/golang** — <https://www.reddit.com/r/golang/> — idiomatic-Go architecture debates (search
  "hexagonal", "clean architecture", "sqlc vs sqlx").
- **Gophers Slack** (`#clean-architecture`, `#sql`) — <https://invite.slack.golangbridge.org/>
- **Three Dots Labs blog/community** — the most opinionated, battle-tested Go take on this stack.