# eclipse-tractusx/tractusx-identityhub architecture

> Architecture diagram of the GitHub repository eclipse-tractusx/tractusx-identityhub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eclipse-tractusx/tractusx-identityhub
- Repository: https://github.com/eclipse-tractusx/tractusx-identityhub

## Overview

1. **Repository purpose**
   - This repo packages and deploys the Tractus-X IdentityHub stack as two Java services: **IdentityHub** and **IssuerService**.
   - Both are DCP-oriented identity/credential services built on top of the Eclipse EDC extension model, with production and memory-only deployment variants.

2. **Top-level system split**
   - The architecture is centered on two independent backend runtimes:
     - **`runtimes/identityhub`** and **`runtimes/identityhub-memory`**
     - **`runtimes/issuerservice`** and **`runtimes/issuerservice-memory`**
   - These are the executable service compositions; the rest of the repo mainly provides shared extensions, database migrations, packaging, deployment, and a UI.

3. **IdentityHub runtime responsibilities**
   - IdentityHub acts as the holder-side wallet/wallet-like service.
   - It manages participant contexts, DIDs, key pairs, verifiable credentials, presentation queries, and self-issued token-related flows.
   - It is the service that a dataspace connector talks to during credential presentation flows.

4. **IssuerService runtime responsibilities**
   - IssuerService is the issuer-side service for creating credential definitions, attestations, holders, issuance processes, and credential lifecycle actions such as revocation/suspension/resumption.
   - It is the counterpart in the credential issuance flow and exposes admin and issuance APIs used by IdentityHub and operators.

5. **Shared extension layer**
   - The functional logic is mostly implemented as **EDC service extensions** under `extensions/`.
   - Notable extension groups include:
     - `extensions/store/sql/migrations` for PostgreSQL schema/versioning
     - `extensions/seed/super-user` and `extensions/identityhub/initial-participant` for bootstrapping
     - `extensions/monitor/colored-jdk-monitor` for runtime logging/formatting
   - This indicates a modular, plugin-based backend rather than a single monolithic application.

6. **Persistence boundary**
   - The production variants depend on **PostgreSQL** for durable state.
   - The SQL migrations are organized by domain table set: participant context, key pairs, DID resources, credentials, credential definitions, issuance processes, holders, attestation definitions, STS client, and JTI validation.
   - The memory variants replace these with in-memory stores for demo/testing and do not require the database.

7. **Secret management boundary**
   - The README and deployment structure show **HashiCorp Vault** as the secret store for production deployments.
   - Runtime configs and the API documentation imply that private keys and other sensitive material can be sourced from Vault rather than being generated/stored locally.
   - This is a clear architectural boundary between durable business data in PostgreSQL and secrets in Vault.

8. **API surface and protocol flows**
   - The repo documents several API families in `docs/api/openAPI.yaml` and Bruno collections:
     - **Identity API** for participant contexts, DIDs, key pairs, credentials
     - **Issuance API** for credential requests and issuer metadata
     - **Issuer Admin API** for credential definitions, holders, issuance processes, revocation
     - **DID API**, **STS API**, and **StatusList API**
   - The key protocol flows are:
     - **Issuance flow:** IdentityHub requests credentials from IssuerService via DCP
     - **Presentation flow:** an EDC connector requests verifiable presentations from IdentityHub

9. **Frontend/UI subsystem**
   - The `ui/` directory is a separate **React + TypeScript** application with its own build, tests, and Nginx-based containerization.
   - It provides operator/user screens for participants, credentials, DIDs, key pairs, and search.
   - The UI talks to the backend services over HTTP and is configuration-driven at runtime via environment injection.

10. **Deployment packaging**
   - Deployment is done primarily through **Helm charts**:
     - `charts/tractusx-identityhub`
     - `charts/tractusx-identityhub-memory`
     - `charts/tractusx-issuerservice`
     - `charts/tractusx-issuerservice-memory`
   - Charts include deployment, service, ingress, HPA, logging config, PVCs, and test hooks, which means the repo is meant to produce deployable Kubernetes workloads rather than only libraries.

11. **Local development and Docker composition**
   - `deployment/docker/` contains Docker Compose-based local setups and component-specific configuration files.
   - This includes container wiring for the services plus PostgreSQL initialization scripts, which makes local execution a first-class supported path alongside Kubernetes.

