# onflow/flow-go architecture

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

- Interactive diagram: https://gitdiagram.com/onflow/flow-go
- Repository: https://github.com/onflow/flow-go

## Overview

##### Main Components of the System
- Node Types: Represent different node roles such as the Access Node, Collection Node, Consensus Node, Execution Node, Verification Node, Observer Service, and additional support components like HotStuff consensus modules, storage layers, ledger, and cryptographic modules.
- Network Layer: The networking module is organized into directories such as /network, /network/p2p, /network/message, and associated codec and protocol packages. This layer is responsible for inter-node communication.
- Consensus and Communication Middleware: Components for the HotStuff consensus (located in /consensus/hotstuff) and modules for peer-to-peer communication, including message brokers, connection managers, rate-limiters, and scoring systems.
- Internal Communication Services: Within each node, there is an internal messaging system that interfaces with the network stack and handles incoming queries (e.g., access API RPC calls) and outgoing consensus or state-sync messages.

##### Relationships and Interactions Between Components
- Each node has its dedicated instance with both a business logic component (depending on its role) and a networking stack.
- The nodes communicate over a peer-to-peer (P2P) network that is implemented via a combination of gRPC for structured request–response communication as well as gossip protocols for broadcasting state updates.
- The networking layer uses protocol definitions (located in /network/message/message.proto, /network/message/ping.proto, etc.) to define the structure of messages exchanged between nodes. These include serialized payloads, consensus votes, block proposals, state synchronization requests, and responses.
- The network layer further distinguishes between control and data channels. Control messages (such as connection management, peer scoring, and health pings) ensure that the P2P overlay is maintained, while data messages carry blockchain-specific messages (such as block proposals, transaction batches, and verifications).

##### Network Protocol and Request/Response Types
- Protocol Overview: The network protocol essentially combines a gossip-based distribution mechanism with direct RPC-style request–response interactions. Nodes use well-defined message types (as defined in the protobuf files in /network/message) for consistency.
- Request/Response Examples:
- When an Access Node queries for a block or transaction, it sends a request over a gRPC channel. The receiving node (for example, an Execution Node or a Collection Node) responds with the requested block details, transaction status, or state data.
- In the consensus process, nodes exchange messages such as block proposals, quorum certificates, votes, and timeout notifications. These messages are usually broadcast using the gossip protocol—a many-to-many pattern where each peer both sends and receives these messages asynchronously.
- For state synchronization, a follower node might send a “state query” request to the leader or primary node, and the remote node responds with the relevant snapshot data.
- The networking code (e.g., implementations under /network/codec and /network/p2p) often includes message encoding/decoding routines (using CBOR, protobuf, or RLP as seen in the file tree) to guarantee that the data is serialized correctly before transmission.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Node Roles
    subgraph "Node Roles"
        AccessNode["Access Node"]:::nodeRole
        CollectionNode["Collection Node"]:::nodeRole
        ConsensusNode["Consensus Node"]:::nodeRole
        HotStuff["HotStuff Consensus"]:::nodeRole
        ExecutionNode["Execution Node"]:::nodeRole
        VerificationNode["Verification Node"]:::nodeRole
        ObserverService["Observer Service"]:::nodeRole
    end

    %% Internal Communication Services
    subgraph "Internal Communication Services"
        AccessRPC["Access RPC"]:::internal
        Broadcaster["Broadcaster"]:::internal
        Notifier["Notifier"]:::internal
    end

    %% Network Layer
    subgraph "Network Layer"
        P2P["P2P Module"]:::network
        MessageProtocol["Message Protocol (protobuf)"]:::network
        Codec["Codec & Serialization (CBOR, RLP)"]:::network
    end

    %% Relationships - Node Roles to Network Layer
    AccessNode -->|"gRPC:Query/GetBlock"| P2P
    P2P -->|"gRPC:Response/Block"| ExecutionNode
    ConsensusNode -->|"Gossip:Proposal/Vote( protobuf)"| P2P
    P2P -->|"Broadcast"| AccessNode
    CollectionNode -->|"StateSync:Request(JSON/CBOR)"| P2P
    P2P -->|"StateSync:Response(JSON/CBOR)"| ExecutionNode
    ExecutionNode -->|"gRPC:SubmitTx"| P2P
    P2P -->|"Gossip:BlockUpdates"| ObserverService

    %% Internal Communication within Access Node
    AccessNode -->|"InternalRPC"| AccessRPC
    AccessRPC -->|"NotifyUpdate"| Broadcaster
    Broadcaster -->|"SendNotifications"| Notifier

    %% Consensus Internal Relationship
    ConsensusNode -->|"uses"| HotStuff

    %% Network Layer Internal Relationships
    Codec -->|"Encodes/Decodes"| MessageProtocol

    %% Click Events for Node Roles
    click AccessNode "https://github.com/onflow/flow-go/blob/master/cmd/access/main.go"
    click CollectionNode "https://github.com/onflow/flow-go/blob/master/cmd/collection/main.go"
    click ConsensusNode "https://github.com/onflow/flow-go/blob/master/cmd/consensus/main.go"
    click HotStuff "https://github.com/onflow/flow-go/tree/master/consensus/hotstuff/"
    click ExecutionNode "https://github.com/onflow/flow-go/blob/master/cmd/execution/main.go"
    click VerificationNode "https://github.com/onflow/flow-go/blob/master/cmd/verification/main.go"
    click ObserverService "https://github.com/onflow/flow-go/blob/master/cmd/observer/main.go"

    %% Click Events for Network Layer
    click P2P "https://github.com/onflow/flow-go/tree/master/network/p2p/"
    click MessageProtocol "https://github.com/onflow/flow-go/tree/master/network/message/"
    click Codec "https://github.com/onflow/flow-go/tree/master/network/codec/"

    %% Click Events for Internal Communication Services
    click AccessRPC "https://github.com/onflow/flow-go/tree/master/engine/access/rpc/"
    click Broadcaster "https://github.com/onflow/flow-go/blob/master/engine/broadcaster.go"
    click Notifier "https://github.com/onflow/flow-go/blob/master/engine/notifier.go"

    %% Styles
    classDef nodeRole fill:#e0f7fa,stroke:#006064,stroke-width:2px;
    classDef network fill:#ffe0b2,stroke:#e65100,stroke-width:2px;
    classDef internal fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px;
```
