# hyperledger/fabric architecture

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

- Interactive diagram: https://gitdiagram.com/hyperledger/fabric
- Repository: https://github.com/hyperledger/fabric

## Overview

##### Core Components
- Orderer Service: Represented by the “orderer” directory and its subdirectories (including consensus mechanisms like Raft, SmartBFT, etc.). The orderer provides the ordering service which collects endorsed transactions and forms blocks.
- Peer Nodes: Found in directories such as “peer”, “core/peer” and “gossip”. Peers are responsible for executing chaincode (smart contracts), endorsing transactions, maintaining the ledger, and committing blocks.
- Chaincode (Smart Contracts): The lifecycle, build, and deployment logic are contained in the “core/chaincode”, “ccaas_builder” and “integration/chaincode” directories. These components handle the packaging, endorsement, and runtime container management of chaincode.
- Membership Service Provider (MSP): The “msp” directory and related files deal with identity management, certificate validation, and revocation that secure communication between entities.
- Gossip and Communication: The “gossip” directories (and related submodules under “gossip/comm”, “gossip/gossip”, etc.) implement peer-to-peer message dissemination, including block and state sharing.
- Configuration & Channel Management: Components in “common/channelconfig”, “core/config” and parts of “common/configtx” support channel creation, configuration updates, and policy enforcement.
- Auxiliary Tools and Integration: Directories like “discovery”, “integration”, “docs”, “scripts”, and “vagrant” support tools and tests which help illustrate real-world deployment and network interaction.

##### Relationships and Data Flow
- External Clients/APIs interact with the network via SDKs that trigger chaincode invocations.
- The client submits a transaction proposal to one or several endorser peers.
- Endorser peers simulate the transaction by invoking the chaincode and return endorsements.
- The client collects endorsements and submits a transaction to the ordering service.
- The ordering service (implemented using one of several consensus protocols) orders transactions and forms blocks.
- The generated blocks are distributed to all peers via the gossip network, where peers validate and commit the blocks to their ledger.
- Identity and access management (via MSP) cross-cuts these interactions to ensure proper authentication and authorization.

##### Architectural Patterns and Modularity
- Modular "plug-and-play" design: Different consensus mechanisms, chaincode runtimes, and cryptography modules can be interchanged.
- Clear separation of concerns: Orderers manage transaction ordering, peers handle transaction execution/validation/commitment, and MSP modules secure communications.
- Decentralized and scalable communications via the gossip protocol: Peers disseminate updates and ledger information in a decentralized way.
- Configuration management and dynamic channel updates: Configurations are handled separately from the transaction processing path to allow instantiation of multiple channels.

##### Technologies, Frameworks, or Libraries
- Written in Go, as evidenced by the “go.mod” files.
- Utilizes container-based chaincode execution (with directories like “ccaas_builder”, “core/container”).
- Uses common libraries for cryptography, network communication, and gRPC (as shown in “gossip/comm”, “internal/pkg/comm”).

