# aabolfazl/vortex architecture

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

- Interactive diagram: https://gitdiagram.com/aabolfazl/vortex
- Repository: https://github.com/aabolfazl/vortex

## Overview

##### Main Components
- Worker Processes: Represent each CPU core running an independent worker process. Each process includes an event loop that uses io_uring for asynchronous I/O.
- Listener/Acceptor: A shared listening socket that all worker processes use to accept new connections (reflected in the listener modules).
- Event Loop and I/O Handling: Central to each worker, this module handles io_uring-based event dispatching, illustrated by the components in src/event and src/core/io. Include submodules for io_uring_core, io_uring_dispacher_impl, and I/O handling for sockets.
- Load Balancing Core: This includes the balancer, cluster management (e.g., cluster and cluster_manager implementations in src/core/balancer), and the components responsible for distributing traffic, such as round-robin/least-connections algorithms.
- Network/Connection Management: Highlight the modules dealing with network connections like client_connection_impl, connection_factory, tcp connection pool implementations, and socket management components found in src/core/net and include/vortex/net.
- Configuration and Logging: Include the configuration management (YAML parser and configuration manager in src/core/config) and logging components (see src/core/logger).

##### Relationships and Interactions
- Within a Worker Process, illustrate the event loop receiving notifications from io_uring (as shown in src/event and core I/O directories), then forwarding these events to connection management and load balancer modules.
- Configuration module feeding parameters into the workers and load balancing logic.
- Backend interactions where the load balancer routes incoming traffic to available service nodes or backends, which are represented within the load balancing module and service node components.

##### Architectural Patterns
- Process-per-Core Model: Clearly represent each worker process as an independent unit, with a common shared component for incoming connections.
- Modular design: Note the separation of concerns among configuration, networking, balancing logic, and I/O handling.

##### Relevant Technologies and Libraries
- Modern C++ (C++17) for language specifics.
- io_uring for high-performance event handling.
- CMake as the build system.
- Configuration is managed via YAML (see config files and YAML parser in src/core/config).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Components
    Listener["Listener Socket"]:::listener
    ConfigManager["Configuration Manager"]:::config
    Logging["Logging"]:::log
    LoadBalancer["Load Balancer Core"]:::balancer
    ConnectionManager["Network/Connection Manager"]:::net
    Backend["Backend Service Node (Planned)"]:::backend

    %% Worker Process Subgraph
    subgraph "Worker Process"
        WorkerMain["Worker Process Main"]:::worker
        EventLoop["Event Loop (io_uring)"]:::event
    end

    %% Relationships
    Listener -->|"accepts"| WorkerMain
    ConfigManager -->|"configures"| WorkerMain
    WorkerMain -->|"initializes"| EventLoop
    WorkerMain -->|"logs to"| Logging
    ConfigManager -->|"logs configuration"| Logging
    EventLoop -->|"handles I/O for"| ConnectionManager
    EventLoop -->|"dispatches to"| LoadBalancer
    LoadBalancer -->|"routes"| Backend

    %% Click Events
    click Listener "https://github.com/aabolfazl/vortex/blob/master/src/core/listener/listener_manager.h"
    click WorkerMain "https://github.com/aabolfazl/vortex/blob/master/src/vortex_app.cpp"
    click EventLoop "https://github.com/aabolfazl/vortex/blob/master/src/event/io_uring_core_impl.cpp"
    click LoadBalancer "https://github.com/aabolfazl/vortex/tree/master/src/core/balancer/"
    click ConnectionManager "https://github.com/aabolfazl/vortex/tree/master/src/core/net/"
    click ConfigManager "https://github.com/aabolfazl/vortex/tree/master/src/core/config/"
    click Logging "https://github.com/aabolfazl/vortex/blob/master/src/core/logger/logger.h"

    %% Styles
    classDef listener fill:#ffcccb,stroke:#000,stroke-width:2px;
    classDef config fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef log fill:#d3d3d3,stroke:#000,stroke-width:2px;
    classDef balancer fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef net fill:#ffdead,stroke:#000,stroke-width:2px;
    classDef worker fill:#ffffcc,stroke:#000,stroke-width:2px;
    classDef event fill:#dda0dd,stroke:#000,stroke-width:2px;
    classDef backend fill:#f0e68c,stroke:#000,stroke-width:2px;
```
