# eda-labs/clab-connector architecture

> Architecture diagram of the GitHub repository eda-labs/clab-connector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eda-labs/clab-connector
- Repository: https://github.com/eda-labs/clab-connector

## Overview

##### Project type and purpose
- This is a Python-based CLI connector tool (“clab-connector”) that automates the onboarding and offboarding of Containerlab topologies into an Event-Driven Automation (EDA) system running in Kubernetes.
- It provides subcommands (integrate, remove, export-lab, generate-crs) to read a Containerlab topology JSON, render Kubernetes CR YAML via Jinja2 templates, and apply or delete those resources against an EDA cluster (using HTTP calls and `kubectl`).

##### High-level architecture from the file tree
- Top-level module: `clab_connector/`
- `cli/` – entrypoint & argument parsing (main.py)
- `services/` – business logic for each subcommand: integration, removal, export, manifest generation
- `models/` – domain models for Network Topology, Nodes, Links, plus a factory for node types
- `clients/` – adapters for external systems:
– `eda/http_client.py` for direct HTTP API calls to EDA (Keycloak & EDA CRD)
– `kubernetes/client.py` wrapping `kubectl apply/delete`
- `templates/` – Jinja2 templates for CR YAML artifacts, init, interfaces, profiles, etc.
- `utils/` – shared helpers: YAML processing, constants, exception types, logging configuration

1. CLI Layer
– Input: command + flags + `topology-data.json` file
– Component: `clab_connector/cli/main.py`
2. Service Layer
– IntegrationService, RemovalService, ExportService, ManifestGeneratorService
3. Domain Layer
– Topology, Node, Link, NodeFactory (in `models/`)
4. Adapter Layer
a. EDA HTTP Client (Keycloak & EDA CRDs)
b. Kubernetes Client (invokes `kubectl`)
5. Template Engine
– Jinja2 runtime rendering of YAML from templates in `templates/`
6. External Systems
– Containerlab (source of `topology-data.json`)
– Kubernetes Cluster running EDA + Keycloak

1. CLI → Service: pass parsed options & path to JSON
2. Service → Domain: construct in-memory Topology object via models & node factory
3. Service → Template Engine: render CR YAML snippets for each domain object
4. Service → Adapter:
- Kubernetes Client: `kubectl apply/delete` of rendered YAML
- HTTP Client: token retrieval from Keycloak & direct EDA API calls (optional)
5. Adapters → External Systems: Kubernetes API server & EDA HTTP endpoints

C. Architectural patterns & design principles
- Layered (Presentation/Service/Domain/Infrastructure) or Hexagonal (Ports & Adapters)
- Single Responsibility per module: CLI only parses, Services only orchestrate, Models only define data, Clients only communicate externally
- Template-driven manifest generation (separation of concerns)
- Use of factory pattern for instantiating different node types

D. Key technologies & libraries
- Python 3.x, `uv` for packaging
- Jinja2 for templating
- YAML processor (ruamel.yaml or PyYAML in utils)
- HTTP (requests or httpx) for EDA API
- Subprocess or Python client for `kubectl`
- Logging config via `logging` module