##### Final Practical Steps
- Validate that every component seen in the file tree has a representation or is clearly part of a higher-level block.
- Directional flows that denote data and transaction propagation are accurate.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Components
    Client["Client Applications/SDK"]:::client
    MSP["MSP/Identity Management"]:::msp
    Orderer["Orderer Service"]:::orderer
    Gossip["Gossip Network"]:::gossip

    %% Peer Nodes Subgraph
    subgraph "Peer Nodes"
        PeerCmd["Peer Node (cmd/peer)"]:::peer
        PeerCore["Peer Node (core/peer)"]:::peer
    end

    %% Chaincode Subgraph
    subgraph "Chaincode (Smart Contracts)"
        ChaincodeCore["Chaincode: core/chaincode"]:::chaincode
        ChaincodeBuilder["Chaincode Builder: ccaas_builder"]:::chaincode
        ChaincodeIntegration["Integration Chaincode: integration/chaincode"]:::chaincode
    end

    %% Configuration & Channel Management Subgraph
    subgraph "Configuration & Channel Management"
        ConfigChannel["Channel Config: common/channelconfig"]:::config
        ConfigTx["ConfigTx: common/configtx"]:::config
        ConfigGen["Config Generator: cmd/configtxgen"]:::config
    end

    %% Auxiliary Tools & Integration Subgraph
    subgraph "Auxiliary Tools & Integration"
        ToolDiscovery["Discovery: discovery"]:::aux
        ToolIntegration["Integration Tools: integration"]:::aux
        ToolDocs["Documentation: docs"]:::aux
        ToolScripts["Scripts: scripts"]:::aux
        ToolVagrant["Vagrant: vagrant"]:::aux
    end

    %% Relationships - Transaction Flow and Communications
    Client -->|"tx_proposal"| PeerCmd
    Client -->|"tx_proposal"| PeerCore

    PeerCmd -->|"endorsement"| Client
    PeerCore -->|"endorsement"| Client

    Client -->|"submit_tx"| Orderer
    Orderer -->|"distribute_blocks"| PeerCmd
    Orderer -->|"distribute_blocks"| PeerCore

    PeerCmd -->|"invoke_chaincode"| ChaincodeCore
    ChaincodeCore -->|"returns_response"| PeerCmd

    PeerCore -->|"invoke_chaincode"| ChaincodeBuilder
    ChaincodeBuilder -->|"returns_response"| PeerCore

    PeerCmd -->|"invoke_chaincode"| ChaincodeIntegration
    ChaincodeIntegration -->|"returns_response"| PeerCmd

    PeerCmd -->|"gossip"| Gossip
    PeerCore -->|"gossip"| Gossip
    Gossip -->|"peer_update"| PeerCmd
    Gossip -->|"peer_update"| PeerCore

    ConfigChannel -->|"config_update"| Orderer
    ConfigTx -->|"config_update"| Orderer
    ConfigGen -->|"generate_config"| Orderer

    ConfigChannel -->|"config_update"| PeerCmd
    ConfigTx -->|"config_update"| PeerCmd
    ConfigGen -->|"generate_config"| PeerCmd

    ConfigChannel -->|"config_update"| PeerCore
    ConfigTx -->|"config_update"| PeerCore
    ConfigGen -->|"generate_config"| PeerCore

    %% Security Associations via MSP (dashed connections)
    Client ---|"secures"| MSP
    PeerCmd ---|"secures"| MSP
    PeerCore ---|"secures"| MSP
    Orderer ---|"secures"| MSP
    Gossip ---|"secures"| MSP
    ChaincodeCore ---|"secures"| MSP
    ChaincodeBuilder ---|"secures"| MSP
    ChaincodeIntegration ---|"secures"| MSP
    ConfigChannel ---|"secures"| MSP
    ConfigTx ---|"secures"| MSP
    ConfigGen ---|"secures"| MSP

    %% Click Events for Component Mappings
    click Orderer "https://github.com/hyperledger/fabric/tree/main/orderer"
    click PeerCmd "https://github.com/hyperledger/fabric/tree/main/cmd/peer"
    click PeerCore "https://github.com/hyperledger/fabric/tree/main/core/peer"
    click ChaincodeCore "https://github.com/hyperledger/fabric/tree/main/core/chaincode"
    click ChaincodeBuilder "https://github.com/hyperledger/fabric/tree/main/ccaas_builder"
    click ChaincodeIntegration "https://github.com/hyperledger/fabric/tree/main/integration/chaincode"
    click MSP "https://github.com/hyperledger/fabric/tree/main/msp"
    click Gossip "https://github.com/hyperledger/fabric/tree/main/gossip"
    click ConfigChannel "https://github.com/hyperledger/fabric/tree/main/common/channelconfig"
    click ConfigTx "https://github.com/hyperledger/fabric/tree/main/common/configtx"
    click ConfigGen "https://github.com/hyperledger/fabric/tree/main/cmd/configtxgen"
    click ToolDiscovery "https://github.com/hyperledger/fabric/tree/main/discovery"
    click ToolIntegration "https://github.com/hyperledger/fabric/tree/main/integration"
    click ToolDocs "https://github.com/hyperledger/fabric/tree/main/docs"
    click ToolScripts "https://github.com/hyperledger/fabric/tree/main/scripts"
    click ToolVagrant "https://github.com/hyperledger/fabric/tree/main/vagrant"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef orderer fill:#87CEFA,stroke:#000,stroke-width:2px;
    classDef peer fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef chaincode fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef msp fill:#D8BFD8,stroke:#000,stroke-width:2px;
    classDef gossip fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef config fill:#E0FFFF,stroke:#000,stroke-width:2px;
    classDef aux fill:#F5F5DC,stroke:#000,stroke-width:2px;
```
