Modules

The repository is a single Maven reactor rooted at the graphitron-rewrite-parent parent pom (10-SNAPSHOT). Thirteen modules cover the generator, its inputs, its consumers, the reusable runtime surface, the tooling that wraps both ends, and the documentation site. The roadmap-tool check-module-enumeration step fails the build if this table stops naming a module the root pom declares, so the set below cannot fall behind the reactor:

Module Purpose

Module	Purpose
`graphitron-javapoet`	Internal fork of Square JavaPoet; the emit-time API every generator builds through.
`graphitron-model`	The fact tier: the DDL that defines the generator’s fact base, the jOOQ compile-time surface generated from it, the in-memory H2 bootstrap a run captures into, and capture itself, which reads the consumer’s three sources (their GraphQL schema, their jOOQ-generated database classes, their compiled Java) and writes down what it found. Builds before the core, so editing the DDL fails javac in every consumer that touched the changed relation and the core cannot reach back into the tier that feeds it.
`graphitron`	The generator core: the classifier, the validator, the planners and every emitter. Reads facts and writes none.
`graphitron-fixtures-codegen`	Builds the test database and runs jOOQ codegen against it.
`graphitron-sakila-db`	Packages those generated jOOQ classes (Sakila-inspired catalog plus the `nodeidfixture` and `idreffixture` sub-schemas) as a jar that downstream tests depend on.
`graphitron-sakila-service`	`@service` / `@externalField` / `@condition` implementations referenced from the example schemas (`FilmService`, `SampleQueryService`, …). Compile-scope dep on `graphitron-sakila-db` for the jOOQ tables.
`graphitron-maven-plugin`	Maven plugin: `generate`, `validate`, `capture` and `dev` Mojos (the dev mojo provides the watch loop). Also the home of the cross-tier tests: the dev mojo is what wires the generator to the two clients, so a test whose subject is the build and a client agreeing lives here, above both, rather than inside a client reaching up.
`graphitron-sakila-example`	End-to-end consumer: compiles emitted Java against a real jOOQ catalog, executes it against Postgres, and serves a runnable Quarkus + JAX-RS reference application from the same module.
`graphitron-lsp`	Editor LSP server for `.graphqls` authoring. Reads the fact store and the buffer under the cursor; no dependency on `graphitron` at any scope.
`graphitron-mcp`	MCP server embedded in the `dev` Mojo: serves an `about` prompt, a `directives` resource, and read-only catalog / schema / diagnostics / `docs.search` tools to an MCP-aware agent over loopback Streamable HTTP. The dependency-quarantine seam that keeps its heavy semantic-index dependencies off the plugin’s own compile surface.
`graphitron-jakarta-rest`	Reusable, spec-conformant GraphQL-over-HTTP serving library (vendor-neutral Jakarta REST + CDI) over a Graphitron schema: the `/graphql` resource, status-code semantics, SDL endpoint, and GraphiQL page, behind a `GraphitronApplication` SPI the consumer’s adapter implements. The built-in `/graphql` resource is a thin mount over two public delegates a consumer can mount anywhere instead: `GraphqlHttpHandler` (the whole decode/decide/execute/encode pipeline, taking an optional `OperationPolicy` that refuses non-permitted operation types before execution) and `GraphiqlBundle` (the page and its assets), with `GraphitronApplication.builtInEndpointEnabled()` turning the built-in route off. The GraphiQL page is self-hosted: a version-pinned GraphiQL 5 + React bundle ships as committed classpath resources and is streamed from the bundle’s `assets/{name}` endpoint (no runtime CDN), with the one-shot Vite recipe that reproduces it under `tools/graphiql-build/`; the Maven build never invokes node. The first hand-written runtime artifact consumers depend on; compiles at `<release>17</release>`.
`roadmap-tool`	Regenerates `roadmap/README.md` from per-item front-matter. Also hosts the repo-wide prose tripwires bound to `verify`: the markdown-table check, the transient-citation check over the agent-onboarding documents, and the module-enumeration check that guards this table.
`docs`	Packaging `pom`; renders the AsciiDoc site (user manual, architecture pages, roadmap) to `target/generated-docs/` and is deployed to GitHub Pages from trunk. Carries `maven.deploy.skip`, so it publishes a site and not an artifact.

