# qubic/core architecture

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

## Overview

##### Main Components Identification
- Boot & EFI Components:
- UEFI bootloader functionality. Note the presence of the “lib/platform_efi” and “lib/platform_os” directories, which show that the project has platform-specific code (for EFI and OS-based debugging and sleep functionalities). Also, the README details the disk format and boot partition structure.
- Platform & Base Libraries:
- The “lib/platform_common” directory with its EDK2 mdepkg submodule indicates core libraries and low-level interfaces (e.g., BaseLib, DebugLib, assembly routines for LongJump/SetJump). These form the foundation for platform abstraction.
- Core Application Code:
- “src” holds the main application logic. This includes:
- The K12 folder (likely related to the cryptographic hash or similar algorithm, e.g. KangarooTwelve).
- Main node entry point (e.g. qubic.cpp, Qubic.vcxproj).
- Contract-related modules in “src/contract_core” and “src/contracts” that manage contract definitions, execution logic, and contract-related data structures.
- Network and messaging infrastructure in “src/network_core” and “src/network_messages” that indicate how the node communicates with other peers.
- Additional features (e.g., mining in “src/mining”, logging in “src/logging”, ticking mechanics in “src/ticking”, and the spectrum module for system state).
- Core platform functionality like file I/O, concurrency, debugging, and memory management in “src/platform”.
- Testing & Tools:
- Separate “test” directory indicates extensive testing routines (unit, integration tests).
- “tools” directory (e.g., score_test_generator) for generating test inputs or validating score calculations.
- Documentation & Auxiliary Files:
- The “doc” directory and various Markdown files (README.md, SEAMLESS.md, protocol.md, etc.) provide developer guidance and protocol details.

##### Depicting Relationships and Interactions
- Inside the core application, separate the following into distinct modules:
- Contract Engine: Merge “contract_core” and “contracts” components. These handle the execution of smart contracts and rule-based logic.
- Network Stack: Use “network_core” and “network_messages” to show incoming/outgoing communications with peers. Include external public peer references as described in the README.
- Computor/Mining Module: Indicate the parts of the code that handle compute tasks (e.g. “src/mining”, “score_cache”, “score”).
- Utility & Support Modules: This would include logging, file I/O, concurrency, memory, platform-specific functions, and cryptographic routines from “src/K12” etc.
- Finally, display the Testing and Tools layer separately, which validates the modular components through the test harness and utilities.

##### Highlighting Architectural Patterns
- A modular design with clear separations between platform-specific code (both EFI and OS layers) and the higher-level application logic.
- Separation of concerns: boot initialization and environment configuration, network communications, contract processing, and computational tasks are distinct.
- The structure of “src” implies that components are split logically (networking, contracts, logging, ticking) even though it may compile into one monolithic EFI executable.
- The use of libraries (e.g., BaseLib, DebugLib) suggests heavy reuse of low-level routines common to UEFI or EDK2 development.

##### Including Technologies and Frameworks
- UEFI/EDK2: The project builds a UEFI executable and uses EDK2 libraries.
- C/C++: Evidenced by .cpp, .c, .h, and .asm files.
- Visual Studio Project Files (.vcxproj) indicate the development environment.
- GitHub Workflows: The presence of .github/workflows files shows CI/CD integration.
- It uses custom disk partitioning and boot scripts, as described in the README (e.g., startup.nsh).

