# bloxbean/cardano-client-lib architecture

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

- Interactive diagram: https://gitdiagram.com/bloxbean/cardano-client-lib
- Repository: https://github.com/bloxbean/cardano-client-lib

## Overview

This project is a full‐featured Java client library for interacting with the Cardano blockchain. It is highly modular, composed of many modules (each with its own subpackage and even its own build file) that span a wide range of concerns—from low‐level crypto and address management through transaction specification, metadata, and even support for multiple blockchain “backend” providers (e.g. Blockfrost, Koios, Ogmios/Kupo) as well as advanced modules such as CIP implementations and QuickTx. In other words, the library uses a layered, “plug‐in” style architecture, where each module is independent but interdependent through imported common utilities and defined APIs.

##### Main Components
- Core Library and Utilities: Represent modules such as “common”, “common-spec”, “crypto”, and “address”. These modules provide basic building blocks such as CBOR serialization, cryptography (Bip32, Bip39, CIP1852), and address derivation.
- Transaction and Metadata Modules: Include “transaction-spec”, “metadata” and “core/core-api” modules that help build, serialize, and sign blockchain transactions.
- Plutus and CIP Modules: Illustrate the “plutus” module to support smart contract serialization and on-chain script interactions. Also, include the umbrella “cip” module and its sub-modules (cip8, cip20, cip25, cip27, cip30, cip67, cip68) that add support for Cardano Improvement Proposals.
- Advanced Transaction Builders: Represent the “quicktx”, “function”, “coinselection” and other supportive modules that provide high-level, composable functions as well as customized coin selection and transaction assembly strategies.
- Supporting/Ancillary Modules: Identify other modules such as “annotation-processor”, “hd-wallet”, “governance”, “supplier” (which bring in external interactions or domain-specific functionality like wallet management or governance).

##### Specify Relationships and Dependencies
- Directional links from higher-level modules (like “core” and “core-api”) to lower-level ones (such as “common”, “crypto”, “common-spec”, “address”, “metadata”). Indicate that “transaction-spec” and “plutus” depend on these foundational modules.

##### Architectural Patterns and Design Principles
- Modularity and Separation of Concerns: Show each module as a clearly labeled block that does one thing (e.g., “plutus” handles smart contract logic, “coinselection” handles UTXO algorithm choices).

##### Relevant Technologies and Libraries
- That the project uses Gradle for builds (and even has Jenkins and GitHub Actions for CI/CD).
- That the library is built for Java 11.

– Clearly labeled components (e.g., “Cardano Client Core”, “Crypto & Address Utils”, “Transaction Spec”, “Metadata”, “Plutus Module”).

