Architecture and data flow

Architecture and data flow

Mettada is a compiler/generator platform embedded into consumer applications. The root repository hosts platform packages and pilot consumers; it is not a Laravel application itself.

Package ownership

Package	Responsibility
backend-core	Framework-independent DSL loading/validation, entity/workspace compilation, IR and metadata, dependency graph, relationships, permission resolution, and generator contracts.
backend-laravel	Laravel integration, CLI/Artisan commands, pipeline orchestration, generated Laravel artifacts, and workspace contract emission.
contracts	Shared versioned workspace contract and schema.
frontend-core	Framework-neutral contract compilation, navigation, routing, and data/runtime abstractions.
frontend-react	React rendering components and application shell.
Consumer application	Business rules, custom endpoints/screens, application configuration, data, and tests.

Source entry points: EntitySpecCompiler, DSLPipeline, ReactUIGenerator, and MettadaSyncCommand.

End-to-end flow

flowchart LR
  A[Consumer YAML specs] --> B[SpecLoader + JSON Schema validation]
  B --> C[backend-core compilers]
  C --> D[Platform metadata and IR]
  D --> E[DSLPipeline relationship and graph stages]
  E --> F[Laravel generator registry]
  F --> G[Consumer backend artifacts]
  E --> H[ReactUIGenerator]
  H --> I[workspace.v1 contract]
  I --> J[frontend-core contract compiler]
  J --> K[frontend-react runtime]
  G --> L[Consumer application]
  K --> L
  L --> M[Application-owned business code and tests]

The documented order of pipeline stages is load, validate, compile, resolve relationships, build/validate graph, construct metadata, compute diffs, select targets, register generators, generate output, and clean obsolete feature output. Re-check the pipeline implementation when changing ordering or side effects.

Architectural invariants

• backend-core does not own Laravel-specific generators or framework facades; those belong to backend-laravel.
• Generated workspace output is validated against the shared versioned contract before it is persisted.
• Consumer-owned business invariants do not become guaranteed merely because a workspace contract or CRUD endpoint was generated.
• Generated output and consumer custom code have explicit ownership boundaries; changing a generator can affect every consumer on the next sync.

History versus current behavior

docs/platform-context/README.md is a reconciliation aid. Its dated sections and long subsystem snapshots capture historical states. Use current package code and tests as evidence for current behavior; do not copy old test counts or retired package names into new documentation.