# algorand/go-algorand architecture

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

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

## Overview

##### Project type and purpose
- A high‐performance, permissionless blockchain node in Go (Algorand).
- Provides core libraries (crypto, data models, protocol rules), two daemons (algod, kmd), CLI tools, SDK, testing and deployment scripts.

##### File structure
- Core packages:
– crypto: hashing, signatures, VRFs
– protocol, config: consensus constants, network tags, parameters
– data: account, transaction, block, ledger‐state types
– network: P2P mesh, WebSocket connections, RPC subpackage
– agreement: BFT consensus protocol
– ledger: state machine, block application, storage drivers
– node: application wiring (initialization/shutdown)
- Daemons:
– daemon/algod: integrates core, network, consensus, ledger, exposes REST API
– daemon/kmd: key‐management service, REST API for signing
- Interfaces & CLI: cmd, libgoal, tools/*
- Deployment & orchestration: docker/, nodecontrol/, netdeploy/
- Utilities: logging/, util/, extensive scripts/ and test/ suites

- Crypto Layer
- Protocol & Config layer
- Data Models (in‐memory types)
- Networking Layer (P2P + RPC)
- Agreement Engine (BFT service)
- Ledger State Machine & Storage
- Daemon: algod
- Daemon: kmd
- CLI/SDK clients
- Deployment orchestrator (Docker, nodecontrol, netdeploy)
1. CLI/SDK → HTTP REST → algod API handler
2. Incoming transactions → transaction pool → agreement engine
3. Consensus rounds exchange messages over P2P mesh
4. New block → ledger application → storage (SQLite/Pebble) → updated state
5. RPC queries → ledger query layer → response
6. Signing requests from CLI → kmd → returns signed TX
7. Deployment scripts launch/configure multiple algod/kmd instances
c. Architectural patterns & principles:
- Layered separation: crypto → protocol → consensus → storage → API
- Modular daemons: isolate key management (kmd) from core node (algod)
- Event‐driven P2P messaging
- Pluggable storage drivers (SQLite, Pebble) and codec generation (msgp)
- Clear interfaces for testing and mocking
d. Key technologies/frameworks:
- Go modules, Go toolchain
- HTTP + OpenAPI/JSON for REST RPC
- WebSockets for P2P consensus messaging
- MessagePack for internal serialization
- Prometheus / OpenCensus metrics
- logrus‐based logging

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User & Clients"
        CLI["CLI & SDK Clients"]:::cli
        Metrics["Monitoring & Metrics"]:::external
    end

    subgraph "Key Management Daemon" 
        KMD["kmd Daemon<br/>(daemon/kmd/)"]:::daemon
        KMDServer["kmd Server<br/>(server.go)"]:::daemon
    end

    subgraph "Core Node Daemon (algod)"
        ALGOD["algod Daemon<br/>(daemon/algod/)"]:::daemon
        AlgodServer["algod Server API<br/>(server.go)"]:::daemon

        subgraph "Core Libraries"
            CryptoLayer["Crypto Layer<br/>(crypto/)"]:::crypto
            ProtocolConfig["Protocol & Config<br/>(protocol/, config/)"]:::protocol
            DataModels["Data Models<br/>(data/)"]:::data
            Networking["Networking Layer<br/>(network/)"]:::network
            Agreement["Agreement Engine (BFT)<br/>(agreement/)"]:::consensus
            Catchup["Catchup Service<br/>(catchup/)"]:::service
            LedgerSM["Ledger State Machine<br/>(ledger/)"]:::storage
        end
    end

    subgraph "Orchestration & Deployment"
        Docker["Docker Scripts<br/>(docker/)"]:::deploy
        NodeControl["Node Control<br/>(nodecontrol/)"]:::deploy
        NetDeploy["Network Deployment<br/>(netdeploy/)"]:::deploy
    end

    CLI -->|"HTTP REST"| AlgodServer
    CLI -->|"HTTP REST"| KMDServer
    CLI -->|"Prometheus"| Metrics
    Metrics -->|collects| AlgodServer

    AlgodServer -->|"msgp"| CryptoLayer
    AlgodServer -->|"uses"| ProtocolConfig
    AlgodServer -->|"instantiates"| DataModels
    AlgodServer -->|"routes"| Networking
    AlgodServer -->|"invokes"| Agreement
    AlgodServer -->|"triggers"| Catchup
    AlgodServer -->|"applies blocks"| LedgerSM

    Networking -->|"WebSocket P2P"| Agreement
    Agreement -->|"consensus msgs"| Networking
    DataModels -->|"in-memory state"| LedgerSM
    LedgerSM -->|"storage drivers"| LedgerSM

    KMDServer -->|"sign reqs"| CryptoLayer
    KMDServer -->|"returns signed TX"| CLI

    Docker -->|launch| ALGOD
    Docker -->|launch| KMD
    NodeControl -->|configure| ALGOD
    NodeControl -->|configure| KMD
    NetDeploy -->|orchestrate multi-node| ALGOD
    NetDeploy -->|orchestrate multi-node| KMD

    click CryptoLayer "https://github.com/algorand/go-algorand/tree/master/crypto/"
    click ProtocolConfig "https://github.com/algorand/go-algorand/tree/master/protocol/"
    click DataModels "https://github.com/algorand/go-algorand/tree/master/data/"
    click Networking "https://github.com/algorand/go-algorand/tree/master/network/"
    click Agreement "https://github.com/algorand/go-algorand/tree/master/agreement/"
    click LedgerSM "https://github.com/algorand/go-algorand/tree/master/ledger/"
    click Catchup "https://github.com/algorand/go-algorand/tree/master/catchup/"
    click ALGOD "https://github.com/algorand/go-algorand/tree/master/daemon/algod/"
    click AlgodServer "https://github.com/algorand/go-algorand/blob/master/daemon/algod/server.go"
    click KMD "https://github.com/algorand/go-algorand/tree/master/daemon/kmd/"
    click KMDServer "https://github.com/algorand/go-algorand/blob/master/daemon/kmd/server/server.go"
    click CLI "https://github.com/algorand/go-algorand/tree/master/cmd/"
    click CLI "https://github.com/algorand/go-algorand/tree/master/libgoal/"
    click Docker "https://github.com/algorand/go-algorand/tree/master/docker/"
    click NodeControl "https://github.com/algorand/go-algorand/tree/master/nodecontrol/"
    click NetDeploy "https://github.com/algorand/go-algorand/tree/master/netdeploy/"

    classDef crypto fill:#e0ffe0,stroke:#008000,stroke-width:1px
    classDef protocol fill:#f0fff0,stroke:#00aa00,stroke-width:1px
    classDef data fill:#e0f7ff,stroke:#0066cc,stroke-width:1px
    classDef network fill:#e0e0ff,stroke:#0000cc,stroke-width:1px
    classDef consensus fill:#ccffcc,stroke:#009900,stroke-width:1px
    classDef service fill:#fff0e0,stroke:#cc6600,stroke-width:1px
    classDef storage fill:#fff8c6,stroke:#cca300,stroke-width:1px
    classDef daemon fill:#ffe0e0,stroke:#cc0000,stroke-width:1px
    classDef cli fill:#f0e0ff,stroke:#6600cc,stroke-width:1px
    classDef external fill:#f8f8f8,stroke:#888888,stroke-width:1px
    classDef deploy fill:#f0f0f0,stroke:#555555,stroke-width:1px
```
