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:
- Create the domain type. Use Domain Type Creator skill to generate the C++ domain model, serialisation, and JSON I/O.
- Create the SQL schema. Use SQL entity schema patterns and How do I create entity schema? to add the table, CRUD functions, and grants.
- Create the repository. Follow Entity lifecycle to scaffold the C++ repository class.
- Wire the service layer. Add NATS handlers and service methods following the protocol conventions in Protocol Reference.
- Create the Qt UI. Follow Qt entity patterns: ClientModel → list window → detail dialog → history dialog. Use How do I create entity UI?.
- Add CLI commands. Follow CLI entity patterns and How do I create entity commands? (CLI).
- Add HTTP endpoints. Follow Shell entity patterns and How do I create entity endpoints?.
- Write unit tests. Follow Unit test conventions and Unit Test Writer skill.
- 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_idpresent) are in place and registered inrls/rls_create.sql. - Detail dialog calls
promptChangeReason()before save (Create/Amend) and before delete;change_reason_codeandchange_commentaryare set on the domain entity before the request is sent. - Notify trigger uses
ores_utility_iso8601_timestamp_fn(change_timestamp)for the timestamp field inpg_notifypayloads. - PR is open with the entity changes.
See also
- Entity lifecycle — layer ordering and type mappings.
- Work a task through to merged PR — the PR lifecycle runbook.
- Runbooks catalogue — all runbooks.