# qinguoyi/tinywebserver architecture

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

- Interactive diagram: https://gitdiagram.com/qinguoyi/tinywebserver
- Repository: https://github.com/qinguoyi/tinywebserver

## Overview

##### Project Type and Purpose
- TinyWebServer is a lightweight, high‑performance, full‑stack C++ web server for Linux.
- It implements a browser/server (B/S) model, supporting HTTP GET/POST, static file serving (HTML, images, video), dynamic pages via MySQL-backed user registration/login, nonblocking sockets with epoll (ET/LT), thread pool concurrency (half‑sync/half‑reactive), Reactor/Proactor event models, timers for idle‐connection cleanup, and synchronous/asynchronous logging.

##### File Structure
- Top‑level:
- main.cpp, webserver.cpp/h: server entry point & core initialization
- build.sh, makefile: build scripts
- config.cpp/h: runtime configuration parser
- root/: static HTML and media assets
- CGImysql/: MySQL connection pool + CGI login/register code
- http/: HTTP connection handling, request parsing state machines
- threadpool/: thread‑pool implementation
- timer/: idle‑connection timer (sorted list)
- log/: synchronous/asynchronous logging subsystem
- lock/: mutex/sem wrappers
- test_pressure/: bundled Webbench tool for stress testing
- Configuration files (.sh, makefile) set up build, port, model flags.
- README documents architecture, demo, pressure test results, and command‑line options.

##### README Insights
- Concurrency model: thread pool + nonblocking sockets + epoll (supports ET & LT) + Reactor & simulated Proactor.
- HTTP parsing via finite state machine supports GET/POST.
- Synchronous/asynchronous logging.
- MySQL connection pool and CGI for user auth.
- Timer subsystem for timeouts.
- Command‑line switches to tune ports, log mode, epoll trigger modes, linger, SQL pool size, thread count, actor model.

