Adding a New Domain Service

Add an entry to the Service registry (projects/modeling/service_registry.org):

* <name>
:PROPERTIES:
:psql_var:    <name>_service
:env_key:     <NAME>_SERVICE
:iam_role:    <Name>Service
:description: <Human-readable description>
:email:       <name>_service@system.ores
:END:

** DML prefixes

- ores_<name>_

This is the source of truth that drives the four auto-generated files below.

cmake --build --preset linux-clang-debug-ninja --target codegen

The following files are regenerated from the service registry automatically; do not edit them by hand:

Add component wildcard and per-entity CRUD permissions to projects/ores.sql/populate/iam/iam_permissions_populate.sql:

-- <Name> Component Permissions
PERFORM ores_iam_permissions_upsert_fn(ores_utility_system_tenant_id_fn(),
    '<name>::<entities>:read',   'View <entity> details');
PERFORM ores_iam_permissions_upsert_fn(ores_utility_system_tenant_id_fn(),
    '<name>::<entities>:write',  'Create and modify <entities>');
PERFORM ores_iam_permissions_upsert_fn(ores_utility_system_tenant_id_fn(),
    '<name>::<entities>:delete', 'Archive <entities>');
PERFORM ores_iam_permissions_upsert_fn(ores_utility_system_tenant_id_fn(),
    '<name>::*', 'Full access to all <name> operations');

Note: This file is hand-maintained until the codegen IAM plan is complete. See doc/plans/2026-05-18-codegen-iam-permissions.org.

Add a service role with its permission assignments to projects/ores.sql/populate/iam/iam_roles_populate.sql:

-- <Name> service: full own-component + tenant read
PERFORM ores_iam_roles_upsert_fn(
    ores_utility_system_tenant_id_fn(), '<Name>Service',
    '<Human-readable description>');
PERFORM ores_iam_role_permissions_assign_fn(
    ores_utility_system_tenant_id_fn(), '<Name>Service', '<name>::*');
PERFORM ores_iam_role_permissions_assign_fn(
    ores_utility_system_tenant_id_fn(), '<Name>Service', 'iam::tenants:read');

Add cross-service permission assignments here too if the service needs to read from another component (e.g. dq::change_reasons:read).

Add the service binary to projects/ores.sql/populate/controller/controller_service_definitions_populate.sql:

('ores.<name>.service', 'ores.<name>.service', 1, null, '<Description>'),

Columns: (service_name, binary_name, priority, config_path, description).

Add the startup dependency to projects/ores.sql/populate/controller/controller_service_dependencies_populate.sql:

('ores.<name>.service', 'ores.iam.service'),

All domain services depend on ores.iam.service. Add additional dependencies if the service requires other services to be up first.

Add ores.<name>.service to the _SERVICES list in projects/ores.compass/src/nats_certs.py, then generate the certificate:

./compass.sh nats certs

Existing certificates are skipped, so running without --force is safe and will only create the new entry.

Apply all SQL changes to a local development database:

./projects/ores.compass/compass.sh db recreate -k -y

This runs setup_schema.sql (which calls the create scripts and grants) and then the populate scripts. It verifies the new IAM entries, role, service account, grants, and controller definitions in a single pass.

Update .env with the new service credentials:

./projects/ores.compass/compass.sh env init --preset <preset> -y

This adds ORES_<NAME>_SERVICE_DB_USER and ORES_<NAME>_SERVICE_DB_PASSWORD to .env. Only required on environments that have not yet had the service entry added; if the service was in the registry when the environment was last initialised the variables will already be present.

Create the three standard C++ sub-projects under projects/:

Add all three to projects/CMakeLists.txt:

add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/ores.<name>.api)
add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/ores.<name>.core)
add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/ores.<name>.service)

If the service needs a UI panel, create projects/ores.qt.<name> as a Qt plugin (shared library with Q_PLUGIN_METADATA, subclassing PluginBase). Add it to projects/CMakeLists.txt:

add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/ores.qt.<name>)

Steps 3 and 4 will be eliminated once the codegen IAM plan (doc/plans/2026-05-18-codegen-iam-permissions.org) is complete.