# hyperledger/fabric-samples architecture

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

## Overview

- Fabric Network Infrastructure – include the ordering service, peers, certificate authorities (CAs), and optionally the components for admin and fabric-network configuration. Note that this is represented in the “test-network”, “test-network-k8s”, and “test-network-nano-bash” directories.
- Chaincode (Smart Contracts) – show the various chaincode implementations used for asset transfers, private data, state-based endorsement, events, auctions, token services (ERC-20, ERC-721, ERC-1155, UTXO tokens, etc.). Since there are multiple asset transfer samples (asset-transfer-basic, asset-transfer-ledger-queries, asset-transfer-private-data, asset-transfer-secured-agreement, asset-transfer-sbe, asset-transfer-events, asset-transfer-abac), make it clear that these chaincodes encapsulate business logic on the ledger.
- Application Gateways and Client Applications – indicate the client-side or gateway applications that interact with the Fabric network. There are implementations in various languages (Go, Java, JavaScript, TypeScript) showing how external applications engage with the network using Fabric SDKs. For instance, directories like asset-transfer-basic/application-gateway-* or full-stack-asset-transfer-guide/applications are examples.
- Full-Stack / Frontend Applications – Incorporate the full-stack asset transfer guide sample which not only covers chaincode and backend but also a complete frontend (Angular-based in this case) to interact with the blockchain.
- Infrastructure/Deployment Configurations – the repository holds numerous infrastructure-related files such as those for Kubernetes ("test-network-k8s", “infrastructure/”), Docker Compose files (e.g., in “test-network”, “compose”), and playbooks for chaincode deployment. Represent these elements to show how the environment is bootstrapped and managed.
- Auxiliary Tools and Scripts – represent CI/CD pipelines (GitHub workflows in .github/workflows, CI scripts in the ci folder), testing scripts, and utilities for enrollment, chaincode packaging and network management. Although not the core application logic, these components support the overall system.

##### Relationships and data flow
- That chaincode is installed on peers within the network and that smart contracts interact with the underlying ledger.
- That chaincode and client applications are versioned and that some components (like use of private data collections or state-based endorsement) require additional communication and policy enforcement.

##### Architectural patterns and design principles
- Separation of concerns: Clearly differentiate transaction processing (chaincode on peers) from application logic (client applications) and external orchestration (deployment scripts and network configuration).
- Multi-language support: Represent that the same underlying business logic is implemented in multiple languages to support varied developer ecosystems.
- Extensibility and modularity: Show that separate modules (asset transfer, auctions, token models, off-chain data) can be added or substituted while sharing the core Fabric network infrastructure.
- Use of external configuration and CI/CD pipelines that manage deployment and testing across environments.

##### Relevant technologies, frameworks, and libraries
- Fabric SDKs and CLI tools.
- Docker and Kubernetes (for containerization and orchestration).
- Programming languages and build tools (e.g., Go modules, Java Gradle/Maven, Node/npm, TypeScript configurations).
- CI/CD workflows (GitHub Actions, shell scripts in the “ci” folder, playbooks in the “infrastructure” folder).

