# eclipse-tractusx/tractusx-edc architecture

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

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

## Overview

##### Project type and purpose
- This is not a typical full-stack app but a platform packaging and deploying two microservice-style components of the Eclipse Data Space Connector (EDC):
– Control-Plane (administration, contract negotiation, resource management)
– Data-Plane (data transfer runtime)
- The project provides:
– Java modules and EDC extensions (under edc-controlplane, edc-dataplane, edc-extensions, core, spi)
– Docker images (built via `./gradlew dockerize`)
– Helm charts for Kubernetes (under charts/tractusx-connector* and charts/tractusx-connector-memory)
– CI/CD workflows (GitHub Actions in .github/workflows)

##### File structure
- Top-level packaging:
– core/, spi/ → foundational libraries and SPI interfaces
– edc-controlplane/, edc-dataplane/ → control-plane and data-plane distribution modules (PostgreSQL+Vault, in-memory)
– edc-extensions/ → a catalogue of pluggable feature extensions (agreements, identity, policy, data-plane proxy, token refresh, validators, migrations, etc.)
– charts/ → Helm chart definitions for Kubernetes deployments
– edc-tests/ → automated tests, end-to-end fixtures, and deployment tests
– .github/actions & .github/workflows → build, test, publish Docker images and Helm charts
- Architectural pattern:
– Microservices: control-plane and data-plane run as separate pods
– Plugin/SPI: edc-extensions loaded at runtime via Java’s ServiceExtension SPI
– Infrastructure as Code: Helm charts define k8s Deployment, Service, Ingress, ConfigMap, NetworkPolicy
– CI/CD pipelines automate version bump, code quality scans, Docker and Helm publishes

##### Main components and their responsibilities
a. Control-Plane Service
– Java process exposing the Management API (contract definitions, negotiations, catalog, assets, EDRs, response channels)
– Loads core-utils, edr-core, json-ld-core, and selected edc-extensions
– Persists state in PostgreSQL
– Manages secrets in Hashicorp Vault (via edc-controlplane-postgresql-hashicorp-vault module)
b. Data-Plane Service
– Java process handling actual data transfer streams
– Can be configured to use Vault for token storage (edc-dataplane-hashicorp-vault) or in-memory runtime for dev (edc-runtime-memory)
c. Helm/Infrastructure Layer
– charts/tractusx-connector-memory: deploys both control-plane (in-memory) and data-plane pods for quick dev
– charts/tractusx-connector: production variant with two separate charts:
· control-plane (deployment-controlplane.yaml, service-controlplane.yaml, ingress-controlplane.yaml, hpa, networkpolicy, serviceaccount)
· data-plane (deployment-dataplane.yaml, service-dataplane.yaml, ingress-dataplane.yaml, hpa)
– ConfigMaps for control-plane and data-plane configuration and custom CA certificates
d. CI/CD Pipeline
– GitHub Actions build Java artifacts, run tests, generate Allure reports, scan code, bump versions
– Actions publish Docker images to registry, publish Helm charts to chart repository
– Deployment tests and upgradeability tests ensure backward compatibility

##### Relationships and data flow
- Actor (CLI or GUI) → interacts with Control-Plane’s REST API
- Control-Plane → reads/writes to PostgreSQL for metadata and Vault for credentials
- Control-Plane → negotiates contracts, publishes EDRs to Data-Plane via its management endpoint
- Data-Plane → uses EDRs to start data streaming over HTTP/gRPC (or other supported protocols)
- Data consumers/providers → pull/push data via Data-Plane public API
- Helm charts → deploy pods, services, ingresses; they consume Kubernetes Secrets/ConfigMaps to configure Vault and DB connectivity
- CI/CD → upon commit to main, workflows trigger build → Docker image → push → Helm chart package → push

##### Architectural patterns and design principles
- Separation of concerns: control vs. data plane
- Plugin architecture via Java SPI (org.eclipse.edc.spi.system.ServiceExtension) for extensibility without core changes
- Immutable infrastructure: Docker images built from code, deployed via declarative Helm charts
- Infrastructure modularization: separate charts for memory/dev and prod (Vault+Postgres)
- Automated testing: unit tests in each module, end-to-end tests in edc-tests, deployment smoke tests in CI

##### Be detailed—capture
- Both runtime options (in-memory vs. prod Vault+Postgres)
- All external dependencies (Vault, Postgres, Docker registry, Helm repo)
- Key extension modules under each plane
- CI/CD artifacts and stages

## Diagram (Mermaid)

