# eclipse-edc/minimumviabledataspace architecture

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

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

## Overview

##### Main system components
- Connector Runtimes:
– Consumer Connector (controlplane and associated dataplane)
– Two Provider Connectors (provider-qna and provider-manufacturing; each has its controlplane and dataplane)
- Catalog Server: A specialized runtime that aggregates catalog pointers from provider connectors.
- IdentityHub Services: One for the consumer and one for the provider; these are responsible for managing DID documents, verifiable credentials, and participant identity data.
- Issuer Service / NGINX: A separate issuer entity that hosts a static DID document (served via an NGINX container) and supplies public key information for signing credentials.
- Data Persistence and Vault Components (in Kubernetes deployments):
– PostgreSQL databases
– HashiCorp Vault instances (for secret management)
- Infrastructure & Deployment:
– Terraform scripts and Kubernetes manifests (e.g. Kind configs, ingress, modules for connectors, catalog server, identityhub, issuer)
– Seed scripts that bootstrap credentials and participant context

##### Out the relationships and interactions
- Interaction between the Consumer Connector and Provider Connectors via data exchange protocols (noting that they communicate using dataspace protocol HTTP endpoints).
- That the Provider Connectors do not expose their catalogs directly; instead, they register their assets (catalog assets) with the Catalog Server by acting as pointers.
- IdentityHub components: both consumer and provider IdentityHubs are used for obtaining and seeding verifiable credentials (e.g. during contract negotiations, a consumer must present MembershipCredential and a DataProcessorCredential).
- NGINX host for the issuer’s DID document; indicate that its endpoint must be reachable by other components and that the issuer public/private key pair is managed externally using OpenSSL (with re-generation processes shown in the advanced topics).

##### Architectural patterns and design principles
- The project adopts a modular architecture with microservice-like runtimes (several “launcher” modules) each responsible for a specific concern.
- It follows a service-oriented approach where runtime modules communicate via RESTful APIs (look for HTTP endpoints and Postman collections in the README).
- There is a clear separation between core functionality (credential handling, authentication, contract negotiation), infrastructure concerns (deployment with Terraform, Kubernetes configuration), and custom extension points (see the extensions directory for implementations such as Catalog Node Resolver and custom policy evaluation functions).

##### Relevant technologies and frameworks
- Gradle is used as the build system (see build.gradle.kts files).
- Java is the primary language (multiple src/main/java directories).
- Docker (for containerizing runtimes and NGINX) and Kubernetes (with Kind and Terraform for deployment) are involved.
- Additional key artifacts include configuration files for Checkstyle, GitHub workflows, and a suite of integration and performance tests.

