How do I create a new entity?

Question
Answer
Script
Tested by

Question

How do I add a new domain entity to ORE Studio?

Answer

1. Read the standard first

Every entity must conform to entity lifecycle before writing any code. That document specifies what each layer must contain and what the defaults are. Partial entities or disabled defaults without written rationale are not acceptable.

2. Create the codegen model

Create projects/ores.codegen/models/{component}/{entity}_domain_entity.json. Minimum required content in the qt section:

"qt": {
  "has_uuid_primary_key": true,
  "has_pagination": true,
  "has_history": true,
  "detail_fields": [ ... ],
  "history_request_class":  "{component}::messaging::get_{entity}_history_request",
  "history_response_class": "{component}::messaging::get_{entity}_history_response",
  "history_message_type":   "get_{entity}_history_request",
  ...
}

If any of has_history, has_pagination, or detail_fields is absent or disabled, add a deviation_rationale_{dimension} key with a one-sentence justification before proceeding.

3. Generate and integrate each layer

# SQL (table DDL, trigger, RLS, artefact table)
./compass.sh codegen entity generate <entity> --address ores.sql.schema

# C++ API and core (domain type, repository, service, handler)
./compass.sh codegen entity generate <entity> --address ores.cpp

# Qt UI (model, MDI window, detail dialog, history dialog, controller)
./compass.sh codegen entity generate <entity> --address ores.cpp.qt

Follow the codegen-add-entity skill for CMakeLists integration, controller wiring, and PR checkpoints at each layer boundary.

4. Validate

# SQL schema integrity
./projects/ores.sql/utility/validate_schemas.sh

# Component documentation
./projects/ores.codegen/validate_docs.sh

Ask the user to build the affected targets before raising each PR.

Script

See codegen-add-entity skill for the full phase-by-phase execution guide and layer-specific skills for deep detail on each layer.

Tested by

Build and test suite for the component via compass build (not raw cmake --build): ./compass.sh build {component}.core.tests.