```mermaid
graph TB
    %% CI/CD
    CI["CI/CD Pipeline"]:::ci
    WF["GitHub Actions\n(.github/workflows/)"]:::ci
    Actions["Custom Actions\n(.github/actions/)"]:::ci
    CI --> WF --> Actions
    Actions --> Build["Build & Test"]:::ci
    Build --> DockerReg["Docker Registry"]:::ci
    Build --> HelmRepo["Helm Chart Repo"]:::ci
    HelmRepo --> Deploy["Deploy"]:::ci

    Deploy --> K8sCluster["Kubernetes Cluster"]:::cluster

    subgraph "Kubernetes Cluster"
        direction TB

        subgraph "Control-Plane"
            direction TB
            CPPod["Control-Plane Pod"]:::ms
            CPService["Service (ClusterIP)"]:::ms
            CPIngress["Ingress"]:::ms
            CPPod --> CPService --> CPIngress
            CPPod --> Postgres["PostgreSQL"]:::db
            CPPod --> Vault["HashiCorp Vault"]:::db
            CPPod --> CoreUtils["core-utils"]:::module
            CPPod --> EDRCore["edr-core"]:::module
            CPPod --> JSONLD["json-ld-core"]:::module
            CPPod --> SPI["SPI Interfaces"]:::module
            CPPod --> Extensions["EDC Extensions"]:::module
            CPPod --> CPBase["edc-controlplane-base"]:::module
            CPPod --> CPVaultDist["edc-controlplane-postgresql-hashicorp-vault"]:::module
            CPPod --> CPMemDist["edc-runtime-memory"]:::module
        end

        subgraph "Data-Plane"
            direction TB
            DPPod["Data-Plane Pod"]:::ms
            DPService["Service (ClusterIP)"]:::ms
            DPIngress["Ingress"]:::ms
            DPPod --> DPService --> DPIngress
            DPPod --> Vault
            DPPod --> DPBase["edc-dataplane-base"]:::module
            DPPod --> DPVault["edc-dataplane-hashicorp-vault"]:::module
            DPPod --> DPMem["(in-memory runtime)"]:::module
            DPPod --> SPI
            DPPod --> Extensions
        end
    end

    %% Helm charts
    DevChart["tractusx-connector-memory"]:::doc
    ProdChart["tractusx-connector"]:::doc
    Deploy --> DevChart
    Deploy --> ProdChart

    %% Click Events
    click CoreUtils "https://github.com/eclipse-tractusx/tractusx-edc/tree/main/core/core-utils"
    click EDRCore "https://github.com/eclipse-tractusx/tractusx-edc/tree/main/core/edr-core"
    click JSONLD "https://github.com/eclipse-tractusx/tractusx-edc/tree/main/core/json-ld-core"
    click SPI "https://github.com/eclipse-tractusx/tractusx-edc/tree/main/spi/"
    click CPBase "https://github.com/eclipse-tractusx/tractusx-edc/tree/main/edc-controlplane/edc-controlplane-base"
    click CPVaultDist "https://github.com/eclipse-tractusx/tractusx-edc/tree/main/edc-controlplane/edc-controlplane-postgresql-hashicorp-vault"
    click CPMemDist "https://github.com/eclipse-tractusx/tractusx-edc/tree/main/edc-controlplane/edc-runtime-memory"
    click DPBase "https://github.com/eclipse-tractusx/tractusx-edc/tree/main/edc-dataplane/edc-dataplane-base"
    click DPVault "https://github.com/eclipse-tractusx/tractusx-edc/tree/main/edc-dataplane/edc-dataplane-hashicorp-vault"
    click Extensions "https://github.com/eclipse-tractusx/tractusx-edc/tree/main/edc-extensions/"
    click DevChart "https://github.com/eclipse-tractusx/tractusx-edc/tree/main/charts/tractusx-connector-memory"
    click ProdChart "https://github.com/eclipse-tractusx/tractusx-edc/tree/main/charts/tractusx-connector"
    click WF "https://github.com/eclipse-tractusx/tractusx-edc/tree/main/.github/workflows/"
    click Actions "https://github.com/eclipse-tractusx/tractusx-edc/tree/main/.github/actions/"
    click edcTests "https://github.com/eclipse-tractusx/tractusx-edc/tree/main/edc-tests/"

    %% Styles
    classDef ms fill:#ADD8E6,stroke:#1E90FF
    classDef db fill:#98FB98,stroke:#228B22,stroke-width:2px
    classDef ci fill:#FFA500,stroke:#FF8C00,stroke-dasharray:5 5
    classDef module fill:#E0E0E0,stroke:#A9A9A9
    classDef doc fill:#F5DEB3,stroke:#DEB887
    classDef cluster fill:#FFFFFF,stroke:#000000,stroke-width:2px
```
