# Glossary — v2 Architecture

Canonical vocabulary. Once a term is defined here, every lesson uses it the same way. Interview
term ↔ this-repo term mapped where they differ.

## Hexagonal / ports & adapters

- **Hexagonal architecture** — Cockburn's name for **ports & adapters**. The application core sits
  in the middle; everything external (DB, gRPC, Kafka, tests) plugs in through ports at the edges.
  Goal: the core is driven by users, programs, tests, or batch scripts equally, and is testable in
  isolation from real devices/DBs.
- **Port** — an **interface** the core owns. A *driven* port (repository, publisher) is what the
  core needs from the outside; a *driving* port is how the outside invokes the core. In this repo:
  `core/port/repository/*.go`, `infrastructure/repo_port.go`, `repository/storage.go`.
- **Adapter** — a concrete **implementation** of a port that talks to a real technology
  (postgres, gRPC, Kafka). In this repo: `infrastructure/postgres/`, `infrastructure/repositories/`.
- **Dependency inversion** — the core depends on the port (interface); the adapter depends on the
  port too. Neither the core nor the port imports the adapter. When the core imports the adapter,
  that's a **leak** (see conversationmgmt).
- **Composition root** — the *one* place concrete adapters are wired into ports. Should live at the
  outermost edge: `cmd/server/{service}/gserver.go` (eureka) or a controller constructor (spike).
  If it lives inside the core, dependency inversion has leaked.
- **Domain layer** — entities, value objects, business rules. In eureka v2, **pure Go stdlib types,
  no `pgtype`**. In spike, split into `domain/model` (pgtype, DB-facing) and `domain/dto` (plain Go,
  app boundary).
- **`pgtype` leak** — a smell where DB-driver types (`pgtype.Text`, etc.) appear in domain/usecase
  signatures instead of plain Go types, coupling the core to the driver. Real example:
  notification `announcement`.

## CQRS

- **CQRS (Command Query Responsibility Segregation)** — use a **different model to write than to
  read**. Fowler's caveat: "adds risky complexity"; apply only to parts of a system that need it.
- **Command** — a request that **changes state** (create, update, delete). Handled by a
  *command handler*. In this repo: `application/commands/*_handler.go`.
- **Query** — a request that **reads state**, no side effects. Handled by a *query handler*. In this
  repo: `application/queries/*_handler.go`.
- **Handler** — the object that executes one command or query. Holds its dependencies (DB, repo
  interfaces) as struct fields; typically **one operation per handler/file**.
- **Command bus / mediator** — a dispatcher that routes a command to its handler. **This repo has
  none** — controllers call handlers directly. Say so in interviews; don't invent one.
- **CQS (Command Query Separation)** — Fowler's older *method-level* rule (a method either changes
  state or returns data, not both). The ancestor of CQRS, **not** the same thing.
- **Read/write asymmetry (this repo's rule)** — eureka's data-access rule: **reads** may call the
  sqlc `Querier` directly from a usecase (any table); **writes** MUST go through a repository
  interface (never call a mutating sqlc query from a usecase). Keeps invariants/events/observability
  on the write path.

## sqlc

- **sqlc** — a tool that reads your `.sql` files + schema and **generates type-safe Go**. You write
  SQL; it writes the Go structs and methods. Compile-time checks on columns and params.
- **Query annotation** — the magic comment above a query: `-- name: GetX :one` (or `:many`,
  `:exec`, `:execrows`). Tells sqlc the method name and return shape.
- **`Querier`** — the generated interface (`emit_interface: true`) listing every query method. The
  repo adapter holds one and delegates to it. Mockable → unit tests without a DB.
- **`Queries` / `New()`** — the generated struct implementing `Querier`. `db.New()` builds it;
  with `emit_methods_with_db_argument`, the DB (`database.Ext`) is passed **per method**, not stored.
- **Querier injection** — the v2 convention: the repo struct has a `querier {Module}Querier` field,
  filled by `New{X}Repo()` calling `db.New()`. Must use the **constructor** — a bare `&Repo{}`
  leaves `querier` nil and panics.
- **WASM plugin** — this repo's v2 sqlc uses a custom Manabie `sqlc-gen-go.wasm` codegen (not stock),
  which adds `emit_dynamic_filter`, built-in `emit_tracing`, and `go_generate_mock`.
- **`emit_dynamic_filter`** — v2-only sqlc feature: build optional `WHERE` clauses from params that
  may be absent, without hand-writing SQL string concatenation.
- **Dynamic SQL (the alternative)** — what spike/notification/conversationmgmt do instead of sqlc:
  build the query string at runtime with `database.GetFieldNames` / `GetScanFields` /
  `GeneratePlaceholders`, values via `$N`. Hand-rolled, not generated.

## This-repo layout terms

- **v2** — the newer architecture generation. Literal dir `internal/eureka/v2/`; called the
  "modules/ layer" in spike/notification. Opposite: **v1 / legacy** (`entities/`, `repositories/`,
  `services/` — avoid adding to it).
- **Module** — a self-contained bounded context under `modules/` (or `v2/modules/`) with its own
  domain, ports, adapters, and transport. E.g. `email`, `system_notification`, `conversation`,
  `assessment`, `learning_time`.
- **`database.Ext`** — the interface accepting both a real pool and a `pgx.Tx`. Passing it per-call
  is what lets a command handler run several repo writes inside one `ExecInTx`.
- **`.claude/rules/*.md`** — the load-bearing convention files (storage.go purity, Querier injection,
  error translation, security). The real spec for v2 — more authoritative than the readmes.