industry-core-hub

Contributors Stargazers Apache 2.0 License CC-BY-4.0 Latest Release

Tractus-X SDK

Industry Core Hub Logo

Industry Core Hub

A lightweight open-source data provision and consumption orchestrator for the Catena-X dataspace.
It helps teams go from onboarding to first data exchange in days, not months.

Table of Contents

What is the Industry Core Hub?

The Industry Core Hub (IC-Hub) is an open-source reference implementation of the Eclipse Tractus-X Industry Core KIT. It acts as a middleware orchestrator that sits between your business applications/backend & legacy systems and the underlying Eclipse Tractus-X dataspace infrastructure, eliminating the need for deep expertise in each individual component.

The Problem It Solves

Adopting dataspace technologies from Eclipse Tractus-X (used for example in the Catena-X dataspace by service providers) typically requires integrating multiple complex components:

Setting all of this up correctly — with the right policies, asset registrations, and data contracts — is a significant engineering effort that can take weeks or months, and requires specialist knowledge most companies don’t have in-house.

The Solution

The IC-Hub abstracts all of this complexity behind a clean, unified API and an intuitive user interface. You interact with one system; the IC-Hub orchestrates everything else for you:

This dramatically reduces the onboarding effort for SMEs and use case developers, turning weeks of integration work into a matter of days.

Who is it for?

Audience Benefit
Data Providers Register automotive parts, create digital twins, attach submodels, and share data with supply chain partners with minimal effort
Data Consumers Search, discover, and retrieve digital twin data from business partners without dealing with EDC negotiation complexity
Use Case Developers Build Catena-X use cases (e.g., DPP, Traceability) on top of a stable, pre-integrated foundation in days rather than months
SMEs Adopt the Catena-X dataspace with minimal IT investment and infrastructure knowledge
KIT Providers Extend the IC-Hub with custom add-on views and features for specific use cases, distributable via the Catena-X marketplace

Key Capabilities

Data Provisioning

Data Consumption

Platform & Operations

Architecture

High-Level System Context

The IC-Hub acts as the central orchestration layer between your applications and the Catena-X dataspace components. Instead of integrating with each component individually, your application talks only to the IC-Hub.

%%{init: {"flowchart": {"subGraphTitleMargin": {"top": 24, "bottom": 12, "defaultRenderer": "elk"}}}}%%
flowchart TB
    subgraph "Your Organization"
        BACK["Backend<br/>Legacy System"]
        PIP["Integration Pipeline"]
        APP["Business Application UI"]
        ICH["Industry Core Hub"]
        DB[("PostgreSQL Metadata DB")]
        KC["Keycloak IAM"]
    end

    subgraph "Tractus&#8209;X&nbsp;Dataspace&nbsp;Components<br/>(Self&#8209;hosted&nbsp;or&nbsp;as&nbsp;a&nbsp;Service)"
        direction TB
        %% This creates an invisible spacer to push real nodes down
        spacer1[" "]
        spacer1[" "]
        spacer1[" "]
        style spacer1 fill:transparent,stroke:none,color:transparent,height:20px
        EDC["EDC"]
        DTR["DTR"]
        SS["Submodel Server"]
    end

    subgraph "Tractus&#8209;X&nbsp;Discovery&nbsp;Services"
        direction TB
        %% This creates an invisible spacer to push real nodes down
        spacer1[" "]
        style spacer1 fill:transparent,stroke:none,color:transparent,height:20px
        DF["Discovery Finder"]
        BPND["BPN Discovery"]
        EDCD["EDC Discovery"]
    end

    subgraph "Business Partner"
        direction TB
        %% This creates an invisible spacer to push real nodes down
        spacer1[" "]
        style spacer1 fill:transparent,stroke:none,color:transparent,height:20px
        PEDC["EDC"]
        PDTR["DTR"]
    end

    APP -- "REST API / UI" --> ICH
    ICH --> DB
    ICH -- "Asset & Policy<br/>Registration" --> EDC
    ICH -- "AAS Twin<br/>Registration" --> DTR
    ICH -- "Submodel Read/Write" --> SS
    ICH -- "Endpoint Discovery" --> DF
    DF --> BPND
    DF --> EDCD
    BACK --> PIP
    PIP -- "REST API" --> ICH
    ICH -- "Auth" --> KC
    EDC <-- "Data Contract<br/>Negotiation" --> PEDC
    PEDC --> PDTR

