Catalogs and Repositories

Overview

OctoMesh distinguishes between Catalogs and Repositories for managing Construction Kit Model Libraries:

• Catalog: A file-based storage system that provides various Construction Kit Model Libraries in multiple versions. Catalogs serve as the source from which libraries can be imported.
• Repository: A database-stored (e.g., MongoDB) collection of Construction Kit Model Libraries that work together. A repository contains exactly one version of each library, and all libraries must be logically compatible with each other.

Catalogs

Catalogs are file-based storage systems that centrally provide Construction Kit Model Libraries for OctoMesh. They can contain multiple versions of the same library, allowing you to choose which version to import into a repository.

Catalog Types

File System Catalog

Local directory structure containing Construction Kit library definitions. Suitable for development environments or on-premise deployments. During builds it is also the publish target and resolution source for interdependent Construction Kit models that are compiled in the same run.

The catalog root is resolved in this order:

1. OctoLocalCatalogRootPath MSBuild property (or the transient -lcr option of octo-ckc) — when set, both the catalog content and its cache live under this root.
2. Repository convention: when the repository defines OctoRepoRootPath (all meshmakers repositories do, via Directory.Build.props), the catalog defaults to <repository parent>/.octo/local-catalog — one isolated catalog per branch/workspace checkout, following the same convention as the ../nuget package folder.
3. Fallback: ~/.octo/local-catalog (user profile) when neither is available, e.g. for consumers of the MsBuildTasks package without the meshmakers props convention.

On CI agents, the build pipelines set OctoLocalCatalogRootPath to $(Agent.TempDirectory)/octo-local-catalog (via the shared update-build-number.yml template), so every pipeline run gets a fresh, isolated catalog and feature-branch builds can never leak unpublished models into other builds.

Git Catalog

GitHub or other Git-based sources for version-controlled, distributed access to Construction Kit libraries. Enables collaboration and change tracking across teams.

By default, the meshmakers Git catalog is configured, available at meshmakers.github.io.

System Libraries

Core Construction Kit libraries are compiled directly into OctoMesh services' source code. These system libraries are automatically available without external catalog configuration and provide fundamental data types and patterns required by the platform.

Catalog Structure

Construction Kit libraries are stored in validated form within catalogs. The validated form contains all types, attributes, records, enums, and associations. Catalogs can hold multiple versions of the same library (e.g., Industry.Energy-1.0.0, Industry.Energy-1.1.0, Industry.Energy-2.0.0).

Catalog Roots: ck-models/v2 and ck-models/v3

Catalogs store compiled models under two roots. CK language 1 models with exact pins go to ck-models/v2/; models that carry a minEngineVersion — ckLanguage: 2 models, range-retaining models and any model compiled against such a dependency — go to ck-models/v3/. Engines before CK v2 read only ck-models/v2/; CK v2 engines read both. A model version lives in exactly one root.

Operating rule: shared catalogs

Do not publish a ckLanguage: 2 or range-retaining version of a base model (for example System or Basic) into a shared catalog — the GitHub catalogs (octo-ckc) or any catalog other teams compile against — until every service that consumes that catalog runs the CK v2 engine. After one such publish every dependent compiled against the catalog inherits the base's minEngineVersion and is published under ck-models/v3/, which older engines do not read. See CK language 2.

Dependency Resolution

Catalogs are searched to resolve dependencies when importing libraries. The search order is:

1. Embedded System Construction Kits - Built-in libraries compiled into OctoMesh services
2. Local File System Catalog - User-specific or project-specific libraries
3. GitHub Catalog - Shared libraries from the configured Git source

Managing Catalogs with octo-ckc

The octo-ckc tool provides commands for working with catalogs:

List Available Catalogs

octo-ckc -c GetCatalogs

Lists all known Construction Kit catalogs with their names and descriptions.

Publish to Catalog

octo-ckc -c Publish -f <file> [-c <catalog>] [-r]

Parameter	Description
-f, --file	Path of the compiled construction kit model file (required)
-c, --catalog	Name of the catalog (default: LocalFileSystemCatalog)
-r, --replace	Replace existing model if it already exists
-lcr, --localCatalogRoot	Root path of the local file system catalog for this invocation only (not persisted)

Get Model from Catalog

octo-ckc -c Get -c <catalog> -n <name> [-f <file>]

Parameter	Description
-c, --catalog	Name of the catalog (required)
-n, --name	Name of the construction kit model to retrieve (required)
-f, --file	Optional output file path to store the model

Find Model in Catalogs

octo-ckc -c Find -id <modelId>

Parameter	Description
-id, --modelId	Model ID to find, including version ranges (required)

Searches all known catalogs for the specified model.

Restore Dependencies

octo-ckc -c Restore -f <file> -o <outputPath> [-c <cache>]

Parameter	Description
-f, --file	Path of the model configuration file (required)
-o, --outputPath	Output path for compiled construction kits (required)
-c, --cache	Optional cache file path for dependent models
-lcr, --localCatalogRoot	Root path of the local file system catalog for this invocation only (not persisted)

Restores all construction kit dependencies based on a model configuration file.

Refresh Catalog Cache

octo-ckc -c RefreshCatalogCache [-c <catalog>]

Parameter	Description
-c, --catalog	Name of the catalog (default: LocalFileSystemCatalog)

Refreshes the cache for a specific catalog by reloading from disk or fetching from remote sources.

octo-ckc -c RefreshAllCatalogCaches

Refreshes the cache for all known catalogs.

Repositories

A Repository is a coherent set of Construction Kit Model Libraries stored in a database (such as MongoDB). Unlike catalogs, repositories enforce strict version compatibility:

• Single Version Rule: A repository contains exactly one version of each Model Library
• Version Compatibility: All libraries in a repository must be logically compatible with each other
• Dependency Consistency: Library dependencies must be satisfied within the same repository

Repository Characteristics

Aspect	Description
Storage	Database (e.g., MongoDB)
Versions per Library	Exactly one
Compatibility	All libraries must work together
Purpose	Runtime data model for OctoMesh instances

Importing Libraries

When importing a Construction Kit Model Library from a catalog into a repository:

1. The system checks if the library's dependencies are satisfied
2. Version compatibility with existing libraries is verified
3. If a different version of the library already exists, it must be upgraded or the import fails
4. All dependent libraries must have compatible versions

Example

A repository might contain:

Repository "production"
├── System-1.0.3
├── Basic-1.0.0 (depends on System-1.0.3)
├── Industry.Energy-1.0.0 (depends on Basic-1.0.0)
└── EnergyCommunity-1.0.0 (depends on Industry.Energy-1.0.0, Basic-1.0.0)

All libraries form a coherent set where dependencies are satisfied and versions are compatible.

Comparison

Aspect	Catalog	Repository
Storage	File system or GitHub	Database (e.g., MongoDB)
Multiple versions	Yes	No (one per library)
Purpose	Library distribution	Runtime data model
Version constraints	None	Strict compatibility
Dependencies	Can be unresolved	Must be fully resolved