Eco Manager Wiki

Appearance

03 — Runtime Configuration Model ​

Why Version The Model? ​

If administrators can change entity types, properties, relationships, and templates through a UI, the system needs a safe way to manage change.

Directly editing live metadata is dangerous because it can break:

  • existing entity data,
  • forms,
  • validation,
  • API behavior,
  • reports,
  • permissions,
  • integrations.

Use a draft/publish model.

Draft And Published States ​

text
Draft
    Editable metadata changes.
    Not used by normal entity CRUD.
    Can be validated and previewed.

Published
    Active metadata version.
    Used by the API and frontend.
    Immutable once published.
text
Create Draft
    ↓
Edit Metadata
    ↓
Validate Draft
    ↓
Preview Impact
    ↓
Publish Version
    ↓
Runtime API Uses Published Version

Model Version Table ​

A model version captures the state of the metadata configuration.

text
entity_model_versions

id uuid primary key
version_number integer not null
status text not null
created_by_user_id uuid not null
created_at timestamptz not null
published_by_user_id uuid null
published_at timestamptz null
notes text null
deleted_at timestamptz null

Example statuses:

text
draft
validating
ready_to_publish
published
archived
rejected

Metadata Ownership ​

Each metadata row should point to a model version.

Examples:

text
entity_type_definitions.model_version_id
property_groups.model_version_id
property_definitions.model_version_id
relationship_definitions.model_version_id
templates.model_version_id

This allows drafts to be edited without changing the live application model.

Publishing Rules ​

Publishing should be transactional.

A model version may be published only if:

  • all keys are unique within the model,
  • all referenced metadata exists,
  • no forbidden cycles exist,
  • no invalid type references exist,
  • destructive changes have been approved,
  • existing runtime data remains valid or has an explicit migration plan,
  • permissions have been checked,
  • audit events have been written.

Compatibility ​

Metadata changes fall into categories.

Safe Additive Changes ​

Usually safe:

  • add entity type,
  • add optional property,
  • add tag group,
  • add relationship type,
  • add template,
  • add view.

Potentially Breaking Changes ​

Need validation:

  • make optional property required,
  • change property value type,
  • remove property definition,
  • remove entity type,
  • restrict allowed parent/child types,
  • restrict relationship cardinality,
  • change tag selection mode.

Destructive Changes ​

Need explicit approval and migration plan:

  • delete entity type with existing entities,
  • delete property definition with existing values,
  • delete tag with assignments,
  • delete relationship definition with existing relationships,
  • change sensitive property handling.

Rollback ​

Rollback should mean re-publishing a previous compatible version, not mutating history.

Published versions should be immutable.

If a published version is wrong, create a new draft from an older version, validate it, and publish a new version.