12. **Operational and release tooling**
   - The `.github/workflows` area is extensive and covers linting, scanning, deployment tests, Helm validation, snapshot publishing, and release automation.
   - This repo is therefore structured not only as source code but as a releaseable product with CI/CD, security scanning, and chart/image publishing.

13. **Testing and verification**
   - End-to-end and API verification assets are stored under `docs/api/bruno`, `tests/deployment`, and `scripts/verify-credential.py`.
   - These artifacts indicate the system is verified through a mix of backend tests, deployment checks, and API flow collections rather than only unit tests.

14. **Main architectural diagram boundaries**
   - If you draw the architecture, the main boxes should be:
     - **IdentityHub runtime**
     - **IssuerService runtime**
     - **PostgreSQL**
     - **Vault**
     - **EDC connector / external dataspace participant**
     - **Operator UI**
   - The critical arrows are:
     - UI → backend APIs
     - IdentityHub ↔ IssuerService for DCP issuance
     - Connector ↔ IdentityHub for presentation
     - Both runtimes → PostgreSQL, and production variants → Vault
     - Deployment/CI → Helm charts, container images, and Kubernetes

Main entry points: [`runtimes/identityhub`](https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/runtimes/identityhub) (IdentityHub), [`runtimes/issuerservice`](https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/runtimes/issuerservice) (IssuerService), [`ui`](https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/ui) (Operator UI), [`.github/workflows`](https://github.com/eclipse-tractusx/tractusx-identityhub/blob/main/.github/workflows) (CI/CD)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Backend runtimes"]
  node_identityhub_rt["IdentityHub<br/>runtime"]
  node_identityhub_mem_rt["IdentityHub memory<br/>runtime"]
  node_issuer_rt["IssuerService<br/>runtime"]
  node_issuer_mem_rt["Issuer memory<br/>runtime"]
end

subgraph group_extensions["Shared extensions"]
  node_identityhub_ext{{"Identity extensions"}}
  node_seed_ext{{"Super-user seed<br/>bootstrap extension"}}
  node_monitor_ext{{"Colored monitor<br/>monitor extension"}}
  node_sql_migrations{{"SQL migrations<br/>postgres migrations"}}
end

subgraph group_delivery["Packaging and deploy"]
  node_helm_charts{{"Helm charts<br/>k8s packaging"}}
  node_docker_compose{{"Docker compose<br/>local deploy"}}
  node_ci_cd{{"CI/CD<br/>release automation<br/>[workflows]"}}
end

subgraph group_ui["Operator UI"]
  node_operator_ui["Operator UI<br/>react app"]
end

subgraph group_docs["API and verification"]
  node_openapi_docs["API docs<br/>api contracts"]
  node_e2e_tests["E2E checks<br/>verification assets"]
end

node_postgres_db[("PostgreSQL<br/>durable store")]
node_vault_store[("Vault<br/>secret store")]
node_connector["EDC connector<br/>external participant"]

node_identityhub_rt -->|"uses schema"| node_sql_migrations
node_issuer_rt -->|"uses schema"| node_sql_migrations
node_sql_migrations -->|"provisions"| node_postgres_db
node_identityhub_rt -->|"reads secrets"| node_vault_store
node_issuer_rt -->|"reads secrets"| node_vault_store
node_identityhub_rt -->|"presentation"| node_connector
node_connector -->|"DCP request"| node_identityhub_rt
node_identityhub_rt -->|"issuance"| node_issuer_rt
node_issuer_rt -->|"offers/metadata"| node_identityhub_rt
node_operator_ui -->|"Identity APIs"| node_identityhub_rt
node_operator_ui -->|"Issuer APIs"| node_issuer_rt
node_identityhub_mem_rt -.->|"same service"| node_identityhub_rt
node_issuer_mem_rt -.->|"same service"| node_issuer_rt
node_identityhub_mem_rt -.->|"dev target"| node_operator_ui
node_issuer_mem_rt -.->|"dev target"| node_operator_ui
node_identityhub_rt -->|"loads extensions"| node_identityhub_ext
node_identityhub_rt -->|"bootstrap"| node_seed_ext
node_issuer_rt -->|"bootstrap"| node_seed_ext
node_identityhub_rt -.->|"logging"| node_monitor_ext
node_issuer_rt -.->|"logging"| node_monitor_ext
node_helm_charts -->|"deploys"| node_identityhub_rt
node_helm_charts -->|"deploys"| node_issuer_rt
node_docker_compose -->|"runs locally"| node_identityhub_mem_rt
node_docker_compose -->|"runs locally"| node_issuer_mem_rt
node_ci_cd -->|"validates/publishes"| node_helm_charts
node_ci_cd -->|"builds"| node_operator_ui
node_ci_cd -->|"builds"| node_identityhub_rt
node_ci_cd -->|"builds"| node_issuer_rt
node_openapi_docs -->|"documents"| node_identityhub_rt
node_e2e_tests -->|"verifies"| node_identityhub_rt
node_e2e_tests -->|"verifies"| node_issuer_rt
node_e2e_tests -.->|"smoke tests"| node_operator_ui

click node_identityhub_rt "https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/runtimes/identityhub"
click node_identityhub_mem_rt "https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/runtimes/identityhub-memory"
click node_issuer_rt "https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/runtimes/issuerservice"
click node_issuer_mem_rt "https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/runtimes/issuerservice-memory"
click node_identityhub_ext "https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/extensions/identityhub/initial-participant"
click node_seed_ext "https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/extensions/seed/super-user"
click node_monitor_ext "https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/extensions/monitor/colored-jdk-monitor"
click node_sql_migrations "https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/extensions/store/sql/migrations"
click node_operator_ui "https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/ui"
click node_helm_charts "https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/charts"
click node_docker_compose "https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/deployment/docker"
click node_ci_cd "https://github.com/eclipse-tractusx/tractusx-identityhub/blob/main/.github/workflows"
click node_openapi_docs "https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/docs/api"
click node_e2e_tests "https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/tests/deployment"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_identityhub_rt,node_identityhub_mem_rt,node_issuer_rt,node_issuer_mem_rt toneBlue
class node_identityhub_ext,node_seed_ext,node_monitor_ext,node_sql_migrations toneAmber
class node_helm_charts,node_docker_compose,node_ci_cd toneMint
class node_operator_ui toneRose
class node_openapi_docs,node_e2e_tests toneIndigo
class node_postgres_db,node_vault_store,node_connector toneNeutral
```

## Components

### Backend runtimes

Executable IdentityHub and IssuerService compositions, including memory variants.

- [IdentityHub](https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/runtimes/identityhub): runtime · Production holder-side runtime for participant contexts, DIDs, keys, credentials, and presentation flows. · `runtimes/identityhub`
- [IdentityHub memory](https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/runtimes/identityhub-memory): runtime · In-memory IdentityHub variant for demo and testing. · `runtimes/identityhub-memory`
- [IssuerService](https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/runtimes/issuerservice): runtime · Production issuer-side runtime for definitions, holders, issuance, and lifecycle actions. · `runtimes/issuerservice`
- [Issuer memory](https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/runtimes/issuerservice-memory): runtime · In-memory IssuerService variant for demo and testing. · `runtimes/issuerservice-memory`

### Shared extensions

Eclipse EDC service extensions for persistence, bootstrapping, and monitoring.

- [Identity extensions](https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/extensions/identityhub/initial-participant): extensions · IdentityHub-specific extensions such as initial participant bootstrapping. · `extensions/identityhub/initial-participant`
- [Super-user seed](https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/extensions/seed/super-user): bootstrap extension · Bootstraps privileged or default identities for initial setup. · `extensions/seed/super-user`
- [Colored monitor](https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/extensions/monitor/colored-jdk-monitor): monitor extension · JDK logging formatter and runtime observability helper. · `extensions/monitor/colored-jdk-monitor`
- [SQL migrations](https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/extensions/store/sql/migrations): postgres migrations · Flyway-backed PostgreSQL schema and versioning for participants, keys, DIDs, credentials, issuance, holders, attestations, STS, and JTI validation. · `extensions/store/sql/migrations`

### Packaging and deploy

Helm charts, Docker composition, and release tooling.

- [Helm charts](https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/charts): k8s packaging · Kubernetes charts for production and memory variants of both services. · `charts`
- [Docker compose](https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/deployment/docker): local deploy · Local container composition and PostgreSQL initialization scripts. · `deployment/docker`
- [CI/CD](https://github.com/eclipse-tractusx/tractusx-identityhub/blob/main/.github/workflows): release automation · GitHub Actions workflows for linting, scanning, testing, publishing, and release automation. · `.github/workflows`

### Operator UI

React frontend for browsing and managing participants, credentials, DIDs, and keys.

- [Operator UI](https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/ui): react app · React + TypeScript frontend for managing participants, credentials, DIDs, key pairs, and search. · `ui`

### API and verification

OpenAPI, Bruno collections, walkthroughs, and deployment verification assets.

- [API docs](https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/docs/api): api contracts · OpenAPI definitions and Bruno collections documenting Identity, Issuance, Admin, DID, STS, and StatusList APIs. · `docs/api`
- [E2E checks](https://github.com/eclipse-tractusx/tractusx-identityhub/tree/main/tests/deployment): verification assets · Deployment tests, walkthroughs, and credential verification scripts. · `tests/deployment`

### Other components

- **PostgreSQL**: durable store · Primary durable state for production runtime data.
- **Vault**: secret store · Secret backend for private keys and other sensitive runtime material.
- **EDC connector**: external participant · External dataspace participant that requests presentations and participates in DCP flows.

## Connections

- IdentityHub → SQL migrations: uses schema · Production IdentityHub persists business state through the shared PostgreSQL migrations layer.
- IssuerService → SQL migrations: uses schema · Production IssuerService persists business state through the shared PostgreSQL migrations layer.
- SQL migrations → PostgreSQL: provisions · Migrations define and evolve the PostgreSQL schema used by both runtimes.
- IdentityHub → Vault: reads secrets · IdentityHub can source private keys and sensitive material from Vault in production.
- IssuerService → Vault: reads secrets · IssuerService can source private keys and sensitive material from Vault in production.
- IdentityHub → EDC connector: presentation · External connectors request verifiable presentations from IdentityHub.
- EDC connector → IdentityHub: DCP request · Presentation flow enters IdentityHub from an external dataspace participant.
- IdentityHub → IssuerService: issuance · IdentityHub requests credential issuance from IssuerService via DCP.
- IssuerService → IdentityHub: offers/metadata · IssuerService exposes issuance APIs and credential offer flows consumed by IdentityHub.
- Operator UI → IdentityHub: Identity APIs · UI manages participants, DIDs, key pairs, and credentials through IdentityHub HTTP APIs.
- Operator UI → IssuerService: Issuer APIs · UI manages definitions, holders, issuance processes, and lifecycle actions through IssuerService HTTP APIs.
- IdentityHub memory → IdentityHub: same service · Memory variant mirrors the IdentityHub runtime shape without durable persistence.
- Issuer memory → IssuerService: same service · Memory variant mirrors the IssuerService runtime shape without durable persistence.
- IdentityHub memory → Operator UI: dev target · UI can be pointed at the memory runtime for local development.
- Issuer memory → Operator UI: dev target · UI can be pointed at the memory runtime for local development.
- IdentityHub → Identity extensions: loads extensions · IdentityHub runtime is assembled from modular EDC extensions.
- IdentityHub → Super-user seed: bootstrap · Runtime can be seeded with privileged participant/user state.
- IssuerService → Super-user seed: bootstrap · IssuerService can be seeded with initial operator or super-user state.
- IdentityHub → Colored monitor: logging · Runtime uses the shared JDK monitor formatting extension.
- IssuerService → Colored monitor: logging · Runtime uses the shared JDK monitor formatting extension.
- Helm charts → IdentityHub: deploys · Charts package the production and memory IdentityHub workloads.
- Helm charts → IssuerService: deploys · Charts package the production and memory IssuerService workloads.
- Docker compose → IdentityHub memory: runs locally · Docker composition supports local IdentityHub execution.
- Docker compose → Issuer memory: runs locally · Docker composition supports local IssuerService execution.
- CI/CD → Helm charts: validates/publishes · CI validates, packages, and publishes Helm charts.
- CI/CD → Operator UI: builds · CI builds, tests, and publishes the frontend artifact.
- CI/CD → IdentityHub: builds · CI builds and scans the backend runtime images and artifacts.
- CI/CD → IssuerService: builds · CI builds and scans the backend runtime images and artifacts.
- API docs → IdentityHub: documents · API specs describe the backend service surfaces and protocol flows.
- E2E checks → IdentityHub: verifies · Deployment and API checks exercise IdentityHub flows.
- E2E checks → IssuerService: verifies · Deployment and API checks exercise IssuerService flows.
- E2E checks → Operator UI: smoke tests · Verification assets include end-to-end scenarios involving the UI and backend.