# ccims/clara architecture

> Architecture diagram of the GitHub repository ccims/clara, 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/ccims/clara
- Repository: https://github.com/ccims/clara

## Overview

##### Project Type and Purpose
- CLARA is a specialized framework: it is not a traditional full-stack web application but a tool that collects, aggregates, filters, merges, and exports architectural data from Kubernetes-deployed systems.
- Its key goal is to ease the transition of an existing architecture into a Gropius model, with alternative export methods (GraphViz) available.
- The README clearly identifies prerequisites (such as Kubernetes, kube-api, syft, Java, and Gradle) and outlines that the artifact includes the CLARA framework and a sample reference architecture (T2-Project).

##### Analyzing the File Structure
- Top-Level Directories and Files: You have the main build files (gradle scripts, .envrc, etc.), documentation directories (docs, README.md, INSTALL.md), and deployment configurations.
- The core application resides in the “clara-app” directory with an organized package structure. For example:
- The “aggregation” package contains classes that handle recovery—divided into submodules for different platforms (Kubernetes, DNS, OpenTelemetry, SBOM).
- The “api” package partitions the system’s entry points for aggregation, export, filtering, merging, and the definitions of architectural components (e.g., Component, Domain, Communication).
- The “export” packages include modules for exporting the recovered architecture in various formats (GraphViz and Gropius GraphQL integration).
- Supporting modules such as “filter”, “merge”, and “config” indicate that data goes through several processing stages.
- Additional directories like “clara-graphql”, “clara-integration-tests”, and “clara-protos” show that external interfaces (GraphQL) and protocol definitions (e.g., Opentelemetry and ping service proto files) are pivotal parts of the project.
- The “deployment” and “t2-deployment” directories illustrate that actual system deployment and integration testing with external systems (like MongoDB and microservices) are considered.

##### Key Components
a. Core Application (CLARA Framework) – This is the heart of the system:
- Aggregation Module: Central to architecture recovery and includes:
- Kubernetes Aggregation Submodule with further bifurcation (aggregators for DNS, kubeAPI, OpenTelemetry, and SBOM gathering).
- Manager and Executor classes ensuring parallel execution and handling of failures.
- API Layer: Provides interfaces for invoking aggregation logic, exporting functionality, and filtering/merging processes.
- Export Module: Supports exporting via Graphviz and integration with Gropius (using GraphQL queries and mutations).
- Filter and Merge Modules: Responsible for cleaning up the recovered model—removing unwanted components and merging data.
- Configuration and Utility Modules: Manage application settings, logging, and utility functions to support processing pipelines.

b. External Systems and Tools:
- Kubernetes Cluster: CLARA interacts with a Kubernetes cluster to recover architecture (via the Kubernetes API).
- External Tools: Integration with syft for SBOM analysis and OpenTelemetry for log and trace data aggregation.
- Gropius: Optional integration where the recovered model is mapped to a Gropius issue management system through GraphQL APIs.
- GraphViz: For alternative architecture export visualization.

c. Testing and Deployment:
- Integration Tests Component: Ensures that the aggregation, export, and recovery functions are working correctly.
- Deployment Configurations: YAML files for deploying the application and dependent services (like the OpenTelemetry Collector) in a Kubernetes environment.

##### Relationships and Interactions
- Data Flow: Data is collected from a live Kubernetes environment and external tools. Each aggregator (e.g., DNS, kubeAPI, OpenTelemetry) processes specific aspects of system telemetry.
- Processing Pipeline: The data flows from the aggregation modules, then possibly through filtering and merging, and finally into the export modules.
- Aggregators feeding data into the aggregation manager.
- The aggregation manager interfacing with filtering, merging, and then handing off the data to the export executors.
- Export modules then push data to external systems (Gropius via GraphQL or visualizations via Graphviz).

##### Architectural Patterns and Design Highlights
- Modularization: The project is logically modularized by function (aggregation, export, filtering, merging) supporting separation of concerns.
- Extensibility: The design of multiple aggregator implementations (for DNS, kubeAPI, OpenTelemetry, and SBOM) indicate a plug-in or strategy pattern where new aggregators can be added.
- Integration: The system is tightly integrated with Kubernetes, leveraging configuration files and client libraries to interact with the cluster.
- API-First Approach: The abstraction layers in the “api” directories highlight how the internal data processes are exposed and orchestrated.