##### Overall
– Begin by sketching the broad layers: Bottom (Utilities and Fundamental Libraries), Middle (Core Domain Logic for transactions, metadata, addresses, cryptography), Upper (Specialized Modules supporting smart contracts and CIP standards), and External Integration (Backend providers connecting to the Cardano network).

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Utilities and Fundamental Libraries
    subgraph "Utilities and Fundamental Libraries"
        common["common"]:::utilities
        commonSpec["common-spec"]:::utilities
        crypto["crypto"]:::utilities
        address["address"]:::utilities
    end

    %% Core Domain Logic
    subgraph "Core Domain Logic"
        transactionSpec["transaction-spec"]:::core
        metadata["metadata"]:::core
        coreApi["Core API"]:::core
    end

    %% Specialized Modules
    subgraph "Specialized Modules"
        plutus["plutus"]:::specialized
        subgraph "CIP Modules"
            cip8["CIP8"]:::specialized
            cip20["CIP20"]:::specialized
            cip25["CIP25"]:::specialized
            cip27["CIP27"]:::specialized
            cip30["CIP30"]:::specialized
            cip67["CIP67"]:::specialized
            cip68["CIP68"]:::specialized
        end
    end

    %% Transaction Handling
    subgraph "Transaction Handling"
        quicktx["QuickTx"]:::tx
        func["Function"]:::tx
        coinselection["Coinselection"]:::tx
    end

    %% Backend Integration
    subgraph "Backend Integration"
        backend["Backend API"]:::backendStyle
        blockfrost["Blockfrost Backend"]:::backendStyle
        koios["Koios Backend"]:::backendStyle
        ogmios["Ogmios/Kupo Backend"]:::backendStyle
    end

    %% Supporting Modules
    subgraph "Supporting Modules"
        annotationProcessor["Annotation Processor"]:::supporting
        hdWallet["HD Wallet"]:::supporting
        governance["Governance"]:::supporting
        subgraph "Supplier Modules"
            supplier["Supplier"]:::supporting
            kupoSupplier["Kupo Supplier"]:::supporting
            ogmiosSupplier["Ogmios Supplier"]:::supporting
        end
    end

    %% Dependency Relationships

    %% Foundational dependencies for Core Domain
    address -->|"dependsOn"| common
    address -->|"dependsOn"| crypto
    metadata -->|"dependsOn"| common
    metadata -->|"dependsOn"| crypto
    transactionSpec -->|"dependsOn"| common
    transactionSpec -->|"dependsOn"| crypto
    transactionSpec -->|"dependsOn"| commonSpec

    coreApi -->|"dependsOn"| common
    coreApi -->|"dependsOn"| crypto
    coreApi -->|"dependsOn"| commonSpec
    coreApi -->|"dependsOn"| address
    coreApi -->|"dependsOn"| metadata

    %% Specialized Modules dependencies
    plutus -->|"dependsOn"| coreApi
    cip8 -->|"dependsOn"| coreApi
    cip20 -->|"dependsOn"| coreApi
    cip25 -->|"dependsOn"| coreApi
    cip27 -->|"dependsOn"| coreApi
    cip30 -->|"dependsOn"| coreApi
    cip67 -->|"dependsOn"| coreApi
    cip68 -->|"dependsOn"| coreApi

    %% Transaction Handling dependencies
    quicktx -->|"calls"| coreApi
    quicktx -->|"calls"| backend
    func -->|"calls"| coreApi
    func -->|"calls"| backend
    coinselection -->|"calls"| coreApi

    %% Backend Integration relationships
    backend -->|"implementedBy"| blockfrost
    backend -->|"implementedBy"| koios
    backend -->|"implementedBy"| ogmios

    %% Supporting Modules relationship (Supplier uses Backend API)
    supplier -->|"utilizes"| backend

    %% Styles
    classDef utilities fill:#ade6a9,stroke:#333,stroke-width:2px;
    classDef core fill:#a3c4f3,stroke:#333,stroke-width:2px;
    classDef specialized fill:#f3a3c4,stroke:#333,stroke-width:2px;
    classDef tx fill:#f3e9a3,stroke:#333,stroke-width:2px;
    classDef backendStyle fill:#d6a3f3,stroke:#333,stroke-width:2px;
    classDef supporting fill:#f3d6a3,stroke:#333,stroke-width:2px;

    %% Click Events for Core Library and Utilities
    click common "https://github.com/bloxbean/cardano-client-lib/tree/master//common"
    click commonSpec "https://github.com/bloxbean/cardano-client-lib/tree/master//common-spec"
    click crypto "https://github.com/bloxbean/cardano-client-lib/tree/master//crypto"
    click address "https://github.com/bloxbean/cardano-client-lib/tree/master//address"

    %% Click Events for Transaction and Metadata Modules
    click transactionSpec "https://github.com/bloxbean/cardano-client-lib/tree/master//transaction-spec"
    click metadata "https://github.com/bloxbean/cardano-client-lib/tree/master//metadata"
    click coreApi "https://github.com/bloxbean/cardano-client-lib/tree/master//core-api"
    click coreApi "https://github.com/bloxbean/cardano-client-lib/tree/master//core"

    %% Click Events for Backend Integration Layers
    click backend "https://github.com/bloxbean/cardano-client-lib/tree/master//backend"
    click blockfrost "https://github.com/bloxbean/cardano-client-lib/tree/master//backend-modules/blockfrost"
    click koios "https://github.com/bloxbean/cardano-client-lib/tree/master//backend-modules/koios"
    click ogmios "https://github.com/bloxbean/cardano-client-lib/tree/master//backend-modules/ogmios"

    %% Click Events for Plutus and CIP Modules
    click plutus "https://github.com/bloxbean/cardano-client-lib/tree/master//plutus"
    click cip8 "https://github.com/bloxbean/cardano-client-lib/tree/master//cip/cip8"
    click cip20 "https://github.com/bloxbean/cardano-client-lib/tree/master//cip/cip20"
    click cip25 "https://github.com/bloxbean/cardano-client-lib/tree/master//cip/cip25"
    click cip27 "https://github.com/bloxbean/cardano-client-lib/tree/master//cip/cip27"
    click cip30 "https://github.com/bloxbean/cardano-client-lib/tree/master//cip/cip30"
    click cip67 "https://github.com/bloxbean/cardano-client-lib/tree/master//cip/cip67"
    click cip68 "https://github.com/bloxbean/cardano-client-lib/tree/master//cip/cip68"

    %% Click Events for Advanced Transaction Builders
    click quicktx "https://github.com/bloxbean/cardano-client-lib/tree/master//quicktx"
    click func "https://github.com/bloxbean/cardano-client-lib/tree/master//function"
    click coinselection "https://github.com/bloxbean/cardano-client-lib/tree/master//coinselection"

    %% Click Events for Supporting/Ancillary Modules
    click annotationProcessor "https://github.com/bloxbean/cardano-client-lib/tree/master//annotation-processor"
    click hdWallet "https://github.com/bloxbean/cardano-client-lib/tree/master//hd-wallet"
    click governance "https://github.com/bloxbean/cardano-client-lib/tree/master//governance"
    click supplier "https://github.com/bloxbean/cardano-client-lib/tree/master//supplier"
    click kupoSupplier "https://github.com/bloxbean/cardano-client-lib/tree/master//supplier/kupo-supplier"
    click ogmiosSupplier "https://github.com/bloxbean/cardano-client-lib/tree/master//supplier/ogmios-supplier"
```
