Schema generator workflow

What this area does

The schema generator is one of the repository’s core product surfaces. It lets users create, edit, import, export, version, and restore extraction schemas, and it can derive schema suggestions from uploaded documents.

The route family is mounted from App.jsx under /schema-generator and is split into several focused screens instead of one monolithic page.

Route family

/schema-generator — schema list / landing route.
/schema-generator/new — choose a creation path.
/schema-generator/create — guided schema creation.
/schema-generator/manual — manual editor.
/schema-generator/import — import flow.
/schema-generator/export — export flow.

Workflow map

flowchart TD
  list[Schema list] --> choose[Choose creation path]
  choose --> create[Guided create]
  choose --> manual[Manual edit]
  choose --> import[Import]
  choose --> export[Export]
  create --> save[Save generated schema]
  manual --> version[Create new version]
  list --> detail[Schema detail/version timeline]
  detail --> restore[Restore old version]
  detail --> rules[Attach processing rules]
  create --> docgen[Generate from document]

Primary implementation and owning symbols

The workflow is assembled from the page files in src/pages/schemagenerator/:

route wrappers: SchemaListRoute, SchemaChoosePage, SchemaCreateRoute, SchemaManualRoute, SchemaImportRoute, SchemaExportRoute
editing and display surfaces: SchemaDetailPanel, SchemaFieldEditor, SchemaVersionColumn, SchemaVersionTimeline
orchestration: SchemaCreateWorkflow, SchemaImportExport, SchemaSaveModal, SchemaSidebar, ProcessingRulesPanel
utility: schemaTypeUtils.js

Service coupling

The workflow relies on schemaService, which is where the actual backend contract lives.

Key backend interactions

list schemas with pagination and optional document/country filters,
create/update/delete schemas,
create a new version or restore an older version,
generate a schema from a document upload,
save a generated schema,
resolve pre/post-processing rules into numeric PKs before submit.

Schema data model boundaries

The frontend deliberately treats schema_value as the backend payload that carries the extraction structure. When metadata is available, the service may wrap fields in an object that includes internal hints such as agent, sub-agent, and model markers. That metadata is used for display and provenance, but the generated-save path still needs the schema value to be parseable in the shape the backend accepts.

Invariants

Schema versioning is backend-driven; the frontend creates new versions rather than mutating historical rows in place.
Rule references must resolve to numeric PKs before submit.
Document-driven generation and manual editing are separate entry paths but converge on the same schema persistence service.
Generated schemas and manually authored schemas share the same display surfaces once saved.

Evidence-backed tests

tests/contract/schemaService.test.js is the main proof suite for this subsystem. It verifies:

list pagination and filters,
response normalization from array vs paginated envelopes,
create/update/delete request shapes,
metadata wrapping in schema_value,
rule PK resolution,
document generation FormData shape,
save-generated request fields.

The Playwright workflow tests under e2e/tests/workflow/verify-schemas.spec.js and the schema preflight specs exercise the page-level journey through the generator and portal screens.

Practical extension points

If you change the schema-generator UI, the safest order is:

update the route/page component,
update schemaService or the related utility,
extend the contract test to pin the request shape,
update the workflow Playwright spec if navigation or page sequencing changes.