# scyth3-c/vibe architecture

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

- Interactive diagram: https://gitdiagram.com/scyth3-c/vibe
- Repository: https://github.com/scyth3-c/vibe

## Overview

##### Project type and purpose
- This is a high‑performance, user‑friendly C++ web framework (“Vibe”) providing an Express‑style API for building HTTP servers.
- The README and folder names (include/vibe, sources, examples) confirm that Vibe is a library, not a full application—it exposes Router, middleware, async I/O, templating, JSON, etc.

##### File structure
- Top‑level: CMakeLists.txt, Dockerfile, package.json (for npx static scaffolding), tests/, examples/, include/vibe/, sources/
- The “include/vibe” headers define public APIs (Router, Request, utilities).
- The “sources” folder houses implementation: request parsing, I/O, threading (thread_pool), sysprocess, sockets.
- examples/ illustrates use cases (routing, callbacks, JSON, templates).
- GitHub workflows, Dockerfile show CI/CD and containerization.

##### Key insights from README
- Core components: Router class, Query/Request object, send(…), listen()
- Dependencies: C++17, CMake, optional Docker, NPM CLI scaffold
- Testing via CMake/ctest, NPM scripts

a. Client & Network Layer
- External HTTP client (browser, curl)
- TCP/IP stack (OS kernel)
b. I/O & Event Loop
- Socket listener (acceptor)
- Epoll or select-based reactor (router_epoll.h)
c. Thread Pool
- Worker threads to run request handlers in parallel
d. Request Processing
- Request parser (io.cpp, parameters.cpp)
- Router match engine (sources/request/routes.cpp)
- Middleware chain (orderable callbacks)
e. Handler Execution
- User‑defined callbacks (examples code)
- Query/Response API (send(), json(), render())
f. Utilities & Extensions
- JSON library (util/json.hpp)
- Templating (basic_render, data_render, mg_reader)
- Sysprocess notifications, parameter processing
g. Build & Deployment Tools
- CMake build graphs
- Docker container
- NPM static site scaffolder (create‑vibe‑static)
h. Tests & Examples
- Unit tests (tests/)
- Sample applications (examples/)

##### Relationships & interactions
Client → Network Stack → Socket Listener → Event Loop → Thread Pool → Request Parser → Router → Middleware → Handler → Response Builder → Network Stack → Client
- Utilities are invoked within parser, handler, response phases.
- Build/Deploy tools are orthogonal: show CMake → binary, Docker → container, NPM → CLI scaffold.