The architecture follows a layered abstraction approach — each layer hides the complexity of the layer below it, so use-case developers only interact with high-level business concepts.

%%{init: {"flowchart": {"subGraphTitleMargin": {"top": 24, "bottom": 12}}}}%%
graph TB
    subgraph L4["Layer 4 — Use Case Add-ons"]
        UC1["DPP Add-on"]
        UC2["Certificate Management Add-on"]
        UC3["PCF Add-on"]
    end
    subgraph L3["Layer 3 — Industry Core Hub"]
        ICH["IC-Hub API & UI<br/>(Orchestration)"]
    end
    subgraph L2["Layer 2 — Tractus-X SDK"]
        SDK["tractusx-sdk<br/>(EDC & DTR client libraries)"]
    end
    subgraph L1["Layer 1 — Dataspace Infra"]
        EDC["EDC"]
        DTR["DTR"]
        DS["Discovery Services"]
        SS["Submodel Services"]
    end

    L4 --> L3
    L3 --> L2
    L2 --> L1

For the full architecture documentation, see the Architecture Guide.

Building Blocks

The IC-Hub integrates with these core Catena-X / Tractus-X components:

Component Role
Tractus-X EDC Sovereign data exchange via standardized data contracts
Digital Twin Registry (DTR) AAS-compliant digital twin registration and discovery
Submodel Server Storage and serving of aspect model data
Discovery Finder Locates BPN Discovery endpoints for a given asset type
BPN Discovery Maps manufacturer part IDs to Business Partner Numbers
Portal IAM / Keycloak Identity and access management

Backend

The backend exposes a RESTful API (documented via Swagger/OpenAPI) that orchestrates all interactions with the Catena-X components. It is built with Python and FastAPI, uses SQLModel/PostgreSQL for metadata persistence, and integrates with the Tractus-X SDK.

%%{init: {"flowchart": {"subGraphTitleMargin": {"top": 24, "bottom": 12}}}}%%
graph TB
    CLIENT["Frontend / API Client"]
    JOBS["Background Jobs<br/>(asset_sync_job)"]

    subgraph CTRL["Controllers — controllers/fastapi/routers/"]
        R_PROV["Provider Routers<br/>/part-management<br/>/twin-management<br/>/submodel-dispatcher<br/>/share<br/>/partner-management"]
        R_CONS["Consumer Routers<br/>/discover<br/>/connection"]
        R_AUTH["Authentication Router"]
        R_ADDON["Add-on Routers<br/>/addons/ecopass-kit"]
    end

    subgraph SVC["Services — services/provider/"]
        PS["PartManagementService"]
        TMS["TwinManagementService"]
        SMS["SubmodelDispatcherService"]
        SHS["SharingService"]
        PMS["PartnerManagementService"]
    end

    subgraph MGR["Managers — managers/"]
        subgraph PROV_MGR["enablement_services/provider/"]
            CPM["ConnectorProviderManager<br/>(EDC asset & policy registration)"]
            DPM["DtrProviderManager<br/>(AAS Shell registration)"]
        end
        subgraph CONS_MGR["enablement_services/consumer/"]
            CCM["ConsumerConnectorManager<br/>(EDC contract negotiation)"]
            DCM["DtrConsumerManager<br/>(AAS Shell discovery)"]
        end
        SVM["SubmodelServiceManager<br/>(FileSystem / HTTP adapter)"]
        SDG["SubmodelDocumentGenerator<br/>(aspect model documents)"]
        DB_M["RepositoryManager<br/>(SQLModel ORM)"]
        ADDON_MGR["addons_service/ecopass_kit<br/>(EcoPass KIT managers)"]
    end

    subgraph MODELS["Models — models/"]
        SVC_M["services/<br/>Pydantic DTOs (provider & consumer)"]
        DB_MDL["metadata_database/<br/>SQLModel ORM models (provider & consumer)"]
    end

    subgraph EXT["External Systems"]
        EDC["EDC Connector<br/>(Tractus-X SDK)"]
        DTR["Digital Twin Registry<br/>(Tractus-X SDK)"]
        SS["Submodel Server<br/>(FileSystem or HTTP)"]
        PG[("PostgreSQL")]
    end

    CLIENT --> R_PROV & R_CONS & R_AUTH & R_ADDON
    JOBS --> CPM & DPM & DB_M

    %% Provider path: routers → services → managers
    R_PROV --> PS & TMS & SMS & SHS & PMS
    PS & TMS & SMS & SHS & PMS --> CPM & DPM & SVM & SDG & DB_M

    %% Consumer path: routers call managers directly (no services/consumer/ layer)
    R_CONS --> CCM & DCM

    %% Add-on path: routers call addon managers directly (no services layer)
    R_ADDON --> ADDON_MGR
    ADDON_MGR --> SVM & DB_M

    %% Background jobs also call managers directly (no services layer)
    %% (see jobs/asset_sync_job.py)

    %% Models used across layers
    SVC_M -. "used by" .-> SVC
    DB_MDL -. "used by" .-> MGR

    CPM & DPM --> EDC & DTR
    CCM & DCM --> EDC & DTR
    SVM --> SS
    DB_M --> PG

