> For the complete documentation index, see [llms.txt](https://docs.catalyx.solutions/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catalyx.solutions/catalyx-package-manager/technical-overview.md).

# Technical Overview

This page describes how CPM works under the hood — what components make it up, how they interact, and the key design principles behind the system. It is intended for technically-minded readers who want to understand the platform without diving into source code.

***

## Architecture Overview

CPM is a distributed application built on top of the **Canton Network**. Rather than relying on a centralised database to store the source of truth, it uses the **Canton Ledger** as its primary record of state. This means all core actions — registering a package, granting access, approving a publish request — are recorded as smart contract transactions on the ledger, visible and verifiable by the relevant parties.

The system has two main parts: a **backend service** that runs on IntellectEU's infrastructure, and a **web frontend** that runs entirely in the user's browser.

<details>

<summary>Component Overview</summary>

| Component               | Description                                                                                                                                                            |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Listing Service**     | The core backend. A Kotlin/Spring Boot application that connects to the Canton Ledger, manages package state, handles artifact storage, and sends email notifications. |
| **Canton Ledger**       | The source of truth for all CPM actions. Package registrations, publish requests, access grants, and tenant onboarding are all recorded as DAML smart contracts.       |
| **JFrog Artifactory**   | Managed artifact storage hosted by IntellectEU. Used to store DAR files for packages that choose internal hosting.                                                     |
| **DAML Contracts**      | Smart contracts (written in DAML) that model the CPM domain: packages, versions, access requests, tenant info, and subscriptions.                                      |
| **Web Frontend**        | The browser-based user interface. Communicates directly with the user's Canton node for authentication — no credentials pass through IntellectEU's servers.            |
| **Email (SMTP)**        | Used to send notifications to subscribers when packages are published, updated, or deleted, or when access is granted or revoked.                                      |
| **Splice / Scan Proxy** | An integration point with the broader Canton Network. Used to resolve Canton Network metadata such as DSO party IDs and mining round information.                      |

</details>

***

## The Listing Service

The Listing Service is the heart of CPM. It is a **Kotlin application built on Spring Boot** that runs continuously, keeping CPM's internal state in sync with the Canton Ledger.

On startup, it reads the current **Active Contract Set (ACS)** from the ledger — a snapshot of all currently active DAML contracts — and builds an in-memory database from them. It then subscribes to a live transaction stream, processing each new event as it arrives. This means CPM's internal state always reflects what is on-chain.

The service is responsible for:

* **Validating and approving requests** — when a user submits a package creation or publish request via the frontend, this creates a DAML contract on the ledger. The Listing Service detects it, validates the request (checks for duplicates, invalid names, missing fields, etc.), and either approves or rejects it by exercising a choice on the contract.
* **Managing artifact storage** — when a DAR file is uploaded, the service handles routing it to Artifactory and generating short-lived signed download links when a download is requested.
* **Sending notifications** — when package versions are published, deleted, or access is changed, the service identifies subscribed parties and dispatches email notifications.
* **Maintaining tenant info** — company registration details (submitted during onboarding) are stored as `TenantInfo` contracts on the ledger and kept in sync by the service.

{% hint style="info" %}
The Listing Service authenticates with the Canton Ledger using its own service identity (via OIDC client credentials), completely separate from end-user authentication. End users log in through their own identity provider — the Listing Service never sees user credentials.
{% endhint %}

***

## DAML Smart Contracts

All meaningful state in CPM is modelled as **DAML smart contracts** on the Canton Ledger. The key contract types are:

* **`DarPackage`** — represents a registered package. Created when a publisher's `DarPackageCreateRequest` is approved.
* **`DarPackageVersion`** — represents a specific published version of a package, including its metadata, hash, and hosting details.
* **`DarPackagePublishRequest`** — submitted by a publisher when they want to publish a new version. Approved by the Listing Service after validation.
* **`DarPackageAccess` / `DarPackageAccessRequest`** — model private package access. A party requests access; the publisher approves or rejects it.
* **`DarPackagePrivateService`** — marks a package as private and tracks which parties have been granted access.
* **`Subscription`** — records that a party wants to receive email notifications for a package.
* **`TenantInfo`** — stores the registration details submitted by a company during onboarding (company name, Canton party ID, email, OIDC details).

Using the ledger for this means all state changes are **auditable, tamper-evident, and shared only with the relevant parties** — consistent with Canton Network's privacy model.

***

## Artifact Storage

DAR files can be hosted in two ways:

{% columns %}
{% column %}
**Managed (IntellectEU Artifactory)**

The publisher uploads the DAR file through the CPM UI. The Listing Service stores it in IntellectEU's JFrog Artifactory instance. When a download is requested, the service generates a **short-lived signed URL** (valid for a few minutes) that the user's browser fetches directly from Artifactory. Permissions are checked before the link is issued — private packages are only accessible to authorised parties.
{% endcolumn %}

{% column %}
**External (Publisher-hosted)**

The publisher provides a URL pointing to a file they host themselves. This is only supported for **public packages** — private packages must use managed hosting so that CPM can enforce access controls.
{% endcolumn %}
{% endcolumns %}

***

## Authentication Model

CPM uses a **federated, node-centric authentication model**. There are no CPM-managed user accounts.

When a company registers, they provide their own **OIDC issuer URL and client ID**. These details are stored in the `TenantInfo` contract on the ledger. When a user from that company logs in, CPM looks up their company's OIDC configuration and redirects them to their own identity provider — the login happens entirely outside of CPM.

The Listing Service itself authenticates with the Canton Ledger using its own dedicated service account (via OIDC client credentials flow), keeping operator access separate from end-user access.

{% hint style="success" %}
No user credentials ever pass through IntellectEU's servers. The CPM frontend is a browser application — it communicates directly with the user's Canton node for node-level interactions. This was a deliberate design goal.
{% endhint %}

***

## Notification System

CPM sends email notifications via SMTP when certain ledger events occur. The Listing Service detects these events from the transaction stream and enqueues notifications for affected subscribers.

Events that trigger notifications include:

* A new version of a subscribed package is published
* A subscribed package version is deleted
* An entire subscribed package is deleted
* Access to a private package is granted or revoked

Notifications are sent to the email address recorded in the recipient's `TenantInfo` contract on the ledger.

***

## Canton Network Integration

CPM integrates with the broader Canton Network through a **Splice Validator Scan Proxy** — an API endpoint exposed by the Canton validator node. This is used to resolve network-level information such as the DSO party ID and open mining round data, which CPM uses when submitting certain ledger transactions.

This integration means CPM is aware of the Canton Network it is deployed on, rather than operating in isolation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.catalyx.solutions/catalyx-package-manager/technical-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.