graphitron-javapoet

Internal fork of Square JavaPoet; the emit-time API every generator builds through.

graphitron-model

The fact tier: the DDL that defines the generator’s fact base, the jOOQ compile-time surface generated from it, the in-memory H2 bootstrap a run captures into, and capture itself, which reads the consumer’s three sources (their GraphQL schema, their jOOQ-generated database classes, their compiled Java) and writes down what it found. Builds before the core, so editing the DDL fails javac in every consumer that touched the changed relation and the core cannot reach back into the tier that feeds it.

graphitron

The generator core: the classifier, the validator, the planners and every emitter. Reads facts and writes none.

graphitron-fixtures-codegen

Builds the test database and runs jOOQ codegen against it.

graphitron-sakila-db

Packages those generated jOOQ classes (Sakila-inspired catalog plus the nodeidfixture and idreffixture sub-schemas) as a jar that downstream tests depend on.

graphitron-sakila-service

@service / @externalField / @condition implementations referenced from the example schemas (FilmService, SampleQueryService, …). Compile-scope dep on graphitron-sakila-db for the jOOQ tables.

graphitron-maven-plugin

Maven plugin: generate, validate, capture and dev Mojos (the dev mojo provides the watch loop). Also the home of the cross-tier tests: the dev mojo is what wires the generator to the two clients, so a test whose subject is the build and a client agreeing lives here, above both, rather than inside a client reaching up.

graphitron-sakila-example

End-to-end consumer: compiles emitted Java against a real jOOQ catalog, executes it against Postgres, and serves a runnable Quarkus + JAX-RS reference application from the same module.

graphitron-lsp

Editor LSP server for .graphqls authoring. Reads the fact store and the buffer under the cursor; no dependency on graphitron at any scope.

graphitron-mcp

MCP server embedded in the dev Mojo: serves an about prompt, a directives resource, and read-only catalog / schema / diagnostics / docs.search tools to an MCP-aware agent over loopback Streamable HTTP. The dependency-quarantine seam that keeps its heavy semantic-index dependencies off the plugin’s own compile surface.

graphitron-jakarta-rest

Reusable, spec-conformant GraphQL-over-HTTP serving library (vendor-neutral Jakarta REST + CDI) over a Graphitron schema: the /graphql resource, status-code semantics, SDL endpoint, and GraphiQL page, behind a GraphitronApplication SPI the consumer’s adapter implements. The built-in /graphql resource is a thin mount over two public delegates a consumer can mount anywhere instead: GraphqlHttpHandler (the whole decode/decide/execute/encode pipeline, taking an optional OperationPolicy that refuses non-permitted operation types before execution) and GraphiqlBundle (the page and its assets), with GraphitronApplication.builtInEndpointEnabled() turning the built-in route off. The GraphiQL page is self-hosted: a version-pinned GraphiQL 5 + React bundle ships as committed classpath resources and is streamed from the bundle’s assets/{name} endpoint (no runtime CDN), with the one-shot Vite recipe that reproduces it under tools/graphiql-build/; the Maven build never invokes node. The first hand-written runtime artifact consumers depend on; compiles at <release>17</release>.

roadmap-tool

Regenerates roadmap/README.md from per-item front-matter. Also hosts the repo-wide prose tripwires bound to verify: the markdown-table check, the transient-citation check over the agent-onboarding documents, and the module-enumeration check that guards this table.

docs

Packaging pom; renders the AsciiDoc site (user manual, architecture pages, roadmap) to target/generated-docs/ and is deployed to GitHub Pages from trunk. Carries maven.deploy.skip, so it publishes a site and not an artifact.

graphitron-tree-sitter-natives sits alongside these as a plain subdirectory (not a reactor module); it packages the tree_sitter_graphql grammar and libtree-sitter runtime the LSP loads at startup.

Per-module READMEs are deliberately not maintained, with one exception: graphitron-sakila-example/README.md is the consumer-facing "copy this" recipe that the root README and the quick-start send readers to, and its relative links are build-enforced by ReadmeLinkIntegrityTest in that module’s test suite. For everything else this table is the orientation surface, and lives next to the architecture pages so it stays in sync with the pipeline they describe.

← Reference index