For better readability, the backend architecture can be split into focused diagrams.

Focused View — Controllers and Their External Relations

%%{init: {"flowchart": {"subGraphTitleMargin": {"top": 24, "bottom": 12}}}}%%
flowchart LR
    CLIENT["Frontend / API Client"]

    subgraph CTRL_FOCUS["Controllers — controllers/fastapi/routers/"]
        R_PROV_F["Provider Routers"]
        R_CONS_F["Consumer Routers"]
        R_AUTH_F["Authentication Router"]
        R_ADDON_F["Add-on Routers"]
    end

    subgraph SVC_FOCUS["Services — services/provider/"]
        SVC_PROVIDER_F["Provider Services"]
    end

    subgraph MGR_FOCUS["Managers — managers/"]
        MGR_CONS_F["Consumer Managers"]
        MGR_ADDON_F["Add-on Managers"]
    end

    CLIENT --> R_PROV_F & R_CONS_F & R_AUTH_F & R_ADDON_F
    R_PROV_F --> SVC_PROVIDER_F
    R_CONS_F --> MGR_CONS_F
    R_ADDON_F --> MGR_ADDON_F

The backend is organized into the following packages:

Note: There is currently no services/consumer/ layer — consumer routers call the consumer managers directly. Similarly, add-on routers bypass the provider services and call their own KIT-specific managers. Background jobs (jobs/) also call managers directly, without going through any service layer.

See the API Reference and API Collection (Bruno) for details.

Frontend

The frontend is a React/TypeScript Single Page Application built with Material-UI (MUI) components. It provides an intuitive dashboard for managing digital twins, submodels, and EDC assets.

%%{init: {"flowchart": {"subGraphTitleMargin": {"top": 24, "bottom": 12}}}}%%
graph TB
    subgraph "React SPA (ichub-frontend)"
        subgraph "Feature Modules"
            ICK["industry-core-kit<br/>(Catalog Parts, Serialized Parts, Twins, Submodels)"]
            EPK["eco-pass-kit<br/>(Digital Product Passport)"]
            BPK["business-partner-kit<br/>(Partner Discovery)"]
        end

        subgraph "Shared Infrastructure"
            CTX["React Contexts<br/>(Auth, Config, Notifications)"]
            SVC["Services<br/>(HttpClient, AuthService, EnvironmentService)"]
            CMP["Common Components<br/>(Layout, Navigation, Dialogs, Forms)"]
        end

        subgraph "Routing"
            RT["React Router v7+<br/>FeatureRouteGuard<br/>(role-based access)"]
        end
    end

    subgraph "Auth"
        KC["Keycloak"]
    end

    subgraph "Backend"
        API["IC-Hub REST API<br/>(FastAPI)"]
    end

    ICK & EPK & BPK --> CTX & SVC & CMP
    RT --> ICK & EPK & BPK
    SVC -- "Axios HTTP" --> API
    CTX -- "OAuth2 / OIDC" --> KC

