# openclarity/kubeclarity architecture

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

- Interactive diagram: https://gitdiagram.com/openclarity/kubeclarity
- Repository: https://github.com/openclarity/kubeclarity

## Overview

##### Main components
- API/Backend Server – Found in the “api”, “backend”, and “sbom_db” directories. This layer handles REST API endpoints (with subcomponents for operations, models, and controllers) and communicates with the underlying database for managing applications, resources, packages, and vulnerabilities.
- CLI Tool – The “cli” directory contains command‐line functionality. It is used in CI/CD pipelines to generate SBOMs and perform vulnerability scans, and then export results back to the backend.
- UI – Under the “ui” directory, which implements the web dashboard. It provides user interactions for viewing applications, scan results, and performing actions such as scheduling a runtime scan.
- Scanners and Analyzers – Scanners for vulnerabilities and SBOM generators are integrated throughout the project. Look at the “runtime_k8s_scanner”, “cis_docker_benchmark_scanner”, and the shared packages under “shared/pkg/analyzer” and “shared/pkg/scanner”. They implement support for tools like Syft, CycloneDX, Grype, and Trivy.
- Deployment & Configuration – The “charts” directory provides Helm charts for Kubernetes deployment. Additionally, configuration files (Dockerfiles, Makefile, go.mod files) indicate containerized deployment, CI workflows (under .github/workflows), and integration into Kubernetes.
- Utility & Shared Components – The “shared” directory contains common utilities, converters, analyzers, and job managers that support various pipelines across the system.

##### Relationships & Data Flow
- The UI interacts with the API/Backend via REST calls, obtaining data for dashboards (e.g., vulnerabilities, scan statuses, SBOMs).
- The CLI tool (and runtime scanners like “runtime_k8s_scanner”) serves as an external client that triggers SBOM generation and vulnerability scans, then sends data (using export functionality) to the API/Backend.
- Analyzers and scanners are plugged into both CLI and backend pipelines; they fetch data from containers (or local images/registries), process SBOM creation, scan for vulnerabilities, and then aggregate results.
- Deployment is orchestrated using Helm charts for Kubernetes, and jobs (such as scheduled or on-demand scanning jobs) rely on proper RBAC permissions and secret management.

##### Architectural Patterns and Design Principles
- Separation of Concerns: There is a clear split between API (with its models, operations, and endpoints) and the CLI/UI layers that consume these endpoints.
- Modular and Pluggable Architecture: The design accommodates multiple SBOM generators and vulnerability scanners, with configuration (such as environment variables) allowing for easy swapping or adding of tools.
- Microservices/Containerization: Multiple Dockerfiles indicate that different parts (backend, CLI, runtime scanners, cis docker benchmark updater, and SBOM DB) can be run as separate containers.
- Kubernetes Deployment: Integration with Helm charts, K8s RBAC, and secret management for container registry access underscores that deployment is designed for cloud orchestration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "API/Backend Layer"
        A1["REST API (api)"]:::backend
        A2["Backend Service (backend)"]:::backend
        A3["SBOM Database Service (sbom_db)"]:::backend
        DB["Database & SBOM"]:::db
    end

    subgraph "Client Layer"
        UI["UI Dashboard"]:::frontend
        CLI["CLI Tool"]:::cli
    end

    subgraph "Scanning Engine"
        RT["K8s Runtime Scanner (runtime_k8s_scanner)"]:::scanner
        CIS["CIS Docker Benchmark Scanner (cis_docker_benchmark_scanner)"]:::scanner
        ANA["Shared Analyzer (shared/pkg/analyzer)"]:::scanner
        SCN["Shared Scanner (shared/pkg/scanner)"]:::scanner
    end

    subgraph "Deployment & Infrastructure"
        HELM["Helm Charts (charts)"]:::deployment
        CI["CI/CD & Dockerfiles (.github/workflows)"]:::deployment
    end

    subgraph "Utilities & Shared"
        UTIL["Common Utilities (shared)"]:::shared
    end

    UI -->|"REST_Calls"| A1
    CLI -->|"SBOM_Export"| A1
    A1 -->|"Stores_Data"| DB
    A1 -->|"Delegates"| A2
    A1 -->|"Accesses"| A3

    A2 -->|"Triggers_Scan"| RT
    A2 -->|"Triggers_Scan"| CIS
    A2 -->|"Integrates_With"| ANA
    A2 -->|"Integrates_With"| SCN

    HELM -->|"Deploys"| A1
    HELM -->|"Deploys"| A2
    HELM -->|"Deploys"| A3
    HELM -->|"Deploys"| UI
    HELM -->|"Deploys"| CLI
    HELM -->|"Deploys"| RT
    HELM -->|"Deploys"| CIS

    CI -->|"Builds"| A1
    CI -->|"Builds"| A2
    CI -->|"Builds"| A3
    CI -->|"Builds"| CLI
    CI -->|"Builds"| RT
    CI -->|"Builds"| CIS

    A2 -->|"Utilizes"| UTIL
    CLI -->|"Utilizes"| UTIL
    UI -->|"Utilizes"| UTIL

    classDef frontend fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef cli fill:#ABEBC6,stroke:#1ABC9C,stroke-width:2px;
    classDef db fill:#D5DBDB,stroke:#AAB7B8,stroke-width:2px;
    classDef scanner fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;
    classDef deployment fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef shared fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;

    click A1 "https://github.com/openclarity/kubeclarity/tree/main/api"
    click A2 "https://github.com/openclarity/kubeclarity/tree/main/backend/cmd/backend"
    click A3 "https://github.com/openclarity/kubeclarity/tree/main/sbom_db"
    click CLI "https://github.com/openclarity/kubeclarity/tree/main/cli"
    click UI "https://github.com/openclarity/kubeclarity/tree/main/ui"
    click RT "https://github.com/openclarity/kubeclarity/tree/main/runtime_k8s_scanner"
    click CIS "https://github.com/openclarity/kubeclarity/tree/main/cis_docker_benchmark_scanner"
    click ANA "https://github.com/openclarity/kubeclarity/tree/main/shared/pkg/analyzer"
    click SCN "https://github.com/openclarity/kubeclarity/tree/main/shared/pkg/scanner"
    click HELM "https://github.com/openclarity/kubeclarity/tree/main/charts"
    click CI "https://github.com/openclarity/kubeclarity/tree/main/.github/workflows"
    click UTIL "https://github.com/openclarity/kubeclarity/tree/main/shared"
```
