Add a new entity across all layers

Table of Contents

This page documents a runbook — a named, repeatable composition of recipes and skills for a complete multi-step procedure. Each step references a recipe or skill by id-link.

Goal

Add a new domain entity (e.g. currency, counterparty, trade) with support across all layers: domain type, SQL schema, repository, service, Qt UI, CLI commands, HTTP endpoints, and unit tests.

Preconditions

  • Entity name and fields are defined.
  • Current sprint has a story for this entity.
  • Build environment is configured per development environment setup.

Steps

In execution order:

  1. Create the domain type. Use Domain Type Creator skill to generate the C++ domain model, serialisation, and JSON I/O.
  2. Create the SQL schema. Use SQL entity schema patterns and How do I create entity schema? to add the table, CRUD functions, and grants.
  3. Create the repository. Follow Entity lifecycle to scaffold the C++ repository class.
  4. Wire the service layer. Add NATS handlers and service methods following the protocol conventions in Protocol Reference.
  5. Create the Qt UI. Follow Qt entity patterns: ClientModel → list window → detail dialog → history dialog. Use How do I create entity UI?.
  6. Add CLI commands. Follow CLI entity patterns and How do I create entity commands? (CLI).
  7. Add HTTP endpoints. Follow Shell entity patterns and How do I create entity endpoints?.
  8. Write unit tests. Follow Unit test conventions and Unit Test Writer skill.
  9. Commit and PR. Follow Work a task through to merged PR for the full PR lifecycle.

Postconditions

  • Entity is functional across all layers.
  • All tests pass.
  • RLS policies (tenant isolation; party isolation if party_id present) are in place and registered in rls/rls_create.sql.
  • Detail dialog calls promptChangeReason() before save (Create/Amend) and before delete; change_reason_code and change_commentary are set on the domain entity before the request is sent.
  • Notify trigger uses ores_utility_iso8601_timestamp_fn(change_timestamp) for the timestamp field in pg_notify payloads.
  • PR is open with the entity changes.

See also

Emacs 29.1 (Org mode 9.6.6)