##### Architectural patterns & design principles
- Reactor pattern for I/O (epoll)
- Thread pool for concurrency
- Pipeline for middleware
- Header‑only API + static library core (separation of interface and implementation)
- Modular code organization: request, sockets, threading, util

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Layer
    subgraph "External Systems"
        direction TB
        Client["HTTP Client (Browser, curl)"]:::external
        NetworkStack["TCP/IP Stack (OS Kernel)"]:::external
    end

    %% Socket & Event Loop
    subgraph "I/O & Event Loop"
        direction TB
        SocketListener["Socket Listener (accept)"]:::core
        EventLoop["Event Loop (epoll/select)"]:::core
    end

    %% Thread Pool
    subgraph "Concurrency"
        direction TB
        ThreadPool["Thread Pool"]:::core
    end

    %% Request Processing
    subgraph "Request Processing"
        direction TB
        RequestParser["Request Parser (HTTP, Params)"]:::core
        RouterEngine["Router Engine"]:::core
        MiddlewareChain["Middleware Chain"]:::core
    end

    %% Handler & Response
    subgraph "Handler Execution"
        direction TB
        Handler["User-defined Handlers"]:::api
        ResponseBuilder["Response Builder (send(), json(), render())"]:::api
    end

    %% Utilities
    subgraph "Utilities & Extensions"
        direction TB
        JSONUtil["JSON Utility"]:::util
        Templating["Templating Utilities"]:::util
        SysProcess["Sysprocess Notifications"]:::util
        ParamHelpers["Parameter Processing Helpers"]:::util
    end

    %% Tools
    subgraph "Build & Deployment Tools"
        direction TB
        CMake["CMake Build System"]:::tool
        Docker["Docker Container"]:::tool
        NPMCLI["NPM Static Scaffolder"]:::tool
    end

    %% Tests & Examples
    subgraph "Tests & Examples"
        direction TB
        UnitTests["Unit Tests"]:::tool
        Examples["Example Applications"]:::tool
    end

    %% Flow
    Client --> NetworkStack
    NetworkStack --> SocketListener
    SocketListener --> EventLoop
    EventLoop --> ThreadPool
    ThreadPool --> RequestParser
    RequestParser --> RouterEngine
    RouterEngine --> MiddlewareChain
    MiddlewareChain --> Handler
    Handler --> ResponseBuilder
    ResponseBuilder --> NetworkStack
    NetworkStack --> Client

    %% Utilities integrations
    RequestParser --> JSONUtil
    Handler --> JSONUtil
    Handler --> Templating
    MiddlewareChain --> SysProcess
    RequestParser --> ParamHelpers

    %% Tools dependencies
    CMake -->|builds| SocketListener
    Docker -->|packages| CMake
    NPMCLI -->|scaffolds| Examples
    CMake -->|tests| UnitTests

    %% Click Events
    click SocketListener "https://github.com/scyth3-c/vibe/blob/master/include/vibe/sockets.h"
    click SocketListener "https://github.com/scyth3-c/vibe/blob/master/sources/sockets.cpp"
    click EventLoop "https://github.com/scyth3-c/vibe/blob/master/include/vibe/request/router_epoll.h"
    click EventLoop "https://github.com/scyth3-c/vibe/blob/master/include/vibe/request/io.h"
    click EventLoop "https://github.com/scyth3-c/vibe/blob/master/sources/request/io.cpp"
    click ThreadPool "https://github.com/scyth3-c/vibe/blob/master/include/vibe/threading/thread_pool.h"
    click ThreadPool "https://github.com/scyth3-c/vibe/blob/master/sources/threading/thread_pool.cpp"
    click RequestParser "https://github.com/scyth3-c/vibe/blob/master/include/vibe/request/parameters.hpp"
    click RequestParser "https://github.com/scyth3-c/vibe/blob/master/sources/request/parameters.cpp"
    click RouterEngine "https://github.com/scyth3-c/vibe/blob/master/include/vibe/request/request.hpp"
    click RouterEngine "https://github.com/scyth3-c/vibe/blob/master/sources/request/request.cpp"
    click RouterEngine "https://github.com/scyth3-c/vibe/blob/master/include/vibe/routes.hpp"
    click RouterEngine "https://github.com/scyth3-c/vibe/blob/master/sources/request/routes.cpp"
    click Handler "https://github.com/scyth3-c/vibe/blob/master/include/vibe/vibe.h"
    click Handler "https://github.com/scyth3-c/vibe/blob/master/include/vibe/request/request.hpp"
    click JSONUtil "https://github.com/scyth3-c/vibe/blob/master/include/vibe/util/json.hpp"
    click Templating "https://github.com/scyth3-c/vibe/blob/master/include/vibe/util/basic_render.h"
    click Templating "https://github.com/scyth3-c/vibe/blob/master/include/vibe/util/data_render.h"
    click Templating "https://github.com/scyth3-c/vibe/blob/master/include/vibe/util/cpp_reader.h"
    click Templating "https://github.com/scyth3-c/vibe/blob/master/include/vibe/util/mg_reader.h"
    click SysProcess "https://github.com/scyth3-c/vibe/blob/master/include/vibe/util/sysprocess.h"
    click SysProcess "https://github.com/scyth3-c/vibe/blob/master/sources/sysprocess.cpp"
    click ParamHelpers "https://github.com/scyth3-c/vibe/blob/master/include/vibe/util/parameter_proccess.h"
    click ParamHelpers "https://github.com/scyth3-c/vibe/blob/master/sources/parameter_proccess.cpp"
    click CMake "https://github.com/scyth3-c/vibe/blob/master/CMakeLists.txt"
    click CMake "https://github.com/scyth3-c/vibe/blob/master/.github/workflows/cmake-single-platform.yml"
    click Docker "https://github.com/scyth3-c/vibe/tree/master/Dockerfile"
    click Docker "https://github.com/scyth3-c/vibe/blob/master/.github/workflows/docker-image.yml"
    click NPMCLI "https://github.com/scyth3-c/vibe/blob/master/package.json"
    click UnitTests "https://github.com/scyth3-c/vibe/tree/master/tests/"
    click UnitTests "https://github.com/scyth3-c/vibe/blob/master/tests/main_test.cpp"
    click UnitTests "https://github.com/scyth3-c/vibe/blob/master/tests/debug.cpp"
    click Examples "https://github.com/scyth3-c/vibe/tree/master/examples/"

    %% Styles
    classDef external fill:#dddddd,stroke:#888888,color:#333333,stroke-width:1px
    classDef core fill:#d4f1be,stroke:#4CAF50,color:#333333,stroke-width:1px
    classDef api fill:#bee5f1,stroke:#2196F3,color:#333333,stroke-width:1px
    classDef util fill:#fdf1be,stroke:#FFC107,color:#333333,stroke-width:1px
    classDef tool fill:#ffe0b2,stroke:#FF9800,color:#333333,stroke-width:1px
```
