How to add a new entity

This walkthrough assumes you've read the layering rules — each step below maps to one of them.

Say you're adding publisher.

1. Describe the API surface. Add request/response shapes to api/books/v1/openapi.yaml (for REST) or a new .proto under api/<svc>/v1/ (for ConnectRPC).

2. Add a migration — internal/database/pgdb/migrations/002_publishers.up.sql and the matching .down.sql.

3. Write sqlc queries in internal/database/pgdb/queries/publishers.sql.

4. Run just generate to regenerate API code and dbgen queries.

5. Create a data-access Service at internal/database/publishers/service.go with the usual shape:

   type Service struct { Postgres *pgdb.Postgres }
   func (s *Service) GetByID(ctx context.Context, id string) (*Publisher, error) { ... }

   Every method bodies out as s.Postgres.Queries(ctx, func(ctx, q) error { ... }).

6. Create a handler at internal/publishers/handler.go that implements the relevant generated server interface and converts between domain and API types.

7. Wire it in internal/cmd/server/runner.go — construct the Service, construct the handler, register it on the mux. Keep the order: services first, handlers second, mux registration last. If the entity owns a resource that needs ordered teardown (a worker, a producer), add it to the shutdown sequence too — see Extending the shutdown sequence.

If you ever feel like adding a new layer to accommodate an entity, stop and question it. The layering rules are the contract.