##### Final advice
- Break the system into all logical components you see in the file tree (CLI, models, services, clients, templates, utils).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        cli["CLI Parser\n(main.py)"]:::presentation
    end

    subgraph "Service Layer"
        intSvc["IntegrationService"]:::service
        postHook["SROSPostIntegration"]:::service
        remSvc["RemovalService"]:::service
        expSvc["ExportService"]:::service
        genSvc["ManifestGeneratorService"]:::service
    end

    subgraph "Domain Layer"
        topo["Topology Model"]:::domain
        link["Link Model"]:::domain
        nodeBase["Node Base Class"]:::domain
        nodeFactory["Node Factory"]:::domain
        nokSrl["Nokia SRL Node"]:::domain
        nokSros["Nokia SROS Node"]:::domain
    end

    subgraph "Adapter Layer"
        edaHttp["EDA HTTP Client"]:::adapter
        edaClient["EDA CRD Client"]:::adapter
        k8sClient["Kubernetes Client"]:::adapter
        tmpl["Jinja2 Template Engine"]:::adapter
        subgraph "Utilities"
            utilsConst["Constants"]:::utility
            utilsEx["Exception Types"]:::utility
            utilsHelp["Helpers"]:::utility
            utilsLog["Logging Config"]:::utility
            utilsYaml["YAML Processor"]:::utility
        end
    end

    subgraph "External Systems"
        contlab["Containerlab\n(topology-data.json)"]:::external
        k8sCluster["Kubernetes Cluster\n(EDA & Keycloak)"]:::external
    end

    %% Data Flow
    contlab -->|"invoke"| cli
    cli -->|"calls"| intSvc
    cli -->|"calls"| remSvc
    cli -->|"calls"| expSvc
    cli -->|"calls"| genSvc

    intSvc -->|"uses"| topo
    intSvc -->|"uses"| link
    intSvc -->|"uses"| nodeFactory
    intSvc -->|"uses"| nodeBase
    intSvc -->|"uses"| nokSrl
    intSvc -->|"uses"| nokSros
    intSvc -->|"renders"| tmpl
    intSvc -->|"calls"| edaHttp
    intSvc -->|"calls"| k8sClient

    postHook -->|"hooks into"| intSvc

    remSvc -->|"uses"| tmpl
    remSvc -->|"calls"| k8sClient

    expSvc -->|"uses"| topo
    expSvc -->|"renders"| tmpl

    genSvc -->|"renders"| tmpl

    edaHttp -->|"auth/API calls"| edaClient
    edaHttp -->|"requests"| k8sCluster
    k8sClient -->|"kubectl apply/delete"| k8sCluster

    %% Utility usage
    intSvc -->|"logs/YAML"| utilsConst
    intSvc -->|"logs/errors"| utilsEx
    intSvc -->|"process YAML"| utilsHelp
    intSvc -->|"setup logging"| utilsLog
    intSvc -->|"YAML IO"| utilsYaml

    %% Click Events
    click cli "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/cli/main.py"
    click intSvc "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/services/integration/topology_integrator.py"
    click postHook "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/services/integration/sros_post_integration.py"
    click remSvc "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/services/removal/topology_remover.py"
    click expSvc "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/services/export/topology_exporter.py"
    click genSvc "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/services/manifest/manifest_generator.py"
    click topo "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/models/topology.py"
    click link "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/models/link.py"
    click nodeBase "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/models/node/base.py"
    click nodeFactory "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/models/node/factory.py"
    click nokSrl "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/models/node/nokia_srl.py"
    click nokSros "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/models/node/nokia_sros.py"
    click edaHttp "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/clients/eda/http_client.py"
    click edaClient "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/clients/eda/client.py"
    click k8sClient "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/clients/kubernetes/client.py"
    click tmpl "https://github.com/eda-labs/clab-connector/tree/main/clab_connector/templates/"
    click utilsConst "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/utils/constants.py"
    click utilsEx "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/utils/exceptions.py"
    click utilsHelp "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/utils/helpers.py"
    click utilsLog "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/utils/logging_config.py"
    click utilsYaml "https://github.com/eda-labs/clab-connector/blob/main/clab_connector/utils/yaml_processor.py"

    %% Styles
    classDef presentation fill:#D0E8FF,stroke:#333,stroke-width:1px;
    classDef service fill:#DFFFD0,stroke:#333,stroke-width:1px;
    classDef domain fill:#FFF3B0,stroke:#333,stroke-width:1px;
    classDef adapter fill:#FFD8B0,stroke:#333,stroke-width:1px;
    classDef external fill:#EEEEEE,stroke-dasharray: 5 5,stroke:#666;
    classDef utility fill:#FFE0E0,stroke:#333,stroke-width:1px;
```