Data Provision Flow

The following sequence diagrams show how the IC-Hub orchestrates the two main data provision operations.

Step 1 — Register a Catalog Part (metadata only, stored in PostgreSQL):

sequenceDiagram
    actor User
    participant UI as IC-Hub UI
    participant API as IC-Hub API
    participant SVC as PartManagementService
    participant DB as PostgreSQL

    User->>UI: Fill in part details
    UI->>API: POST /provider/part-management/catalog-part
    API->>SVC: create_catalog_part()
    SVC->>DB: INSERT CatalogPart record
    DB-->>SVC: OK
    SVC-->>API: CatalogPartRead
    API-->>UI: 201 Created
    UI-->>User: Part created

Step 2 — Share a Catalog Part (registers twin in DTR and creates EDC asset/policy):

sequenceDiagram
    actor User
    participant UI as IC-Hub UI
    participant API as IC-Hub API
    participant SHS as SharingService
    participant SDG as SubmodelDocumentGenerator
    participant SVM as SubmodelServiceManager
    participant DTR as DtrProviderManager
    participant EDC as ConnectorProviderManager
    participant DB as PostgreSQL

    User->>UI: Click "Share" for a catalog part
    UI->>API: POST /provider/share/catalog-part
    API->>SHS: share_catalog_part()
    SHS->>DB: Load CatalogPart + BusinessPartner
    DB-->>SHS: Part data
    SHS->>SDG: generate_submodel_document()
    SDG-->>SHS: Aspect model JSON (e.g. PartTypeInformation)
    SHS->>SVM: store_submodel()
    SVM-->>SHS: Submodel storage URL
    SHS->>DTR: create_shell() + add_submodel_descriptor()
    DTR-->>SHS: AAS Shell ID
    SHS->>EDC: create_asset() + create_policy() + create_contract()
    EDC-->>SHS: Asset & Contract IDs
    SHS->>DB: UPDATE Twin / TwinAspect records
    DB-->>SHS: OK
    SHS-->>API: SharedPartBase
    API-->>UI: 200 OK
    UI-->>User: Part shared (twin + EDC asset registered)

Technology Stack

Layer Technology
Backend Python ≥ 3.12, FastAPI, SQLModel, Pydantic
Frontend React 18, TypeScript, Material-UI v6, Vite
Database PostgreSQL
Auth Keycloak (OAuth2 / OpenID Connect)
Deployment Docker, Helm Charts (Kubernetes)
SDK Tractus-X SDK

Catena-X Standards

The IC-Hub is a reference implementation for the following Catena-X standards:

Standard Name
CX-0001 EDC Discovery API
CX-0002 Digital Twins in Catena-X
CX-0003 SAMM Aspect Meta Model
CX-0005 Item Relationship Service
CX-0007 Minimal Data Provider Service
CX-0018 Dataspace Connectivity
CX-0030 Aspect Model: BoM As Specified
CX-0032 Data Model: Part As Specified
CX-0053 Discovery Finder & BPN Discovery Service
CX-0126 Industry Core: Part Type
CX-0127 Industry Core: Part Instance

Integrated Services

The IC-Hub orchestrates the following Tractus-X / Catena-X services:

Core Dataspace Components

Discovery Services

Identity & Access

Roadmap

Feb 2025        R25.06             R25.09          R25.12           2026+
Kickoff          MVP                Stable          R25.12         Beyond
|-------------->|----------------->|-------------->|------------>|---------->|
              Data Provision    Data Consumption   IC-HUB +       KIT Use
               Orchestrator      Orchestrator     First Use Case   Cases &
                                                  (e.g., DPP)   Extensions

See the full Changelog for details on released versions.

Installation

Deploy the IC-Hub in a Kubernetes cluster (via Helm) or run it locally for development.

Quick Start (Local Development)

Database (PostgreSQL + pgAdmin)

A Docker Compose file is provided to spin up a local PostgreSQL instance and pgAdmin (in order to develop the backend in local)

cd deployment/local/docker-compose/
docker compose up -d
# PostgreSQL: localhost:5432 (user/password, db: ichub)
# pgAdmin:    http://localhost:5050 (admin@admin.com / admin)

