Component Creator

When to use this skill

When the user requests the creation of new components for ORE Studio. Components in ORE Studio terminology, are the projects under the projects directory. Example of existing components: ores.accounts, ores.refdata.

How to use this skill

Important: Use the codegen system to scaffold new components. Do not create files manually — the component profile in ores.codegen generates all boilerplate automatically and ensures consistency with the rest of the codebase.

  1. Gather information about the new component (name, purpose, etc).
  2. Create the component model JSON file for codegen.
  3. Run the code generator with the component profile.
  4. Register the component in projects/CMakeLists.txt.
  5. Add the PlantUML diagram stub (not yet generated by codegen).
  6. Build and test.

Detailed instructions

Step 1: Gather requirements

Before starting, gather the following information from the user:

  • Component name: the short name (e.g., trade for ores.trade).
  • Full name: always ores.COMPONENT (e.g., ores.trade).
  • Brief: a one-line description of the component.
  • Description: a longer description of the component's purpose.

Component names must follow the convention ores.COMPONENT where COMPONENT is all lower case and ideally just one word (though exceptions exist, e.g. ores.http.server).

Step 2: Create the component model file

Create a JSON model file at projects/ores.codegen/models/COMPONENT/ores_COMPONENT_component.json: 

{
  "component": {
    "name": "COMPONENT",
    "full_name": "ores.COMPONENT",
    "brief": "One-line description",
    "description": "Longer description of the component's purpose and responsibilities."
  }
}

For example, for ores.trade: 

{
  "component": {
    "name": "trade",
    "full_name": "ores.trade",
    "brief": "Trade domain component",
    "description": "Provides domain types, repositories, services and protocol support for trade management."
  }
}

Step 3: Run the code generator

From the projects/ores.codegen directory, run: 

./run_generator.sh models/COMPONENT/ores_COMPONENT_component.json --profile component

This generates the complete project scaffold under projects/ores.COMPONENT/:

Generated file Description
CMakeLists.txt Root CMake file with subdirectories
src/CMakeLists.txt Library build configuration
tests/CMakeLists.txt Test binary configuration
modeling/CMakeLists.txt PlantUML diagram target
include/ores.COMPONENT/ores.COMPONENT.hpp Namespace documentation header
include/ores.COMPONENT/domain/stub.hpp Stub domain type
src/domain/stub.cpp Stub implementation
tests/main.cpp Catch2 test main with listeners
tests/stub_tests.cpp Stub test case

Step 4: Register in projects/CMakeLists.txt

Add the new component to projects/CMakeLists.txt. Insert it in logical order, typically after its nearest dependency (e.g., after ores.refdata for domain components): 

add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/ores.refdata)
add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/ores.COMPONENT)  # new
add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/ores.assets)

Step 5: Add PlantUML diagram stub

The code generator does not yet produce the PlantUML diagram content. Manually create projects/ores.COMPONENT/modeling/ores.COMPONENT.puml: 

' -*- mode: plantuml; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
'
' Copyright (C) 2026 Marco Craveiro <marco.craveiro@gmail.com>
'
' This program is free software; you can redistribute it and/or modify it under
' the terms of the GNU General Public License as published by the Free Software
' Foundation; either version 3 of the License, or (at your option) any later
' version.
'
' This program is distributed in the hope that it will be useful, but WITHOUT
' ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
' FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
'
' You should have received a copy of the GNU General Public License along with
' this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
' Street, Fifth Floor, Boston, MA 02110-1301, USA.
'
@startuml

title ores.COMPONENT Component

set namespaceSeparator ::

namespace ores #F2F2F2 {
    namespace COMPONENT #F2F2F2 {
        ' Domain types to be added.
    }
}

@enduml

Step 6: Build and test

Using the CMake Runner Skill:

  1. Build and run the new component's tests: 

    cmake --build --preset linux-clang-debug-ninja --target ores.COMPONENT.tests
  2. Run the tests and confirm the stub test passes.

  3. Commit all your changes: 

    [COMPONENT] Add ores.COMPONENT component scaffold

Reference: Component structure

Component parts

Standard components are made up of the following well-known parts (directories):

Part name Description
include Contains the C++ header files.
modeling Contains the PlantUML source and PNG for diagrams.
src Contains the C++ implementation files.
tests Contains the Catch2 tests for the component.

Facets

Within include and src, code is organised into facets:

Facet name Description
domain C++ domain types (POCOs) and associated services (JSON, table I/O, etc.)
generators C++ generators for domain types, used in testing and production.
messaging Network messaging: requests, responses, handlers, protocol types.
repository Database support via sqlgen: repositories, entities, mappers.
eventing Event-related classes.
service Standalone types with domain operations that do not fit into a domain type.
app Executable infrastructure: hosting, startup, etc.
config Top-level configuration; command-line parser for executable components.
net Network utilities: client/server infrastructure, network interface info.
orexml ORE (Open Source Risk Engine) import/export support.
csv CSV import/export support.

CMake dependency visibility

When customising src/CMakeLists.txt dependencies, use the correct visibility:

  • PUBLIC: dependency headers exposed in component's public headers; consumers also link this dependency.
  • PRIVATE: dependency only used in .cpp files; consumers do not see it.
  • INTERFACE: expose a dependency to consumers without linking it directly (use to avoid duplicate library warnings on macOS).

Common transitive dependencies (do not add these explicitly):

  • reflectcpp comes from ores.platform.lib (PUBLIC via ores.utility.lib)
  • Boost::program_options comes from ores.telemetry.lib (PUBLIC)

Component model documentation

Once the scaffold is working, document the component's architecture using the Component Model Creator skill. This produces:

  • modeling/ores.COMPONENT.org — Component architecture documentation
  • modeling/ores.COMPONENT.puml — Refined class diagram
  • modeling/ores.COMPONENT.png — Generated diagram image

Emacs 29.1 (Org mode 9.6.6)