- Use clear labels for every component (e.g., “Consumer Connector (Controlplane/Dataplane)”, “Provider Connector - Q&A”, “Provider Connector - Manufacturing”, “Catalog Server”, “IdentityHub (Consumer)”, “IdentityHub (Provider)”, “Issuer (NGINX)”, “PostgreSQL”, “Vault”, “Terraform/K8S Infra”)
- Architectural notes, such as the fact that provider connectors publish catalogs indirectly (via the catalog server) and that all DSP requests require additional verifiable credentials.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level external service
    IssuerService["Issuer Service / NGINX"]:::runtime

    %% Consumer Environment Subgraph
    subgraph "Consumer Environment"
        ConsumerConnector["Consumer Connector (Controlplane/Dataplane)"]:::runtime
        ConsumerIdentityHub["Consumer IdentityHub"]:::runtime
    end

    %% Provider Environment Subgraph
    subgraph "Provider Environment"
        ProviderQnA["Provider Connector - Q&A"]:::runtime
        ProviderManufacturing["Provider Connector - Manufacturing"]:::runtime
        ProviderIdentityHub["Provider IdentityHub"]:::runtime
        CatalogServer["Catalog Server"]:::runtime
    end

    %% Infrastructure Subgraph
    subgraph "Infrastructure & Deployment"
        PostgreSQL["PostgreSQL"]:::infra
        Vault["Vault"]:::infra
        InfraDeployment["Terraform/K8S Infra"]:::infra
        Extensions["Extensions"]:::infra
    end

    %% Interactions between Issuer and IdentityHubs
    IssuerService -->|"provides-key"| ConsumerIdentityHub
    IssuerService -->|"provides-key"| ProviderIdentityHub

    %% Consumer Connector interactions
    ConsumerConnector -->|"verify-credential"| ConsumerIdentityHub
    ConsumerConnector -->|"catalog-request"| CatalogServer
    CatalogServer -->|"catalog-response"| ConsumerConnector

    %% Provider Connectors interactions
    ProviderQnA -->|"register-catalog"| CatalogServer
    ProviderManufacturing -->|"register-catalog"| CatalogServer
    ProviderQnA -->|"credential-check"| ProviderIdentityHub
    ProviderManufacturing -->|"credential-check"| ProviderIdentityHub

    %% Custom Extensions integration
    ConsumerConnector ---|"custom-extension"| Extensions
    ProviderQnA ---|"custom-extension"| Extensions
    ProviderManufacturing ---|"custom-extension"| Extensions

    %% Infrastructure provisioning
    InfraDeployment -->|"provisions"| PostgreSQL
    InfraDeployment -->|"provisions"| Vault
    InfraDeployment -->|"deploys"| Extensions

    %% Class Definitions
    classDef runtime fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef infra fill:#A9DFBF,stroke:#145A32,stroke-width:2px;

    %% Click Events for Consumer Connector
    click ConsumerConnector "https://github.com/eclipse-edc/minimumviabledataspace/blob/main/.run/Connector Consumer Corp.run.xml"
    click ConsumerConnector "https://github.com/eclipse-edc/minimumviabledataspace/tree/main/launchers/controlplane"
    click ConsumerConnector "https://github.com/eclipse-edc/minimumviabledataspace/tree/main/launchers/dataplane"

    %% Click Events for Provider Connector - Q&A
    click ProviderQnA "https://github.com/eclipse-edc/minimumviabledataspace/blob/main/.run/Connector _provider-qna_.run.xml"
    click ProviderQnA "https://github.com/eclipse-edc/minimumviabledataspace/blob/main/deployment/assets/env/provider_connector_qna.env"

    %% Click Events for Provider Connector - Manufacturing
    click ProviderManufacturing "https://github.com/eclipse-edc/minimumviabledataspace/blob/main/.run/Connector _provider-manufacturing_.run.xml"
    click ProviderManufacturing "https://github.com/eclipse-edc/minimumviabledataspace/blob/main/deployment/assets/env/provider_connector_manufacturing.env"

    %% Click Events for Catalog Server
    click CatalogServer "https://github.com/eclipse-edc/minimumviabledataspace/blob/main/.run/Provider Catalog Server.run.xml"
    click CatalogServer "https://github.com/eclipse-edc/minimumviabledataspace/tree/main/launchers/catalog-server"
    click CatalogServer "https://github.com/eclipse-edc/minimumviabledataspace/tree/main/deployment/modules/catalog-server"

    %% Click Events for Consumer IdentityHub
    click ConsumerIdentityHub "https://github.com/eclipse-edc/minimumviabledataspace/blob/main/.run/IdentityHub Consumer Corp.run.xml"
    click ConsumerIdentityHub "https://github.com/eclipse-edc/minimumviabledataspace/tree/main/launchers/identity-hub"
    click ConsumerIdentityHub "https://github.com/eclipse-edc/minimumviabledataspace/blob/main/deployment/assets/env/consumer_identityhub.env"

    %% Click Events for Provider IdentityHub
    click ProviderIdentityHub "https://github.com/eclipse-edc/minimumviabledataspace/blob/main/.run/IdentityHub Provider Corp.run.xml"
    click ProviderIdentityHub "https://github.com/eclipse-edc/minimumviabledataspace/tree/main/launchers/identity-hub"
    click ProviderIdentityHub "https://github.com/eclipse-edc/minimumviabledataspace/blob/main/deployment/assets/env/provider_identityhub.env"

    %% Click Events for Issuer Service / NGINX
    click IssuerService "https://github.com/eclipse-edc/minimumviabledataspace/blob/main/.run/IssuerService.run.xml"
    click IssuerService "https://github.com/eclipse-edc/minimumviabledataspace/tree/main/launchers/issuerservice"
    click IssuerService "https://github.com/eclipse-edc/minimumviabledataspace/blob/main/deployment/assets/issuer/nginx.conf"
    click IssuerService "https://github.com/eclipse-edc/minimumviabledataspace/blob/main/deployment/assets/env/issuerservice.env"

    %% Click Events for PostgreSQL and Vault
    click PostgreSQL "https://github.com/eclipse-edc/minimumviabledataspace/tree/main/deployment/modules/postgres"
    click Vault "https://github.com/eclipse-edc/minimumviabledataspace/tree/main/deployment/modules/vault"

    %% Click Events for Infrastructure & Deployment
    click InfraDeployment "https://github.com/eclipse-edc/minimumviabledataspace/tree/main/deployment"
    click InfraDeployment "https://github.com/eclipse-edc/minimumviabledataspace/blob/main/deployment/kind.config.yaml"
    click InfraDeployment "https://github.com/eclipse-edc/minimumviabledataspace/blob/main/seed.sh"
    click InfraDeployment "https://github.com/eclipse-edc/minimumviabledataspace/blob/main/seed-k8s.sh"

    %% Click Events for Extensions
    click Extensions "https://github.com/eclipse-edc/minimumviabledataspace/tree/main/extensions/catalog-node-resolver"
    click Extensions "https://github.com/eclipse-edc/minimumviabledataspace/tree/main/extensions/dcp-impl"
    click Extensions "https://github.com/eclipse-edc/minimumviabledataspace/tree/main/extensions/did-example-resolver"
    click Extensions "https://github.com/eclipse-edc/minimumviabledataspace/tree/main/extensions/superuser-seed"
```
