Response represents what the server sends back to the client

==================== CONCRETE HANDLERS ==================== GetUser handles requests like GET /api/users/123 It EMBEDS BaseHandler — meaning it gets B

All runtime config. pydantic VALIDATES every field automatically when the object is constructed — mandatory fields without a default rais

The unit depends on an interface — the seam that lets us substitute a double (§6).

AppError is the canonical error type for this application.

==================== BASE HANDLER (COMPOSITION / "INHERITANCE") ==================== BaseHandler holds shared logic that MULTIPLE handlers need Instea

"INHERITANCE" via COMPOSITION: BaseHandler holds shared logic; concrete handlers EMBED it and reuse its methods.

"INHERITANCE" via COMPOSITION: BaseModel holds shared fields; embedding it into User reuses them (and their json tags).

1) Injected clock — deterministic time.

Config holds all runtime application settings. The `validate` tags enforce rules at startup — this is the single most important safeguard for config m

CreateBook is the SCHEMA. The tags declare every rule: required -> existence check the Go type -> type check (string) min=5,max=100 -> constrai

---- schema (the gate) ----

CreateBookRequest is our native format — the bind target.

Payload struct — serialized to JSON in queue

GetUser embeds BaseHandler (composition) and satisfies Handler.

==================== INTERFACE (ABSTRACTION) ==================== Handler is an INTERFACE — a contract/promise It says: "any type that has a method ca

ABSTRACTION: Handler is an interface — it names a capability ("be able to Handle a request") without saying how. Any type with a Handle method IS-A Ha

POLYMORPHISM: JSONSerializer implements Serializer. Any other format (YAML, Protobuf) could implement the same interface and be used interchangeably t

ListBooks handles requests like GET /api/books?page=2 Also embeds BaseHandler for the same shared log() method

Depend on an INTERFACE, not a concrete type — that interface is the seam.

==================== DATA STRUCTURES ==================== Request represents an incoming HTTP request from a client Think of it as: "what the browser/

==================== ROUTER (ENCAPSULATION) ==================== Router is the main brain — it stores all registered routes and matches incoming reque

ENCAPSULATION: "routes" is lowercase => unexported => private to the package. Outsiders cannot touch the table directly; they go through the methods w

ABSTRACTION: Serializer names a capability — "turn data into bytes and back" — without binding to a concrete format. Code depends on this contract, so

*bool so we can tell "false" apart from "missing".

ENCAPSULATION: an exported struct whose JSON shape is controlled by tags. "password" is unexported (lowercase) -> private AND invisible to the JSON en

In tests: a FAKE in-memory repo (no real DB needed)

Embed the generated UnimplementedUserServiceServer for forward-compat.