The generator turns .graphqls files into Java sources in a fixed pipeline: parse, classify, validate, emit, write, and (for the reference consumer) compile.

flowchart LR
    A[".graphqls files"] --> B["RewriteSchemaLoader<br/>(parse + auto-inject<br/>directives.graphqls)"]
    B --> C["GraphitronSchemaBuilder<br/>(classify into<br/>GraphitronSchema)"]
    C --> D["GraphitronSchemaValidator<br/>(reject Unclassified*,<br/>surface diagnostics)"]
    D --> E["Generators<br/>(TypeFetcher / TypeClass /<br/>TypeConditions /<br/>QueryConditions / ...)"]
    E --> F["JavaFile.writeToPath<br/>(idempotent writes,<br/>orphan sweep)"]
    F --> G["consumer compile<br/>(graphitron-sakila-example<br/>verifies type + behaviour)"]

Three things to know about this pipeline that the diagram doesn’t show:

  1. The loader auto-injects directives.graphqls from the graphitron jar before parse, so consumer schemas never re-declare the canonical directives. This is what lets the classifier treat directive presence as ground truth one stage later: the schema loader has already fed every directive declaration into the parsed schema, regardless of whether the consumer’s .graphqls files mentioned them.

  2. Classification is the only place directives are read. GraphitronSchemaBuilder reads each directive once and resolves everything the generator needs into typed model values: table names, column references, method names, extraction strategies, batch keys. Generators downstream see the classified model and never touch directive syntax. The boundary keeps the model "what to emit," never "what to interpret."

  3. The writer’s idempotency contract is unconditional. On every run, JavaFile.writeToPath writes only files whose rendered content differs from disk (SHA-256 comparison) and deletes orphans in rewrite-owned sub-packages. Both halves run on every emit, not just full builds; this is what keeps the dev-loop’s IDE-recompile times proportional and what stops a delete-a-type cycle from leaving stale files behind. Pinned by IdempotentWriterTest and GeneratorDeterminismTest.

The Code Generation Triggers page is a zoomed-in view of the middle three stages (schema → classified model → generators). This page names the loader, the validator, the writer’s idempotency contract, and the consumer compile that closes the loop.

← Explanation index