##### Final Recommendations
- Detail every major module mentioned above and show how they interact, ensuring that key dependencies (such as the reliance on UEFI specifications and external contract files) are clearly depicted.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Boot & EFI Components"
        BootLoader["UEFI Boot Loader"]:::boot
        EFI["EFI Platform Code"]:::boot
        OS["OS Platform Code"]:::boot
    end

    subgraph "Platform & Base Libraries"
        BaseLib["Platform Common Libraries"]:::library
    end

    subgraph "Core Application"
        MainEntry["Main Node Entry (src/qubic.cpp)"]:::core
        VCXProj["Qubic Project File (src/Qubic.vcxproj)"]:::core
        Crypto["Cryptographic Module (K12)"]:::crypto
        subgraph "Contract Engine"
            ContractCore["Contract Core Modules"]:::contract
            Contracts["Contract Definitions & Implementations"]:::contract
        end
        subgraph "Network Stack"
            NetworkCore["Network Communication Core"]:::network
            NetMessages["Network Messaging Infrastructure"]:::network
        end
        Mining["Computor/Mining Module"]:::mining
        Logging["Logging Utility"]:::utility
        Ticking["Ticking Mechanism"]:::utility
        Spectrum["Spectrum Module"]:::utility
        PlatformFunc["Core Platform Functionality"]:::utility
    end

    subgraph "Testing & Tools"
        Testing["Testing Harness"]:::test
        Tools["Testing & Development Tools"]:::tool
    end

    subgraph "Documentation & Auxiliary Files"
        Docs["Documentation Directory"]:::doc
        Readme["README & SEAMLESS"]:::doc
    end

    ExternalPeers["External Peers"]:::external

    BootLoader -->|"initializes"| BaseLib
    BaseLib -->|"providesFoundation"| MainEntry
    BootLoader -->|"loads"| EFI
    BootLoader -->|"loads"| OS

    MainEntry -->|"invokes"| VCXProj
    MainEntry -->|"calls"| Crypto
    MainEntry -->|"delegates"| ContractCore
    ContractCore -->|"integrates"| Contracts
    MainEntry -->|"communicatesWith"| NetworkCore
    NetworkCore -->|"sendsMessages"| NetMessages
    MainEntry -->|"handles"| Mining
    MainEntry -->|"logs"| Logging
    MainEntry -->|"ticks"| Ticking
    MainEntry -->|"manages"| Spectrum
    MainEntry -->|"utilizes"| PlatformFunc
    NetworkCore -->|"communicates"| ExternalPeers

    Tools --- Testing
    Docs --- Readme

    %% Click Events
    click EFI "https://github.com/qubic/core/tree/main/lib/platform_efi"
    click OS "https://github.com/qubic/core/tree/main/lib/platform_os"
    click BaseLib "https://github.com/qubic/core/tree/main/lib/platform_common"
    click Crypto "https://github.com/qubic/core/tree/main/src/K12"
    click MainEntry "https://github.com/qubic/core/blob/main/src/qubic.cpp"
    click VCXProj "https://github.com/qubic/core/blob/main/src/Qubic.vcxproj"
    click ContractCore "https://github.com/qubic/core/tree/main/src/contract_core"
    click Contracts "https://github.com/qubic/core/tree/main/src/contracts"
    click NetworkCore "https://github.com/qubic/core/tree/main/src/network_core"
    click NetMessages "https://github.com/qubic/core/tree/main/src/network_messages"
    click Mining "https://github.com/qubic/core/tree/main/src/mining"
    click Logging "https://github.com/qubic/core/tree/main/src/logging"
    click Ticking "https://github.com/qubic/core/tree/main/src/ticking"
    click Spectrum "https://github.com/qubic/core/tree/main/src/spectrum"
    click PlatformFunc "https://github.com/qubic/core/tree/main/src/platform"
    click Testing "https://github.com/qubic/core/tree/main/test"
    click Tools "https://github.com/qubic/core/tree/main/tools"
    click Docs "https://github.com/qubic/core/tree/main/doc"
    click Readme "https://github.com/qubic/core/blob/main/README.md"

    %% Class Definitions for Colors
    classDef boot fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef library fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef core fill:#ffdead,stroke:#000,stroke-width:2px;
    classDef crypto fill:#ffa500,stroke:#000,stroke-width:2px;
    classDef contract fill:#ffff99,stroke:#000,stroke-width:2px;
    classDef network fill:#87ceeb,stroke:#000,stroke-width:2px;
    classDef mining fill:#dda0dd,stroke:#000,stroke-width:2px;
    classDef utility fill:#ffc0cb,stroke:#000,stroke-width:2px;
    classDef test fill:#98fb98,stroke:#000,stroke-width:2px;
    classDef tool fill:#d3d3d3,stroke:#000,stroke-width:2px;
    classDef doc fill:#f4a460,stroke:#000,stroke-width:2px;
    classDef external fill:#ff6347,stroke:#000,stroke-width:2px;
```