##### Final Recommendations
- That each component is clearly labeled with its purpose and references the directory names/modules from the file tree (for example, “clara-app/aggregation/platform/kubernetes/aggregators”).
- Detail the flow from data acquisition (Kubernetes logs and metrics) through processing (filtering and merging) to final export.
- Don’t hesitate to further break down components if they are complex (e.g., showing subcomponents within the OpenTelemetry aggregator, such as its SpanProvider submodule).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core CLARA Framework and its components
    subgraph "Core CLARA Framework"
        Core["Core CLARA Framework"]:::internal
        Aggregation["Aggregation Module"]:::internal
        subgraph "Aggregation Details"
            KubeAgg["Kubernetes Aggregators"]:::internal
            SBOMAgg["SBOM Aggregator"]:::internal
        end
        API["API Layer"]:::internal
        Export["Export Module"]:::internal
        subgraph "Export Details"
            GraphvizExp["Graphviz Export"]:::internal
            GropiusExp["Gropius Export"]:::internal
        end
        Filter["Filter Module"]:::internal
        subgraph "Filtering Details"
            FilterRules["Filter Rules"]:::internal
        end
        Merge["Merge Module"]:::internal
        Config["Configuration Module"]:::internal
        Utils["Utility Module"]:::internal
    end

    %% Supporting External Systems
    subgraph "External Systems"
        Kubernetes["Kubernetes Cluster (KubeAPI)"]:::external
        Syft["Syft (SBOM Analysis)"]:::external
        OpenTelemetry["OpenTelemetry Aggregation"]:::external
        GropiusExt["Gropius (GraphQL Integration)"]:::external
        GraphvizExt["Graphviz Visualization"]:::external
    end

    %% Supporting Components: Testing, Deployment & Protocols
    subgraph "Supporting Components"
        IntegrationTests["Integration Tests"]:::support
        Deployment["Deployment Configurations"]:::support
        T2Deployment["T2 Deployment"]:::support
        ProtocolDefs["Protocol Definitions"]:::support
    end

    %% Define data flow relationships within Core Framework
    Core -->|"contains"| Aggregation
    Aggregation -->|"feeds"| API
    API -->|"routes to"| Filter
    API -->|"routes to"| Merge
    API -->|"routes to"| Export
    Filter -->|"refines"| Merge
    Merge -->|"supplies data to"| Export

    %% External systems providing data to Aggregation
    Kubernetes -->|"provides data"| Aggregation
    Syft -->|"analyzes SBOM"| Aggregation
    OpenTelemetry -->|"streams telemetry"| Aggregation

    %% Export module pushing data to external visualizers
    Export -->|"exports to"| GropiusExt
    Export -->|"exports to"| GraphvizExt

    %% Supporting components linking to Core Framework
    Deployment -->|"configures"| Core
    T2Deployment -->|"configures"| Core
    IntegrationTests -->|"verifies"| Core
    ProtocolDefs -->|"defines protocols for"| Core

    %% Click Events for Core Components
    click Core "https://github.com/ccims/clara/tree/main/clara-app/src/main/kotlin/de/unistuttgart/iste/sqa/clara"
    click Aggregation "https://github.com/ccims/clara/tree/main/clara-app/src/main/kotlin/de/unistuttgart/iste/sqa/clara/aggregation"
    click KubeAgg "https://github.com/ccims/clara/tree/main/clara-app/src/main/kotlin/de/unistuttgart/iste/sqa/clara/aggregation/platform/kubernetes/aggregators"
    click SBOMAgg "https://github.com/ccims/clara/tree/main/clara-app/src/main/kotlin/de/unistuttgart/iste/sqa/clara/aggregation/sbom"
    click API "https://github.com/ccims/clara/tree/main/clara-app/src/main/kotlin/de/unistuttgart/iste/sqa/clara/api"
    click Export "https://github.com/ccims/clara/tree/main/clara-app/src/main/kotlin/de/unistuttgart/iste/sqa/clara/export"
    click GraphvizExp "https://github.com/ccims/clara/tree/main/clara-app/src/main/kotlin/de/unistuttgart/iste/sqa/clara/export/graphviz"
    click GropiusExp "https://github.com/ccims/clara/tree/main/clara-app/src/main/kotlin/de/unistuttgart/iste/sqa/clara/export/gropius"
    click Filter "https://github.com/ccims/clara/tree/main/clara-app/src/main/kotlin/de/unistuttgart/iste/sqa/clara/filter"
    click FilterRules "https://github.com/ccims/clara/tree/main/clara-app/src/main/kotlin/de/unistuttgart/iste/sqa/clara/filter/rules"
    click Merge "https://github.com/ccims/clara/tree/main/clara-app/src/main/kotlin/de/unistuttgart/iste/sqa/clara/merge"
    click Config "https://github.com/ccims/clara/tree/main/clara-app/src/main/kotlin/de/unistuttgart/iste/sqa/clara/config"
    click Utils "https://github.com/ccims/clara/tree/main/clara-app/src/main/kotlin/de/unistuttgart/iste/sqa/clara/utils"
    
    %% Click Events for External/Supporting Components
    click GropiusExt "https://github.com/ccims/clara/tree/main/clara-graphql"
    click IntegrationTests "https://github.com/ccims/clara/tree/main/clara-integration-tests"
    click Deployment "https://github.com/ccims/clara/tree/main/deployment"
    click T2Deployment "https://github.com/ccims/clara/tree/main/t2-deployment"
    click ProtocolDefs "https://github.com/ccims/clara/tree/main/clara-protos"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#004085,stroke-width:2px,font-weight:bold;
    classDef external fill:#d4edda,stroke:#155724,stroke-width:2px,font-weight:bold;
    classDef support fill:#ffeeba,stroke:#856404,stroke-width:2px,font-weight:bold;
```
