# kaizoincc/aethelgard architecture

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

- Interactive diagram: https://gitdiagram.com/kaizoincc/aethelgard
- Repository: https://github.com/kaizoincc/aethelgard

## Overview

##### Project type and purpose
- From the file tree and minimal README, “Aethelgard” implements a P2P blockchain node library/application in C++.
- It provides classes for Blocks, BlockHeaders, Transactions, a pluggable BlockchainStorage, and a P2P networking stack (P2PNode, PeerManager, PeerConnection, Message).

##### File structure
- Top-level directories:
- / – public headers for each major component
- src/     – their C++ implementations
- test/    – unit and integration tests per class and end-to-end
- Key modules:
- Domain model: Block, BlockHeader, Transaction
- Persistence: BlockchainStorage
- Networking: P2PNode, PeerManager, PeerConnection, Message
- Utilities: Utils
- No UI or frontend—this is purely a backend/library with a P2P transport and on-disk chain storage.

##### README for additional insights
- The README is sparse; assume standard blockchain features: peer discovery, block/tx propagation, storage, and verification.

a. Main components:
1. P2P Network Layer
– P2PNode: orchestrates the networking stack
– PeerManager: tracks known peers, handles discovery/blacklisting
– PeerConnection: manages per-peer TCP/UDP sessions
– Message (and Message types): the protocol payloads (e.g., GetBlock, NewBlock, Tx)
2. Blockchain Storage Layer
– BlockchainStorage: abstract interface + concrete implementation (e.g., LevelDB, file)
3. Domain Model
– Block (with BlockHeader), Transaction
4. Utilities
– Utils: e.g., serialization, hashing, configuration
5. Tests (external to runtime—but show that each component is covered by unit/integration tests)

b. Relationships and interactions:
- P2PNode receives inbound Message objects via PeerConnection.
- Message dispatcher inside P2PNode routes to appropriate handler (e.g., new block → validate & store, new tx → mempool & rebroadcast).
- Handlers invoke BlockchainStorage to read/write blocks.
- PeerManager supplies PeerConnection with endpoints to connect/disconnect.
- Utils is used by both domain and network layers for common tasks (serialization, hash checks).

c. Architectural patterns / design principles:
- Layered architecture: Network Layer → Application Logic → Persistence Layer
- Dependency inversion: BlockchainStorage is an interface, decoupled from its implementation.
- Single Responsibility: each class has one focus (e.g., PeerManager → peer list, PeerConnection → socket I/O).
- Observer/Publisher-Subscriber: P2PNode publishes new blocks/txs to all PeerConnections.

d. Key technologies and libraries:
- C++17 (assumed)
- TCP/UDP sockets (Boost.Asio or raw BSD sockets)
- Serialization (custom via Utils, or protobuf-like)
- Persistence (could be LevelDB, flat files, or in-memory; implemented in BlockchainStorage.cpp)

##### Elements
- Inbound/outbound data flow (e.g., network messages)
- Method calls (e.g., P2PNode → BlockchainStorage::storeBlock)
- Dependency injection (e.g., P2PNode depends on PeerManager and BlockchainStorage interface)
- Network components in blue
- Core domain classes (Block, Tx) in green
- Storage components in orange
- Utils in gray

##### Detailed, essential components (do not overthink—capture all modules)
- Domain Model: Block / BlockHeader / Transaction
- Messaging: Message base + types
- Networking: P2PNode, PeerManager, PeerConnection
- Storage: BlockchainStorage (interface) → [ConcreteStorage]
- Utils
- Major methods (e.g., PeerManager::addPeer(), PeerConnection::sendMessage(), BlockchainStorage::getHeight()).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Networking Layer
    subgraph "Networking Layer"
        style Networking Layer fill:#E6F2FF,stroke:#000,stroke-width:1px
        P2PNode["P2PNode"]:::network
        PeerManager["PeerManager"]:::network
        PeerConnection["PeerConnection"]:::network
        Message["Message"]:::network
    end

    %% Domain Model
    subgraph "Domain Model"
        style Domain Model fill:#ECFFE6,stroke:#000,stroke-width:1px
        Block["Block\n(BlockHeader)"]:::domain
        BlockHeader["BlockHeader"]:::domain
        Transaction["Transaction"]:::domain
    end

    %% Storage Layer
    subgraph "Storage Layer"
        style Storage Layer fill:#FFF4E6,stroke:#000,stroke-width:1px
        BlockchainStorage["BlockchainStorage"]:::storage
        ConcreteStorage["ConcreteStorage\n(e.g., LevelDB)"]:::storage
    end

    %% Utilities
    subgraph "Utilities"
        style Utilities fill:#F2F2F2,stroke:#000,stroke-width:1px
        Utils["Utils"]:::utils
    end

    %% Connections
    Message -->|"receives"| P2PNode
    P2PNode -->|"uses"| PeerManager
    P2PNode -->|"opens sessions"| PeerConnection
    PeerManager -->|"supplies peers"| PeerConnection
    P2PNode -->|"validates"| Block
    BlockHeader -->|"part of"| Block
    P2PNode -->|"processes tx"| Transaction
    P2PNode -->|"stores"| BlockchainStorage
    Block -->|"storeBlock()"| BlockchainStorage
    BlockchainStorage -->|"implements"| ConcreteStorage
    Utils -.->|"serialization/hashing"| P2PNode
    Utils -.->|"serialization/hashing"| PeerConnection
    Utils -.->|"serialization/hashing"| Block
    Utils -.->|"serialization/hashing"| Transaction
    Utils -.->|"serialization/hashing"| Message

    %% Click Events
    click Block "https://github.com/kaizoincc/aethelgard/blob/main/include/Block.hpp"
    click BlockHeader "https://github.com/kaizoincc/aethelgard/blob/main/include/BlockHeader.hpp"
    click Transaction "https://github.com/kaizoincc/aethelgard/blob/main/include/Transaction.hpp"
    click Message "https://github.com/kaizoincc/aethelgard/blob/main/include/Message.hpp"
    click P2PNode "https://github.com/kaizoincc/aethelgard/blob/main/include/P2PNode.hpp"
    click PeerManager "https://github.com/kaizoincc/aethelgard/blob/main/include/PeerManager.hpp"
    click PeerConnection "https://github.com/kaizoincc/aethelgard/blob/main/include/PeerConnection.hpp"
    click BlockchainStorage "https://github.com/kaizoincc/aethelgard/blob/main/include/BlockchainStorage.hpp"
    click Utils "https://github.com/kaizoincc/aethelgard/blob/main/include/Utils.hpp"

    %% Styles
    classDef network fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef domain fill:#90EE90,stroke:#000,stroke-width:1px
    classDef storage fill:#FFA500,stroke:#000,stroke-width:1px
    classDef utils fill:#D3D3D3,stroke:#000,stroke-width:1px
```
