Generation, workspace contract, and frontend runtime

Generation, workspace contract, and frontend runtime

Generator boundaries

Backend CRUD generators and Laravel filesystem/runtime adapters live in backend-laravel; backend-core provides framework-independent generator contracts and dispatch. The Laravel adapter registers generators and gives them the compiled metadata/context. Generator output is application code, so changes must preserve ownership and re-sync behavior.

ReactUIGenerator transforms workspace metadata into the shared workspace.v1 shape and validates that output before writing it. The canonical schema is packages/contracts/schemas/workspace.v1.schema.json; the frontend runtime consumes this contract rather than the backend’s authoring YAML directly.

Frontend consumption

frontend-core owns contract-oriented framework-neutral definitions and runtime primitives. frontend-react provides React components and shell integration. A consumer’s generated composition code wires those packages and the emitted contracts into its application. Custom consumer UI may use the generated runtime or own separate screens, but must respect consumer authorization and API boundaries.

defineWorkspaceFromContract in frontend-core adapts the contract into runtime workspace definitions; frontend-react renderers then compose pages and sections with registered components. This is an adapter boundary: do not make React components depend on backend PHP metadata classes. For component behavior, check both the framework-neutral definition compiler and the React renderer tests.

Evolving a contract

Treat the JSON Schema as executable interface documentation:

1. Decide whether the change is additive or behaviorally breaking.
2. Update the canonical schema and TypeScript/runtime contract types.
3. Update backend emission/normalization and frontend consumption together.
4. Add schema-valid fixtures and producer/consumer tests.
5. Regenerate docs and update examples.
6. Run contracts, frontend-core, frontend-react, backend adapter, and consumer validation relevant to the changed fields.

Avoid silently changing the meaning of an existing field. If consumers require a new incompatible shape, define and document a new contract version and an explicit transition strategy.