# Senior v2 Architecture Playbook

Compressed reference for the senior-only v2 architecture extension. Pair with [cheat-sheet.md](./cheat-sheet.md), [GLOSSARY.md](./GLOSSARY.md), and [repo-v2-map.md](./repo-v2-map.md).

## The senior shift
Intermediate v2 understanding is: "I can name the layers, the ports, the CQRS folders, and the sqlc flow."

Senior v2 understanding is: "I can review a module boundary, explain whether the composition root is in the right place, reason about transactions and cross-module writes, decide whether a smell is cosmetic or load-bearing, and explain the architecture honestly in an interview."

## The six senior lenses
1. **Wiring belongs at the edge** — if the core news up adapters, the dependency arrow is already compromised.
2. **A smell is interesting only if it changes the dependency story** — cosmetic mess matters less than core→infra leakage.
3. **Transaction seams are architecture seams** — `database.Ext` exists so the same repo methods can run under a pool or a tx.
4. **Transport reuse is a design choice** — reusable handlers across gRPC/Kafka/NATS are a feature only if the business logic stays central and the protocol wrappers stay thin.
5. **Generated code still needs architecture** — sqlc helps with query safety, but repos and usecases still decide where reads and writes are allowed.
6. **Migration honesty beats purity theatre** — v1 and v2 coexist because gradual replacement is the strategy, not because the team forgot how to finish.

## Senior review checklist
- Is the composition root really at the edge, or has the core started constructing concrete adapters?
- Does the interface belong to the core, or is it just a wrapper around a concrete implementation?
- Are writes flowing through the intended repository seams, or is a usecase bypassing them?
- Is `database.Ext` being used to support transactional composition the right way?
- Are transport adapters thin, or has protocol logic leaked into the business layer?
- Is the module worth copying, worth studying carefully, or worth avoiding as a template?
- Is a proposed change actually improving the dependency story, or only renaming folders?

## Interview answer shapes
### What is the biggest architecture smell you have seen in this repo?
A strong answer names the conversationmgmt core→infrastructure leak, explains why it breaks the dependency direction, and contrasts it with cleaner wiring in spike or eureka.

### Why not put sqlc everywhere?
Because it is a trade-off. Query-heavy services benefit more from the generated safety and mockable querier layer; simpler CRUD services may get less value than the codegen cost and operational overhead.

### What is the real purpose of `database.Ext`?
It is the seam that lets the same repository method accept either a real pool or a transaction handle, which is how command handlers compose several writes atomically without changing every repo signature.

### Why no CQRS bus here?
Because the repo chose the lightweight form: separate command and query handlers for clarity and testability, but no mediator, no event sourcing, and no extra machinery unless the complexity truly pays for itself.

### How do you test a v2 module well?
Mock at the seam that belongs to the layer: repos for usecase tests, usecases for transport tests, and DB behavior for repository tests. The architecture should make those seams obvious.