- Client (Web browser or test tool)
- Network Interface / Listen Socket
- Event Demultiplexer (epoll instance)
- Reactor/Proactor Dispatcher
- Thread Pool
- HTTP Connection Handler (http_conn module, state machine)
- Timer Manager (lst_timer) for idle timeouts
- MySQL Connection Pool (CGImysql module)
- Logging Subsystem (sync/async log)
- Static File System (root directory)
- Configuration Manager (config module)
- External MySQL Database
b. Relationships & Data Flows:
1. Client → Listen Socket: new TCP connection.
2. Listen Socket → epoll: register FDs with ET/LT.
3. epoll events → Reactor/Proactor: demultiplex to accept/read/write handlers.
4. For each read event: Reactor enqueues HTTP task to Thread Pool; Proactor may already have read data.
5. Worker Thread → HTTP Connection Handler: parse request (state machine).
6. HTTP Handler:
- If dynamic (login/register) → CGI module → MySQL Pool → Database → response data.
- If static → file I/O from root directory.
7. After processing → write response (via epoll EPOLLOUT).
8. On each new/active connection → Timer Manager resets or schedules a timer. Timer expiration → close connection.
9. Throughout: Logging Subsystem records events to disk (sync or via logging thread with BlockQueue).
c. Architectural Patterns & Principles:
- Half‑Sync/Half‑Async: epoll for async I/O + thread‑pool for sync processing.
- Reactor & Proactor event models selectable at runtime.
- Resource pooling: database connections, threads.
- RAII for connection/lock management.
- Finite State Machine for HTTP parsing.
- Timer wheel / sorted list for efficient timeouts.
d. Key Technologies & Libraries:
- C++11 (RAII, smart pointers)
- Linux sockets API, non‑blocking fcntl
- epoll (ET/LT modes)
- POSIX threads + custom threadpool
- MySQL C API (pooled connections)
- Custom logging with blocking queue for async mode

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Network I/O Layer
    subgraph "Network I/O Layer"
        direction TB
        Client["Client (Browser/Test)"]:::network
        ListenSocket["Listen Socket"]:::network
        Epoll["Event Demultiplexer (epoll)"]:::network
        Reactor["Reactor/Proactor Dispatcher"]:::network
    end

    %% Concurrency Layer
    subgraph "Concurrency Layer"
        direction TB
        ThreadPool["Thread Pool"]:::concurrency
        TimerManager["Timer Manager"]:::concurrency
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        HTTPHandler["HTTP Connection Handler\n(state machine)"]:::application
        CGI["CGI Module\n(MySQL Auth)"]:::application
        StaticFS["Static File System\n(root/)"]:::application
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        ConfigMgr["Configuration Manager"]:::infra
        Logging["Logging Subsystem\n(sync/async)"]:::infra
        Lockers["Lock Wrappers"]:::infra
        MySQLDB["MySQL Database"]:::infra
        subgraph "Core Initialization"
            direction TB
            Main["main.cpp"]:::infra
            WebserverCPP["webserver.cpp"]:::infra
            WebserverH["webserver.h"]:::infra
        end
    end

    %% Data Flows
    Client -->|"TCP Connect"| ListenSocket
    ListenSocket -->|"register FD"| Epoll
    Epoll -->|"demultiplex events"| Reactor
    Reactor -->|"new/read event"| ThreadPool
    Reactor -->|"reset timer"| TimerManager
    ThreadPool -->|"dispatch task"| HTTPHandler
    HTTPHandler -->|"dynamic request"| CGI
    HTTPHandler -->|"static request"| StaticFS
    CGI -->|"DB Query"| MySQLDB
    HTTPHandler -->|"response write"| Epoll
    TimerManager -->|"timeout close"| Reactor
    %% Logging
    Reactor -->|"log event"| Logging
    ThreadPool -->|"log task"| Logging
    HTTPHandler -->|"log request/response"| Logging
    TimerManager -->|"log timeout"| Logging

    %% Configuration
    ConfigMgr -.->|"-p, -m, -t flags"| ListenSocket
    ConfigMgr -.->|"mode flags"| Epoll
    ConfigMgr -.->|"pool/thread counts"| ThreadPool
    ConfigMgr -.->|"SQL pool size"| CGI

    %% Synchronization
    Lockers --> Logging
    Lockers --> TimerManager

    %% Initialization
    Main --> ConfigMgr
    Main --> ListenSocket
    WebserverCPP --> ConfigMgr
    WebserverCPP --> ListenSocket

    %% Click Events
    click Main "https://github.com/qinguoyi/tinywebserver/blob/master/main.cpp"
    click WebserverCPP "https://github.com/qinguoyi/tinywebserver/blob/master/webserver.cpp"
    click WebserverH "https://github.com/qinguoyi/tinywebserver/blob/master/webserver.h"
    click ConfigMgr "https://github.com/qinguoyi/tinywebserver/blob/master/config.cpp"
    click ConfigMgr "https://github.com/qinguoyi/tinywebserver/blob/master/config.h"
    click StaticFS "https://github.com/qinguoyi/tinywebserver/tree/master/root/"
    click CGI "https://github.com/qinguoyi/tinywebserver/blob/master/CGImysql/sql_connection_pool.cpp"
    click CGI "https://github.com/qinguoyi/tinywebserver/blob/master/CGImysql/sql_connection_pool.h"
    click CGI "https://github.com/qinguoyi/tinywebserver/blob/master/CGImysql/README.md"
    click HTTPHandler "https://github.com/qinguoyi/tinywebserver/blob/master/http/http_conn.cpp"
    click HTTPHandler "https://github.com/qinguoyi/tinywebserver/blob/master/http/http_conn.h"
    click HTTPHandler "https://github.com/qinguoyi/tinywebserver/blob/master/http/README.md"
    click ThreadPool "https://github.com/qinguoyi/tinywebserver/blob/master/threadpool/threadpool.h"
    click ThreadPool "https://github.com/qinguoyi/tinywebserver/blob/master/threadpool/README.md"
    click TimerManager "https://github.com/qinguoyi/tinywebserver/blob/master/timer/lst_timer.cpp"
    click TimerManager "https://github.com/qinguoyi/tinywebserver/blob/master/timer/lst_timer.h"
    click TimerManager "https://github.com/qinguoyi/tinywebserver/blob/master/timer/README.md"
    click Logging "https://github.com/qinguoyi/tinywebserver/blob/master/log/log.cpp"
    click Logging "https://github.com/qinguoyi/tinywebserver/blob/master/log/log.h"
    click Logging "https://github.com/qinguoyi/tinywebserver/blob/master/log/block_queue.h"
    click Logging "https://github.com/qinguoyi/tinywebserver/blob/master/log/README.md"
    click Lockers "https://github.com/qinguoyi/tinywebserver/blob/master/lock/locker.h"
    click Lockers "https://github.com/qinguoyi/tinywebserver/blob/master/lock/README.md"
    click StaticFS "https://github.com/qinguoyi/tinywebserver/tree/master/test_pressure/webbench-1.5/"
    click StaticFS "https://github.com/qinguoyi/tinywebserver/blob/master/test_pressure/README.md"
    click ConfigMgr "https://github.com/qinguoyi/tinywebserver/blob/master/build.sh"
    click ConfigMgr "https://github.com/qinguoyi/tinywebserver/tree/master/makefile"
    click ConfigMgr "https://github.com/qinguoyi/tinywebserver/blob/master/README.md"
    click ConfigMgr "https://github.com/qinguoyi/tinywebserver/tree/master/LICENSE"

    %% Styles
    classDef network fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef concurrency fill:#90EE90,stroke:#000,stroke-width:1px
    classDef application fill:#FFA500,stroke:#000,stroke-width:1px
    classDef infra fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef external fill:#CCCCCC,stroke:#000,stroke-width:1px
```