Backend

cd ichub-backend/
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# Edit ichub-backend/config/configuration.yml with your settings
python -m main --host 0.0.0.0 --port 8000
# Swagger UI: http://localhost:8000/docs

Frontend

cd ichub-frontend/
npm install
# Set ICHUB_BACKEND_URL in ichub-frontend/index.html
npm run dev
# App: http://localhost:5173

Kubernetes / Helm

helm repo add tractusx-dev https://eclipse-tractusx.github.io/
helm repo update
helm install ichub -f your-values.yaml tractusx-dev/industry-core-hub

Local Umbrella (Tractus-X Components)

To develop and test against real Catena-X components locally (EDC, DTR, Discovery Services, Portal, etc.), deploy the minimal Tractus-X Umbrella chart on a local Kubernetes cluster (e.g., Minikube):

# Prerequisites: kubectl, Helm v3.8+, Minikube (or Docker Desktop with K8s enabled)
minikube start --cpus=4 --memory=8Gb

helm repo add tractusx-dev https://eclipse-tractusx.github.io/charts/dev
helm repo update tractusx-dev
helm install -f docs/umbrella/minimal-values.yaml umbrella tractusx-dev/umbrella \
  --namespace umbrella --version v2.6.0 --create-namespace

For the full step-by-step guide — including cluster setup, ingress configuration, and host mappings — see the Umbrella Deployment Guide.

For the complete installation guide — including prerequisites, configuration reference, and production deployment — see the Installation Guide.

Documentation

Document Description
Installation Guide Step-by-step deployment for Kubernetes and local development
Architecture Guide Full arc42-based architecture documentation
Introduction & Goals Business context, quality goals, and stakeholders
System Scope & Context System boundaries and external interfaces
API Reference (OpenAPI) Full REST API specification
API Collection (Bruno) Ready-to-use API request collection
API Collection (Postman) Ready-to-use Postman collection
Submodel Creator Guide How to create and publish submodels via the UI
Umbrella Deployment Guide Set up a full local Catena-X environment for testing
Database Schema Metadata database structure
Migration Guide Upgrade and migration instructions
Admin Guide Operational and administration topics
Contributing Guide How to contribute to the project
Security Policy Vulnerability reporting and security guidelines
Changelog Release history and change log

KIT Add-on Extensions

The IC-Hub is designed to be extended. It provides a reusable orchestration foundation for multiple use-case-specific KIT Add-ons. Each add-on can:

This means solution providers can build and sell ready-to-use KIT toolboxes on top of the open-source IC-Hub core.

Available and Planned Add-ons

KIT Add-on Status Description
Industry Core KIT Available Core data provisioning and consumption — catalog part management, part discovery, digital twin registration, and serialized part handling
EcoPass KIT Available Digital Product Passport (DPP) provision and consumption — create, publish, and visualize product passports
Business Partner KIT Available Business partner management — manage and resolve partner identities across the dataspace
Certificate Management KIT Planned (next) Company certificate management — publish and exchange official company certificates across the dataspace
PCF Exchange KIT Planned (next) Product Carbon Footprint exchange — share and consume PCF data across the supply chain
Traceability KIT Planned Supply chain traceability — track parts across the value chain with BoM lifecycle visibility
Quality KIT Planned Quality management — exchange quality-related data (alerts, notifications, investigations) across partners
Demand & Capacity KIT Planned Demand and capacity management — collaborative planning between suppliers and customers

Want to build your own KIT add-on? The IC-Hub’s extensible architecture makes it straightforward to contribute new add-ons. See the Contributing Guide to get started.

How to Get Involved

Reporting a Bug or Sharing an Idea

Found a bug? Create a new issue on our GitHub Issues page. Before opening a new one, please search existing issues first.

Assign it to yourself to let others know you’re working on it — click the cog next to the Assignees section.

Have an idea? Share it in our Discussions or start a new discussion.

Reporting a Security Issue

Please follow the Security Issue Reporting Guidelines if you discover a security vulnerability or concern. See also our Security Policy.

Licenses

NOTICE

This work is licensed under the CC-BY-4.0.

This site is open source. Improve this page.