# youngyangyang04/kama-webserver architecture

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

- Interactive diagram: https://gitdiagram.com/youngyangyang04/kama-webserver
- Repository: https://github.com/youngyangyang04/kama-webserver

## Overview

##### Project type and purpose
- This is a high-performance C++ web server inspired by the Muduo library, implementing a multi-threaded, multi-Reactor model.
- It includes custom memory pooling, asynchronous double-buffered logging, and an LFU cache.

##### File structure
- Top-level directories:
- / – public headers for all modules
- src/ – core server implementation and main()
- log/ – asynchronous logging implementation
- memory/ – memory pool implementation
- lib/ – any shared libraries
- img/, LICENSE, CMakeLists.txt, README.md
- Core modules under include/ and src/ correspond one-to-one:
- EventLoop, Channel, Poller/EPollPoller – Reactor pattern
- EventLoopThread, EventLoopThreadPool – “one loop per thread”
- Acceptor, TcpServer, TcpConnection, Socket, InetAddress – connection management
- Buffer – I/O buffering
- Thread, Timer, TimerQueue – threading and timed callbacks
- Logger, AsyncLogging, LogFile, LogStream – async logging
- memoryPool – custom allocator
- LFU, KICachePolicy – cache eviction policy

##### README for additional insights
- Confirms use of multi-Reactor + thread pool model
- Highlights memory pool, async double buffer logging, LFU cache as differentiators
- Describes module responsibilities (network, logging, memory, cache)

##### Main components and interactions
a. Components:
- Main Thread & MainLoop (EventLoop instance)
- Acceptor (listens on socket, registers Channel with main loop)
- Sub-Reactors (EventLoopThreads in the pool)
- Poller/EPollPoller (inside each EventLoop)
- Channels (one per FD, handle read/write callbacks)
- TcpServer (manages acceptor + loop pool)
- TcpConnection (per-connection state, read/write handlers)
- Buffer (per-connection input/output buffer)
- Thread Pool (EventLoopThreadPool)
- TimerQueue (for timers)
- AsyncLogging (logging thread with double buffer)
- MemoryPool (custom allocator for fixed blocks)
- LFU Cache (optional, used to cache content)
- External Clients (e.g., nc or browser)
- Filesystem (static file serving, if any)

b. Relationships / Data flow:
1. main() → creates EventLoop (main loop)
2. main() → creates EventLoopThreadPool (N subloops)
3. main() → constructs TcpServer(mainLoop, address, threadNum)
4. TcpServer starts:
- Acceptor binds/listens
- Registers acceptor's Channel on mainLoop’s Poller
5. New connection → Acceptor callback → hands new socket to subloop (round-robin)
6. Subloop:
- Creates TcpConnection object
- Registers its read/write Channel on Poller
7. When data arrives → Poller wakes EventLoop → Channel invokes TcpConnection::handleRead → Buffer → user callback (echo) → handleWrite
8. Logging: every Logger::log() → appends to AsyncLogging’s in-memory buffer → background logging thread flushes to disk
9. MemoryPool services all buffer allocations
10. LFU cache invoked by user-defined handler to cache static content

c. Architectural patterns / design principles
- Reactor: EventLoop + Poller + Channel
- Proactor-like for write callbacks
- One-loop-per-thread for concurrency
- Separation of concerns: networking, threading, logging, memory, caching
- Nonblocking I/O + edge-triggered epoll under the hood
- Double buffering to decouple log producer/consumer

