# lucielebriquer/webserv architecture

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

- Interactive diagram: https://gitdiagram.com/lucielebriquer/webserv
- Repository: https://github.com/lucielebriquer/webserv

## Overview

##### Project Type and Purpose
- This is a custom, single‐process, event‐driven HTTP server (“Webserv”) written in C++.
- It implements a full TCP + HTTP/1.1 stack, parses a configuration file (nginx‐style), handles virtual hosts and locations, serves static files and invokes CGI (e.g. PHP) for dynamic responses.

##### High‐Level Architectural Components
- Configuration & Parsing Layer
– Config Parser (sources/parsing/*.cpp + includes/Config.hpp / Location.hpp / Server.hpp / Block.hpp)
– Builds in‐memory data structures representing server blocks, locations, error pages, root paths, allowed methods, CGI mappings.
- Networking & Concurrency Layer
– Socket abstraction (includes/Socket.hpp + sources/engine/class/Socket.cpp)
– epoll‐based Event Loop (sources/engine/epoll.cpp / engine.hpp)
– Client session management (includes/Client.hpp + sources/engine/class/Client.cpp)
- HTTP Processing Layer
– HTTP Request Parser (includes/httpRequest.hpp + sources/request/httpRequest.cpp / httpHeader.cpp)
– Router (matches incoming Host:port + request‐URI against parsed Server/Location objects)
– HTTP Response Builder (includes/httpResponse.hpp / Status.hpp / mime.hpp + sources/response/*.cpp)
- Content Handling Layer
– Static File Handler (reads from disk, infers MIME, supports range requests, chunked encoding)
– CGI Engine (sources/engine/cgi.cpp / env.cpp + execve to run PHP or other CGI)
- Utility & Support
– Logging, error‐handling, helper functions (includes/usefull.hpp, sources/parsing/usefull.cpp, sources/engine/utils.cpp)

##### Component Relationships & Data Flow
1. Startup (main.cpp)
- Read and parse config files (`config/basic.conf`, `config/tenServ.conf`, etc.) → build Config objects.
- Initialize one listening TCP socket per server block (bind/listen on HOST:PORT).
- Create epoll instance and register all listening sockets.
2. Event Loop (epoll_wait)
- On readable event of a listening socket → `accept()` → create Client instance → register client FD in epoll.
- On readable event of a client FD → `recv()` raw bytes → HTTP Request Parser → HTTPRequest object.
- Router selects matching Server + Location based on Host header and URL.
- Handler chooses:
– Static: open file, determine MIME, read content (sources/response/default.cpp).
– CGI: fork + execve(CGI_PATH) with env variables (sources/engine/cgi.cpp + env.cpp), read CGI stdout.
- Build HTTPResponse (status line, headers, body) → `send()` back to client (sources/engine/send.cpp).
- On FIN or error → close FD, remove from epoll.

##### Elements
- Clear component names matching directories/files (e.g. “Client Session”, “Socket”, “epoll”, “Config Parser”).
- Breakdown of static vs dynamic content paths.
- Indication of environment variables passed to CGI (sub‐step in content handling).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Clients["Clients (Browsers)"]

    %% Config & Parsing Layer
    subgraph "Config & Parsing Layer"
        direction TB
        ConfigParser["Config Parser"]:::config
        LocationParser["Location Parser"]:::config
        ServerParser["Server Parser"]:::config
        BlockParser["Block Parser"]:::config
        UsefullParsing["Parsing Utils"]:::config
    end

    %% Networking & Concurrency Layer
    subgraph "Networking & Concurrency Layer"
        direction TB
        SocketAbstraction["Socket Abstraction"]:::network
        EventLoop["epoll Event Loop"]:::network
        ClientSession["Client Session"]:::network
    end

    %% HTTP Processing Layer
    subgraph "HTTP Processing Layer"
        direction TB
        HttpRequestParser["HTTP Request Parser"]:::parsing
        Router["Router"]:::parsing
        HttpResponseBuilder["HTTP Response Builder"]:::parsing
    end

    %% Content Handling Layer
    subgraph "Content Handling Layer"
        direction TB
        StaticHandler["Static File Handler"]:::content
        CGIEngine["CGI Engine"]:::content
    end

    %% Utilities & Support
    subgraph "Utilities & Support"
        direction TB
        Utils["Utilities & Support"]:::utils
    end

    %% Core Flow
    Clients -->|"TCP connect"| SocketAbstraction
    SocketAbstraction -->|"register FDs"| EventLoop
    EventLoop -->|"accept()/recv()"| ClientSession
    ClientSession -->|"HTTP bytes"| HttpRequestParser
    HttpRequestParser -->|"HTTPRequest object"| Router
    Router -->|"static request"| StaticHandler
    Router -->|"CGI request"| CGIEngine
    StaticHandler -->|"file content"| HttpResponseBuilder
    CGIEngine -->|"CGI stdout"| HttpResponseBuilder
    HttpResponseBuilder -->|"HTTP bytes"| SocketAbstraction
    SocketAbstraction -->|"send()"| Clients

    %% Config startup flow
    Clients -.->|"config reload"| ConfigParser
    ConfigParser --> LocationParser
    ConfigParser --> ServerParser
    ConfigParser --> BlockParser
    ConfigParser --> UsefullParsing
    ServerParser -->|"server blocks"| SocketAbstraction

    %% Utils linkage
    Utils --> ConfigParser
    Utils --> HttpRequestParser
    Utils --> StaticHandler
    Utils --> CGIEngine
    Utils --> EventLoop

    %% Click Events
    click ConfigParser "https://github.com/lucielebriquer/webserv/blob/main/includes/Config.hpp"
    click LocationParser "https://github.com/lucielebriquer/webserv/blob/main/includes/Location.hpp"
    click ServerParser "https://github.com/lucielebriquer/webserv/blob/main/includes/Server.hpp"
    click BlockParser "https://github.com/lucielebriquer/webserv/blob/main/includes/Block.hpp"
    click UsefullParsing "https://github.com/lucielebriquer/webserv/blob/main/sources/parsing/usefull.cpp"
    click SocketAbstraction "https://github.com/lucielebriquer/webserv/blob/main/includes/Socket.hpp"
    click SocketAbstraction "https://github.com/lucielebriquer/webserv/blob/main/sources/engine/class/Socket.cpp"
    click EventLoop "https://github.com/lucielebriquer/webserv/blob/main/includes/engine.hpp"
    click EventLoop "https://github.com/lucielebriquer/webserv/blob/main/sources/engine/epoll.cpp"
    click ClientSession "https://github.com/lucielebriquer/webserv/blob/main/includes/Client.hpp"
    click ClientSession "https://github.com/lucielebriquer/webserv/blob/main/sources/engine/class/Client.cpp"
    click HttpRequestParser "https://github.com/lucielebriquer/webserv/blob/main/includes/httpRequest.hpp"
    click HttpRequestParser "https://github.com/lucielebriquer/webserv/blob/main/sources/request/httpRequest.cpp"
    click HttpRequestParser "https://github.com/lucielebriquer/webserv/blob/main/includes/httpHeader.hpp"
    click HttpRequestParser "https://github.com/lucielebriquer/webserv/blob/main/sources/request/httpHeader.cpp"
    click HttpResponseBuilder "https://github.com/lucielebriquer/webserv/blob/main/includes/httpResponse.hpp"
    click HttpResponseBuilder "https://github.com/lucielebriquer/webserv/blob/main/includes/Status.hpp"
    click HttpResponseBuilder "https://github.com/lucielebriquer/webserv/blob/main/includes/mime.hpp"
    click HttpResponseBuilder "https://github.com/lucielebriquer/webserv/blob/main/sources/response/httpResponse.cpp"
    click HttpResponseBuilder "https://github.com/lucielebriquer/webserv/blob/main/sources/response/Status.cpp"
    click HttpResponseBuilder "https://github.com/lucielebriquer/webserv/blob/main/sources/response/mime.cpp"
    click StaticHandler "https://github.com/lucielebriquer/webserv/blob/main/sources/response/default.cpp"
    click CGIEngine "https://github.com/lucielebriquer/webserv/blob/main/sources/engine/cgi.cpp"
    click CGIEngine "https://github.com/lucielebriquer/webserv/blob/main/sources/engine/env.cpp"
    click Utils "https://github.com/lucielebriquer/webserv/blob/main/includes/usefull.hpp"
    click Utils "https://github.com/lucielebriquer/webserv/blob/main/sources/engine/utils.cpp"
    click Clients "https://github.com/lucielebriquer/webserv/blob/main/sources/main.cpp"

    %% Styles
    classDef network fill:#AEDEF4,stroke:#000,stroke-width:1px
    classDef parsing fill:#C8FACC,stroke:#000,stroke-width:1px
    classDef content fill:#FCE0A2,stroke:#000,stroke-width:1px
    classDef config fill:#E0E0E0,stroke:#000,stroke-width:1px
    classDef utils fill:#D3D3D3,stroke:#000,stroke-width:1px
```
