# isndev/qb architecture

> Architecture diagram of the GitHub repository isndev/qb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/isndev/qb
- Repository: https://github.com/isndev/qb

## Overview

##### Main Components

a) Core Runtime Layer:
- Actor Management System
- Event Processing System
- Core Set Manager (for CPU core management)
- Virtual Core Implementation
- Lock-free Communication Channels (MPSC/SPSC queues)

b) Network Layer:
- TCP/UDP Components
- IP Management
- Network Helpers
- Epoll System (for Linux)

c) System Layer:
- Memory Allocator
- CPU Management
- Lock-free Data Structures
- Timestamp Management

**┌─────────────────────── Application Layer ───────────────────────┐**

- Actor Instances         Event Handlers        Services     │

- Framework Layer ────────────────────────┤

- ┌─────────────┐    ┌─────────────┐    ┌─────────────────┐   │
- Actor Core  │    │Event System │    │ Virtual Cores   │   │
- ┘    └─────────────┘    └─────────────────┘   │

- ┌─────────────┐    ┌─────────────┐    ┌─────────────────┐   │
- Network Layer│    │  Core Set   │    │ Memory System   │   │
- ┘    └─────────────┘    └─────────────────┘   │

- System Layer ──────────────────────────────┤

- Lock-free Queues     CPU Management     Memory Allocators    │

- ┘

##### Key Elements to Highlight

a) Actor Communication:
- Event flow through the system

b) Core Management:
- How actors are distributed across CPU cores
- Relationship between Virtual Cores and physical CPU cores
- CoreSet management structure

c) Memory Management:
- Custom allocator system
- Lock-free data structure locations
- Demonstrate memory flow between components

##### Specific Implementation Details

- Rectangles for core components
- Circles for actors
- Hexagons for event handlers
- Diamonds for system services

##### Performance-Critical Paths

Following with bold lines:
- Event propagation paths
- Inter-actor communication channels
- Core-to-core message passing
- Network I/O paths

- Lock-free communication
- CPU cache-friendly design
- Actor isolation and independence
- Event-driven architecture
- Core affinity and scheduling

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and classes
    classDef application fill:#f9f,stroke:#333,stroke-width:2px
    classDef framework fill:#bbf,stroke:#333,stroke-width:2px
    classDef system fill:#ddd,stroke:#333,stroke-width:2px
    classDef network fill:#bfb,stroke:#333,stroke-width:2px
    classDef core fill:#fbf,stroke:#333,stroke-width:2px
    classDef memory fill:#ffb,stroke:#333,stroke-width:2px

    subgraph Application["Application Layer"]
        ActorInstances["Actor Instances"]:::application
        EventHandlers["Event Handlers"]:::application
        Services["Application Services"]:::application
    end

    subgraph Framework["Framework Layer"]
        Main["Framework Main"]:::framework
        ActorMgmt["Actor Management"]:::framework
        EventSystem["Event Processing"]:::framework
        VCore["Virtual Cores"]:::framework
        CoreSetMgmt["Core Set Manager"]:::framework
    end

    subgraph Network["Network Layer"]
        TCP["TCP Component"]:::network
        UDP["UDP Component"]:::network
        IP["IP Management"]:::network
        NetHelpers["Network Helpers"]:::network
        Epoll["Epoll System"]:::network
    end

    subgraph System["System Layer"]
        LockFree["Lock-free Queues"]:::system
        CPUMgmt["CPU Management"]:::system
        MemAlloc["Memory Allocator"]:::system
        TimeStamp["Timestamp Management"]:::system
    end

    %% Relationships
    Main --> ActorMgmt
    Main --> EventSystem
    Main --> CoreSetMgmt
    ActorMgmt --> VCore
    EventSystem --> LockFree
    CoreSetMgmt --> CPUMgmt
    VCore --> CPUMgmt
    
    ActorInstances --> ActorMgmt
    EventHandlers --> EventSystem
    Services --> Main

    TCP & UDP --> IP
    IP --> NetHelpers
    NetHelpers --> Epoll
    
    %% Click events for component mapping
    click ActorMgmt "https://github.com/isndev/qb/blob/master/include/qb/core/Actor.h"
    click EventSystem "https://github.com/isndev/qb/blob/master/include/qb/core/Event.h"
    click CoreSetMgmt "https://github.com/isndev/qb/blob/master/include/qb/core/CoreSet.h"
    click VCore "https://github.com/isndev/qb/blob/master/include/qb/core/VirtualCore.h"
    click TCP "https://github.com/isndev/qb/blob/master/include/qb/network/tcp.h"
    click UDP "https://github.com/isndev/qb/blob/master/include/qb/network/udp.h"
    click IP "https://github.com/isndev/qb/blob/master/include/qb/network/ip.h"
    click NetHelpers "https://github.com/isndev/qb/blob/master/include/qb/network/helper.h"
    click Epoll "https://github.com/isndev/qb/blob/master/include/qb/network/epoll.h"
    click LockFree "https://github.com/isndev/qb/tree/master/include/qb/system/lockfree"
    click CPUMgmt "https://github.com/isndev/qb/blob/master/include/qb/system/cpu.h"
    click MemAlloc "https://github.com/isndev/qb/blob/master/include/qb/system/allocator/pipe.h"
    click TimeStamp "https://github.com/isndev/qb/blob/master/include/qb/system/timestamp.h"
    click Main "https://github.com/isndev/qb/blob/master/include/qb/core/Main.h"
```