d. Key technologies / frameworks
- C++17 (or later)
- Linux epoll
- pthreads (wrapped in Thread class)
- CMake build system

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Layer
    ExternalClients["External Clients"]:::external
    Filesystem["Filesystem"]:::external

    %% Networking Layer
    subgraph "Networking Layer"
        direction TB
        Acceptor["Acceptor"]:::network
        TcpServer["TcpServer"]:::network
        Channel["Channel"]:::network
        PollerInterface["Poller (interface)"]:::network
        EPollPoller["EPollPoller"]:::network
        DefaultPoller["DefaultPoller"]:::network
    end

    %% Concurrency Layer
    subgraph "Concurrency Layer"
        direction TB
        MainLoop(("EventLoop (mainLoop)")):::thread
        EventLoopThreadPool["EventLoopThreadPool"]:::thread
        EventLoopThread1(("EventLoopThread subLoop-1")):::thread
        EventLoopThreadN(("EventLoopThread subLoop-N")):::thread
        TimerQueue["TimerQueue"]:::thread
    end

    %% Connection Abstraction
    subgraph "Connection Abstraction"
        direction TB
        TcpConnection["TcpConnection"]:::network
        Buffer["Buffer"]:::data
        Socket["Socket"]:::network
        InetAddress["InetAddress"]:::network
    end

    %% Auxiliary Services
    subgraph "Auxiliary Services"
        direction TB
        MemoryPool["memoryPool"]:::data
        Logger["Logger"]:::network
        AsyncLogging["AsyncLogging"]:::data
        LogFile["LogFile"]:::data
        LogStream["LogStream"]:::data
        LFUCache["LFU Cache"]:::data
    end

    %% External flows
    ExternalClients -->|"TCP SYN"| Acceptor
    Acceptor -->|"onConnection()"| MainLoop
    MainLoop -->|"register Channel"| PollerInterface
    PollerInterface -->|uses| EPollPoller
    PollerInterface -->|fallback| DefaultPoller
    EPollPoller -->|"wakes"| Channel
    Channel -->|"onRead()/onWrite()"| TcpConnection
    TcpServer -->|"onStart()"| Acceptor
    MainLoop -->|"construct"| TcpServer
    TcpServer -->|"assign subLoop"| EventLoopThreadPool
    EventLoopThreadPool -->|"launch threads"| EventLoopThread1
    EventLoopThreadPool -->|"launch threads"| EventLoopThreadN
    EventLoopThread1 -->|"newConnection()"| TcpConnection
    TcpConnection -->|"uses"| Buffer
    TcpConnection -->|"holds"| Socket
    TcpConnection -->|"binds"| InetAddress

    %% Data flow within connection
    ExternalClients -->|"send data"| TcpConnection
    TcpConnection -->|"read into"| Buffer
    Buffer -->|"userCallback(echo)"| Buffer
    Buffer -->|"write from"| Channel
    Channel -->|"send to OS"| EPollPoller

    %% Timers
    EventLoopThread1 -->|"manages timers"| TimerQueue
    TimerQueue -->|"exec callback"| TcpConnection

    %% Logging flow
    Logger -->|"log() appends"| AsyncLogging
    AsyncLogging -->|dashed invocation| LogFile
    AsyncLogging -->|"uses"| LogStream

    %% Memory and Cache
    MemoryPool -.->|"alloc to"| Buffer
    TcpConnection -->|"cache lookup"| LFUCache
    LFUCache -->|"evict if full"| Filesystem
    Filesystem -->|"serve file"| TcpConnection

    %% Click Events
    click EventLoop "https://github.com/youngyangyang04/kama-webserver/blob/main/include/EventLoop.h"
    click Channel "https://github.com/youngyangyang04/kama-webserver/blob/main/include/Channel.h"
    click PollerInterface "https://github.com/youngyangyang04/kama-webserver/blob/main/include/Poller.h"
    click EPollPoller "https://github.com/youngyangyang04/kama-webserver/blob/main/include/EPollPoller.h"
    click DefaultPoller "https://github.com/youngyangyang04/kama-webserver/blob/main/src/DefaultPoller.cc"
    click EventLoopThread1 "https://github.com/youngyangyang04/kama-webserver/blob/main/include/EventLoopThread.h"
    click EventLoopThreadPool "https://github.com/youngyangyang04/kama-webserver/blob/main/include/EventLoopThreadPool.h"
    click Acceptor "https://github.com/youngyangyang04/kama-webserver/blob/main/include/Acceptor.h"
    click TcpServer "https://github.com/youngyangyang04/kama-webserver/blob/main/include/TcpServer.h"
    click TcpConnection "https://github.com/youngyangyang04/kama-webserver/blob/main/include/TcpConnection.h"
    click Socket "https://github.com/youngyangyang04/kama-webserver/blob/main/include/Socket.h"
    click InetAddress "https://github.com/youngyangyang04/kama-webserver/blob/main/include/InetAddress.h"
    click Buffer "https://github.com/youngyangyang04/kama-webserver/blob/main/include/Buffer.h"
    click Thread "https://github.com/youngyangyang04/kama-webserver/blob/main/include/Thread.h"
    click TimerQueue "https://github.com/youngyangyang04/kama-webserver/blob/main/include/TimerQueue.h"
    click Logger "https://github.com/youngyangyang04/kama-webserver/blob/main/include/Logger.h"
    click AsyncLogging "https://github.com/youngyangyang04/kama-webserver/blob/main/include/AsyncLogging.h"
    click LogFile "https://github.com/youngyangyang04/kama-webserver/blob/main/include/LogFile.h"
    click LogStream "https://github.com/youngyangyang04/kama-webserver/blob/main/include/LogStream.h"
    click MemoryPool "https://github.com/youngyangyang04/kama-webserver/blob/main/include/memoryPool.h"
    click LFUCache "https://github.com/youngyangyang04/kama-webserver/blob/main/include/LFU.h"

    %% Styles
    classDef network fill:#b3d1ff,stroke:#1f78b4,color:#1f78b4
    classDef thread fill:#d1ffd1,stroke:#2ca02c,color:#2ca02c
    classDef data fill:#fff3b3,stroke:#ffae42,color:#ff8c00
    classDef external fill:#d3d3d3,stroke:#696969,color:#696969
```
