Project Concord
The backend and frontend maintained roughly a hundred separate descriptions of the same data structures. Differences between those definitions could lead to API payloads that the frontend did not expect.
The Go backend and TypeScript frontend each defined structures for monitors, queries and pipelines. Changes had to be maintained in both codebases.
Generate types and validation from Go definitions
The Go structs already used tags for JSON marshalling. Validation constraints were added to those tags, for example jsonschema:"minimum=0,maximum=100", so the same definitions specify both the wire format and valid values.
The tags export to JSON Schema, which generates Zod validators for runtime checks and TypeScript types for the frontend.
A generated validator checks a network payload at runtime against the same schema used to generate the frontend type.
The work began as a hackathon project and was rolled out one domain at a time: monitors, rehydrations, agent configs, patterns, stats, logs, knowledge, facets and the service map. This replaced roughly a hundred hand-written UI models.
Resolving differences between the definitions
Generating the frontend types and validators from the Go definitions exposed existing inconsistencies: fields that were optional on one side and required on the other, enum members missing from the frontend, and mismatched nullability.
The inconsistencies were corrected in both codebases, so the generated types and runtime validators matched the API definitions.
Checking generated files in CI
CI regenerates the schemas from the Go types and fails if the generated output differs from the committed files.
The CI check prevents a schema from being changed without updating the generated files, and ensures changes to Go types are accompanied by corresponding generated changes.
Using the same approach at Archon
At Archon, Pydantic models in a FastAPI service generated an OpenAPI document and TypeScript types. The shared client and mock handlers used those generated definitions.
At Archon, CI regenerates the OpenAPI schema and TypeScript types, and fails if either differs from the committed files. OpenAPI describes endpoints as well as data structures.