##### Directions to include the following elements
- Clear, distinct labels for each major component – for example, “Fabric Network (Orderer, Peer, CA)”, “Chaincode – Asset Transfer (Basic, Private Data, ABAC, etc.)”, “Frontend Application (Angular, Full-stack Guide)”, “API Gateway” and “Deployment Infrastructure (Docker/K8s)”.
- Annotations for key integration points (e.g., “Chaincode endorsement” between peers, “Fabric CA” for identity management, “CI/CD pipelines” that automate testing and deployment).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Gateways and Client Applications"
        AG1["Asset Transfer Basic - Gateway (Go)"]:::app
        AG2["Asset Transfer Basic - Gateway (Java)"]:::app
        AG3["Asset Transfer Basic - Gateway (JavaScript)"]:::app
        AG4["Asset Transfer Basic - Gateway (TypeScript)"]:::app
        AG5["Asset Transfer Events - Gateway (Go)"]:::app
        AG6["Asset Transfer Events - Gateway (Java)"]:::app
        AG7["Asset Transfer Events - Gateway (TypeScript)"]:::app
        AG8["Asset Transfer Ledger Queries - Gateway (Java)"]:::app
        AG9["Asset Transfer Ledger Queries - Gateway (JavaScript)"]:::app
        AG10["Asset Transfer Private Data - Gateway (Go)"]:::app
        AG11["Asset Transfer Private Data - Gateway (TypeScript)"]:::app
    end

    subgraph "Full-Stack / Frontend Applications"
        FS1["Full-stack Asset Transfer - Frontend (Angular)"]:::frontend
        FS2["Full-stack Asset Transfer - Trader (TypeScript)"]:::frontend
    end

    %% Fabric Layer
    subgraph "Fabric Network Infrastructure"
        FN1["Test Network"]:::fabric
        FN2["Test Network K8s"]:::fabric
        FN3["Test Network Nano Bash"]:::fabric
    end

    %% Chaincode Layer
    subgraph "Chaincode (Smart Contracts)"
        CC1["Asset Transfer Basic (Chaincode-Go)"]:::chaincode
        CC2["Asset Transfer ABAC (Chaincode-Go)"]:::chaincode
        CC3["Asset Transfer Private Data (Chaincode-Go)"]:::chaincode
        CC4["Asset Transfer SBE (Chaincode-Java)"]:::chaincode
        CC5["Asset Transfer SBE (Chaincode-TypeScript)"]:::chaincode
        CC6["Asset Transfer Secured Agreement (Chaincode-Go)"]:::chaincode
        CC7["Asset Transfer Events (Chaincode-Go)"]:::chaincode
        CC8["Asset Transfer Events (Chaincode-Java)"]:::chaincode
        CC9["Token ERC-20 (Chaincode-Go)"]:::chaincode
        CC10["Token ERC-20 (Chaincode-Java)"]:::chaincode
        CC11["Token ERC-1155 (Chaincode-Go)"]:::chaincode
        CC12["Token ERC-721 (Chaincode-Go)"]:::chaincode
        CC13["Token ERC-721 (Chaincode-Java)"]:::chaincode
        CC14["Token UTXO (Chaincode-Go)"]:::chaincode
    end

    %% Deployment Infrastructure
    subgraph "Deployment Infrastructure (Configurations)"
        Dep1["Deployment: Docker Compose & K8s Configurations"]:::deployment
        Dep2["Full-stack Infrastructure Config"]:::deployment
    end

    %% Auxiliary Tools and Scripts
    subgraph "Auxiliary Tools and Scripts"
        Aux1["CI/CD Pipelines (.github/workflows)"]:::auxiliary
        Aux2["CI Scripts (ci/scripts)"]:::auxiliary
        Aux3["Token SDK Scripts (token-sdk/scripts)"]:::auxiliary
        Aux4["Utility Scripts (test-network/scripts)"]:::auxiliary
    end

    %% Connections from Applications to Fabric
    AG1 -->|"invoke"| FN1
    FS1 -->|"sendTx"| FN1

    %% Fabric to Chaincode relationship (chaincode installed on peers)
    FN1 -->|"installed_on"| CC1

    %% Additional invocation relationships from Applications to Chaincode
    AG3 -->|"invokes"| CC1
    FS1 -->|"submitsTx"| CC1

    %% Deployment and Auxiliary relationships
    Dep1 -->|"deploys"| FN1
    Aux1 -->|"manages"| Dep1

    %% Styles
    classDef fabric fill:#ffeaa7,stroke:#d35400,stroke-width:2px;
    classDef chaincode fill:#d1f2eb,stroke:#16a085,stroke-width:2px;
    classDef app fill:#f6e58d,stroke:#f9ca24,stroke-width:2px;
    classDef frontend fill:#ff7675,stroke:#c23616,stroke-width:2px;
    classDef deployment fill:#74b9ff,stroke:#0984e3,stroke-width:2px;
    classDef auxiliary fill:#55efc4,stroke:#00b894,stroke-width:2px;

    %% Click Events for Fabric Network Infrastructure
    click FN1 "https://github.com/hyperledger/fabric-samples/blob/main/test-network/README.md"
    click FN2 "https://github.com/hyperledger/fabric-samples/blob/main/test-network-k8s/README.md"
    click FN3 "https://github.com/hyperledger/fabric-samples/blob/main/test-network-nano-bash/README.md"

    %% Click Events for Chaincode (Smart Contracts)
    click CC1 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-basic/chaincode-go"
    click CC2 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-abac/chaincode-go"
    click CC3 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-private-data/chaincode-go"
    click CC4 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-sbe/chaincode-java"
    click CC5 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-sbe/chaincode-typescript"
    click CC6 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-secured-agreement/chaincode-go"
    click CC7 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-events/chaincode-go"
    click CC8 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-events/chaincode-java"
    click CC9 "https://github.com/hyperledger/fabric-samples/tree/main/token-erc-20/chaincode-go"
    click CC10 "https://github.com/hyperledger/fabric-samples/tree/main/token-erc-20/chaincode-java"
    click CC11 "https://github.com/hyperledger/fabric-samples/tree/main/token-erc-1155/chaincode-go"
    click CC12 "https://github.com/hyperledger/fabric-samples/tree/main/token-erc-721/chaincode-go"
    click CC13 "https://github.com/hyperledger/fabric-samples/tree/main/token-erc-721/chaincode-java"
    click CC14 "https://github.com/hyperledger/fabric-samples/tree/main/token-utxo/chaincode-go"

    %% Click Events for Application Gateways and Client Applications
    click AG1 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-basic/application-gateway-go"
    click AG2 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-basic/application-gateway-java"
    click AG3 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-basic/application-gateway-javascript"
    click AG4 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-basic/application-gateway-typescript"
    click AG5 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-events/application-gateway-go"
    click AG6 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-events/application-gateway-java"
    click AG7 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-events/application-gateway-typescript"
    click AG8 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-ledger-queries/application-java"
    click AG9 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-ledger-queries/application-javascript"
    click AG10 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-private-data/application-gateway-go"
    click AG11 "https://github.com/hyperledger/fabric-samples/tree/main/asset-transfer-private-data/application-gateway-typescript"

    %% Click Events for Full-Stack / Frontend Applications
    click FS1 "https://github.com/hyperledger/fabric-samples/tree/main/full-stack-asset-transfer-guide/applications/frontend"
    click FS2 "https://github.com/hyperledger/fabric-samples/tree/main/full-stack-asset-transfer-guide/applications/trader-typescript"

    %% Click Events for Deployment Infrastructure
    click Dep1 "https://github.com/hyperledger/fabric-samples/tree/main/test-network/compose"
    click Dep2 "https://github.com/hyperledger/fabric-samples/tree/main/full-stack-asset-transfer-guide/infrastructure"

    %% Click Events for Auxiliary Tools and Scripts
    click Aux1 "https://github.com/hyperledger/fabric-samples/tree/main/.github/workflows"
    click Aux2 "https://github.com/hyperledger/fabric-samples/tree/main/ci/scripts"
    click Aux3 "https://github.com/hyperledger/fabric-samples/tree/main/token-sdk/scripts"
    click Aux4 "https://github.com/hyperledger/fabric-samples/tree/main/test-network/scripts"
```
