Background and rationale, organised by what you might want to understand. None of these pages are required reading; they exist so you can build a mental model when something surprises you, or read up on a design choice before extending past it.

Architectural framing

How the build and the runtime fit together

  • How it works: the pipeline that turns your GraphQL schema and your jOOQ catalog into the resolvers your application serves. Build-time and request-time, in 30 seconds.

  • Classifier mental model: what the build’s classification step does, in user-visible terms. Useful when reading rejection messages or understanding directive interactions.

  • The batching model: why N+1 doesn’t appear in Graphitron-generated code, what @splitQuery and @lookupKey actually do at runtime, and what the N × M contract demands of your custom conditions.

Why specific things work the way they do

  • Design decisions: user-visible "why does it work that way" answers for the constraints that look surprising on first contact (why @condition methods take a table, why @lookupKey blocks pagination, why mutations require @table on the input type, and more).

The wider context

The user-manual explanation chapter sits next to the deployed site’s existing top-level explanation pages, which cover orientation rather than the manual-internal pipeline:

  • Graphitron principles: the design philosophy in plain prose.

  • Vision and goal: what problem Graphitron solves and how it approaches the solution.

  • Dependencies: why jOOQ and graphql-java are foundational, and what that means for users.

  • Security: why authorization stays in the database.

For contributor-facing material (sealed hierarchies, classification source map, generator dispatch, runtime extension points), see the architecture chapter.

← Back to the manual landing