# eclipse-edc/samples architecture

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

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

## Overview

##### Project Overview and Purpose
- The repository is a collection of sample implementations for the Eclipse Dataspace Components (EDC) framework. It is aimed at onboarding new community members by demonstrating various scopes (Basic, Transfer, Advanced, Policy, and Federated Catalog) so that users learn how to work with connectors, extensions, and integrations (such as telemetry, streaming, policy enforcement, etc.).
- The samples cover different aspects of the EDC framework – from the simplest connector implementations in the “basic” scope to complex integrations like custom runtimes, federated catalogs, Kafka streaming, and policy enforcement in other scopes.

##### Analyzing the File Structure
- Top-Level Organization: You see directories like “basic”, “advanced”, “transfer”, “policy”, “federated-catalog”, “system-tests”, and “util”. Each directory groups samples focusing on a specific EDC use case.
- Within each sample module:
- Gradle build files (build.gradle.kts) for dependency and build management.
- Configuration files (e.g., config.properties, JSON files for datasets, contract definitions, policies etc.) that represent runtime configurations.
- For the “advanced” and “transfer” samples, the presence of Dockerfiles, docker-compose files, and integration test resources indicates containerized runtimes and external service integrations such as Prometheus, OpenTelemetry, and Kafka.

##### Identifying Main Components
- Sample Scopes:
- Basic: Illustrates fundamental connector setup, health endpoints, and configuration examples.
- Transfer: Focuses on data transfer processes including negotiation, provider push, consumer pull, event-driven transfers, and streaming mechanisms.
- Advanced: Showcases custom runtime examples (like OpenTelemetry integration) and additional runtime configurations.
- Policy: Focuses on policy evaluation and enforcement (with sample policy functions and constraints).
- Federated Catalog: Demonstrates how catalog connectors and node resolvers work, including embedded and standalone deployments.
- Core runtime component:
- Each sample implements and runs on the EDC runtime, so include an “EDC Runtime” layer representing the container that loads extensions via Java’s SPI mechanism (visible in META-INF/services).
- External Services and Integrations:
- Messaging or Streaming: Kafka (for streaming data scenarios in transfer samples).
- Monitoring & Observability: OpenTelemetry and Prometheus (in advanced samples with Docker/Docker Compose setups).
- HTTP/REST APIs: Health endpoints, data transfer endpoints, and any custom API controllers.
- Test Infrastructure:
- System Tests: Represent integration tests (found under system-tests) that simulate end-to-end flows across the different scopes.

##### Mapping Relationships and Data Flow
- How client requests flow from a REST API (for example, the Health API Controller in the basic scope) into the EDC runtime.
- How configuration files (e.g., config.properties, JSON definitions) feed into the runtime to configure connectors, contracts, assets, and policies.
- How sample modules interact via the extension mechanism – each sample registers its own ServiceExtension component.
- In federated catalog samples, demonstrate how catalog queries are propagated between connectors and a separate node resolver which crawls multiple catalogs.

##### Architectural Patterns and Design Principles
- Modular design: Each scope is an independent module, enabling learning and extensibility.
- Plugin/Extension Architecture: Emphasize the use of Java SPI (via META-INF/services) that allows dynamic loading of service extensions.
- Separation of Concerns: Illustrate the distinction between connector logic, policy enforcement, configuration management, and transfer orchestration.
- Containerization & External Integration: Show how Docker and Docker Compose are used (especially in advanced samples) to simulate a multi-container environment with monitoring (Prometheus) and distributed tracing (OpenTelemetry).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Sample Scopes
    subgraph "Sample Scopes"
        basicScope["Basic Sample Scope"]:::scope
        transferScope["Transfer Sample Scope"]:::scope
        advancedScope["Advanced Sample Scope"]:::scope
        policyScope["Policy Sample Scope"]:::scope
        fedCatalogScope["Federated Catalog Sample Scope"]:::scope
    end

    %% EDC Runtime Layer
    subgraph "EDC Runtime"
        edcRuntime["EDC Runtime & Extension Registration"]:::runtime
    end

    %% External Services & Integrations Layer
    subgraph "External Services & Integrations"
        httpApi["HTTP/REST APIs"]:::external
        monitor["Monitoring (OpenTelemetry & Prometheus)"]:::external
        subgraph "Messaging/Streaming"
            kafkaToHttp["Kafka to HTTP"]:::external
            kafkaBroker["Kafka Broker"]:::external
        end
    end

    %% DevOps & Testing Layer
    subgraph "DevOps & Testing"
        ciCd["CI/CD (GitHub Actions)"]:::devops
        systemTests["System Tests"]:::devops
    end

    %% Relationships: Sample Scopes register extensions to EDC Runtime
    basicScope -->|"Extension Registration"| edcRuntime
    transferScope -->|"Extension Registration"| edcRuntime
    advancedScope -->|"Extension Registration"| edcRuntime
    policyScope -->|"Extension Registration"| edcRuntime
    fedCatalogScope -->|"Extension Registration"| edcRuntime

    %% EDC Runtime interactions
    edcRuntime -->|"HTTP API"| httpApi

    %% External Integrations from specific Sample Scopes
    advancedScope -->|"Monitoring Integration"| monitor
    transferScope -->|"Event Stream"| kafkaToHttp
    transferScope -->|"Event Stream"| kafkaBroker

    %% DevOps interactions
    ciCd -->|"Build & Deploy"| edcRuntime
    systemTests -->|"Integration Testing"| edcRuntime

    %% Click Events
    click basicScope "https://github.com/eclipse-edc/samples/tree/main/basic/"
    click transferScope "https://github.com/eclipse-edc/samples/tree/main/transfer/"
    click advancedScope "https://github.com/eclipse-edc/samples/tree/main/advanced/"
    click policyScope "https://github.com/eclipse-edc/samples/tree/main/policy/"
    click fedCatalogScope "https://github.com/eclipse-edc/samples/tree/main/federated-catalog/"
    click edcRuntime "https://github.com/eclipse-edc/samples/blob/main/basic/basic-02-health-endpoint/src/main/resources/META-INF/services/org.eclipse.edc.spi.system.ServiceExtension"
    click monitor "https://github.com/eclipse-edc/samples/tree/main/advanced/advanced-01-open-telemetry/open-telemetry-runtime"
    click kafkaToHttp "https://github.com/eclipse-edc/samples/tree/main/transfer/streaming/streaming-02-kafka-to-http"
    click kafkaBroker "https://github.com/eclipse-edc/samples/tree/main/transfer/streaming/streaming-03-kafka-broker/"
    click ciCd "https://github.com/eclipse-edc/samples/tree/main/.github/"
    click systemTests "https://github.com/eclipse-edc/samples/tree/main/system-tests/"

    %% Styles
    classDef scope fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef runtime fill:#87CEEB,stroke:#333,stroke-width:2px;
    classDef external fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef devops fill:#FFA07A,stroke:#333,stroke-width:2px;
```
