Codebase map

A quick index for finding your way around. Full Go API docs are on pkg.go.dev.

`cmd/pdf-server`

File	Contents
`main.go`	CLI app, subcommands, logger bootstrap.
`server.go` / `validate.go`	The two subcommand actions.
`wire.go`	Injector declarations (`wireinject` tag).
`wire_bindings.go`	The single `wireSet`: providers + bindings.
`wire_gen.go`	Generated graph (read this for the object graph).
`config.go`	Flag binding into config structs.

`app/`

Package	Key types
`server`	`Handlers`, `EchoRouter`, middleware, `swagger.go`.
`services`	`BasePDFRenderService`, `SimpleValidateService`, `DirectStatsService`, `TemplateSpecService`, domain errors.
`templates`	`Template`, `CompositeTemplate`, `Store`/`LazyStore`, `Validator`, `futures/`.
`templates/fileloader`	`FileTemplateLoader`, engines, sibling loaders, `composition/`, `remote/`, `helpers/`.
`pdfrender`	`PDFRenderer`, `Config`, `Document`, `WaitLifecycleEvent`.
`pdfrender/cdp`	`pool.go`, `factory.go`, `runner.go`, `page.go`, `render.go`, `config.go`.
`pdfrender/server`	Internal callback server + document store.
`config`	`GlobalConfig` aggregation.
`log`	logrus wrapper, context accessors, field constants.
`utils/trace_utils`	OTel providers, samplers, propagators.

Generated code

.gen/ — a Make stamp for wire_gen.go; test/lint/build depend on it.
mocks/ — mockery output mirroring app/; tests import from here.

Design diagrams

design/main_flow.puml, design/services.puml, design/templates.puml.

Conventions worth internalising

Thread ctx everywhere; get loggers via log.LoggerFromContext(ctx, name).
Open spans with tracerProvider.Tracer("Name") + tracer.Start(ctx, "op").
Domain errors implement Is/Unwrap; map to HTTP only in server.Handlers.buildError.
Render concurrency == browser pool size (RENDER_POOL_MAX_TOTAL).