# ibm/cbomkit architecture

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

- Interactive diagram: https://gitdiagram.com/ibm/cbomkit
- Repository: https://github.com/ibm/cbomkit

## Overview

##### Frontend – The CBOMkit-coeus
- Located in the “frontend” directory, this component is built in Vue.js. It offers an intuitive web user interface for:
– Browsing and uploading CBOM files
– Initiating scans (by submitting Git URLs or package URLs)
– Viewing generated CBOMs and associated compliance reports
- It also provides an independent deployment option (“coeus”) for just the visualization/compliance check.
- Docker support with its dedicated Dockerfile and Nginx configurations.

##### API Server (Backend)
- The backend is primarily implemented as a Java application using Maven (see the pom.xml and src/main/java). Its responsibilities include:
– Exposing a RESTful API (with an OpenAPI specification available in openapi.yaml) to handle:
∗ Retrieval of stored/generated CBOMs,
∗ Acceptance of new CBOM scan requests,
∗ Compliance check queries.
– WebSocket integration for providing real-time updates on the scanning process.
– Handling the CBOM generation and interacting with external scanning tools (e.g., CBOMkit-hyperion/Sonar Cryptography Plugin) that actually examine source code to create CBOMs.
- The codebase is structured into various domains such as scanning, compliance, database interaction, and process management which can be visualized as distinct modules or service components within the API server.

##### Database
- Although the database itself isn’t coded in the repository, the helm chart configuration and docker-compose file imply that a persistent data store (likely PostgreSQL based on helm parameter names) is used.
- It is responsible for storing all the CBOMs and providing data to the API server through read-model repositories.

##### Additional Deployment & Infrastructure Elements
- Helm charts in the “chart” directory allow deployment to Kubernetes, integrating all components in production.
- Docker Compose is used for development or simplified production deployments.
- The project includes Maven wrapper scripts and Makefile commands to manage builds and deployments.
- Logging, progress tracking, error handling, and event buses are implemented in the backend (e.g., using WebSocketProgressDispatcher, DomainEventBus, etc.) to facilitate the scanning and CBOM lifecycle.

● “Frontend/CBOMkit-coeus” – a Vue.js based web interface, which can either be integrated with the full suite or deployed independently.
● “API Server” – the backend Java service that handles REST API endpoints and WebSocket connections; you may further decompose this into modules for scanning, compliance checking, and database interaction.
● “External Services” – these include source repositories (e.g., GitHub) and scanning services (the CBOMkit-hyperion integration) that the API server interacts with for CBOM generation.
● “Deployment & Infrastructure” – show supporting infrastructure like Docker containers, Kubernetes (via Helm), and configuration management (Makefile, Maven wrapper).

● From “User/Browser” to “Frontend” indicating user interactions (e.g., upload, view, scan initiation).
● From “Frontend” to “API Server” showing RESTful calls (e.g., lookup, scan requests, compliance queries) and WebSocket connections for progress updates.
● From “API Server” to “Database” for storing and retrieving CBOM data.
● From “API Server” to “External Services” to indicate real-time scanning and data fetching (for example, cloning Git repositories and invoking scanning modules).

c. Architectural Patterns and Technologies:
● Modular layered architecture on the backend, where the scanning, compliance, and database interaction are clearly separated.
● Use of event-driven mechanisms (Domain Event Bus, Process Manager) for handling long-running CBOM generation and asynchronous updates.
● Technology stacks: Vue.js for frontend, Java/Maven for backend, Docker and Kubernetes for deployment.
● Real-time communication via WebSockets for progress feedback.

● Emphasize the separation of concerns by showing the distinct boundaries between the frontend (UI/CBOMkit-coeus) and the API server.
● Clearly indicate where the scanning functionality is located within the backend, and how it communicates both with external code repositories and the compliance module.
● If space permits, indicate the deployment options (docker-compose for simple deployments, helm chart for Kubernetes) to provide additional context for operational flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    U["User/Browser"]:::user

    %% Frontend Layer
    subgraph "Frontend Layer"
        F["Frontend/CBOMkit-coeus (Vue.js)"]:::frontend
        DF["Dockerfile"]:::frontend
        NC["Nginx Config"]:::frontend
    end

    %% API Server
    subgraph "API Server"
        B["API Server (Java/Maven)"]:::backend
        P["pom.xml"]:::backendFile
        J["Java Source Code"]:::backendFile
        O["OpenAPI Spec"]:::backendFile
        %% Backend Modules
        subgraph "Backend Modules"
            S["Scanning Module"]:::backendModule
            C["Compliance Module"]:::backendModule
            DCI["Database Interface"]:::backendModule
        end
    end

    %% Database
    subgraph "Database"
        DB["Database (PostgreSQL)"]:::database
    end

    %% External Services
    subgraph "External Services"
        G["Git Repositories"]:::external
        HS["Scanning Service (Hyperion)"]:::external
    end

    %% Deployment & Infrastructure
    subgraph "Deployment & Infrastructure"
        DC["Docker Containers"]:::deployment
        K["Kubernetes (Helm)"]:::deployment
        H["Helm Charts"]:::deployment
        DCOM["Docker Compose"]:::deployment
        M["Makefile"]:::deployment
        MW["Maven Wrapper"]:::deployment
    end

    %% Connections
    U -->|"interacts"| F
    F -->|"REST/WebSocket"| B
    B -->|"stores/retrieves"| DB
    B -->|"handles_scanning"| S
    B -->|"handles_compliance"| C
    B -->|"manages_data"| DCI
    B -->|"fetches_clones"| G
    B -->|"invokes_scanning"| HS
    DC --- F
    DC --- B
    K --- F
    K --- B
    H --- DB
    DCOM --- DB
    M --- B
    MW --- B

    %% Click Events
    click F "https://github.com/ibm/cbomkit/tree/main/frontend/"
    click DF "https://github.com/ibm/cbomkit/tree/main/frontend/docker/Dockerfile"
    click NC "https://github.com/ibm/cbomkit/blob/main/frontend/docker/etc/nginx/conf.d/default.conf"
    click P "https://github.com/ibm/cbomkit/blob/main/pom.xml"
    click J "https://github.com/ibm/cbomkit/tree/main/src/main/java/com/ibm/"
    click O "https://github.com/ibm/cbomkit/blob/main/openapi.yaml"
    click H "https://github.com/ibm/cbomkit/blob/main/chart/Chart.yaml"
    click DCOM "https://github.com/ibm/cbomkit/blob/main/docker-compose.yaml"
    click M "https://github.com/ibm/cbomkit/tree/main/Makefile"
    click MW "https://github.com/ibm/cbomkit/tree/main/mvnw"

    %% Styles
    classDef user fill:#ffcccc,stroke:#000000,stroke-width:2px;
    classDef frontend fill:#ccffcc,stroke:#000000,stroke-width:2px;
    classDef backend fill:#ccccff,stroke:#000000,stroke-width:2px;
    classDef backendFile fill:#e0ccff,stroke:#000000,stroke-width:2px;
    classDef backendModule fill:#b3cde0,stroke:#000000,stroke-width:2px;
    classDef database fill:#ffffcc,stroke:#000000,stroke-width:2px;
    classDef external fill:#ffccff,stroke:#000000,stroke-width:2px;
    classDef deployment fill:#ccffff,stroke:#000000,stroke-width:2px;
```
