# akrepkov/webserv architecture

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

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

## Overview

##### Project Type & Purpose
- This is a standalone HTTP web‐server written in C++.
- It uses an event‐driven reactor pattern (EventPoll), parses HTTP requests/responses, serves static files from “www/html,” and supports CGI scripts under “www/html/cgi-bin.”
- It is configurable via `configs/default.conf`.

##### File Structure
- Top‐level:
- configs/default.conf → server & location directives
- /*.hpp → component interfaces (Server, Client, Config, EventPoll, HttpRequest/Response, CGI, Location)
- src/*.cpp → implementations and startup (`start.cpp`)
- www/html/… → static content & error pages; `cgi-bin/` holds Python scripts
- Key patterns:
- Reactor/Event loop (EventPoll)
- Modular separation: networking (Server, Client), parsing (HttpRequest/Response), configuration (Config, Location), dynamic content (CGI), utilities
- External dependencies: Python interpreter for CGI scripts

a. Listener/Server
- Binds to socket, accepts new connections
b. EventPoll (Reactor)
- Monitors all socket FDs (listen + clients)
- Dispatches readability/writability events
c. Client Session
- Holds socket FD, buffer
- Tied to a parsed HttpRequest/HttpResponse
d. HTTP Parser & Responder
- HttpRequest: parse incoming data
- HttpResponse: build headers & body
e. Config Manager
- Loads `default.conf` into Config & Location objects
- Determines routing & allowed methods
f. Static File Handler
- Reads files from `www/html`
- Maps URLs to filesystem paths
g. CGI Handler
- On matching “cgi‐bin” locations, forks a process, executes script via `/usr/bin/python`
- Reads script output, converts to HttpResponse
h. File System
- Source for static content & error pages
i. External Service
- Python interpreter invoked for CGI scripts

##### Component Interactions & Data Flows
1. Client → TCP Socket → Server.accept()
2. Socket → EventPoll → “read ready” → Client.read()
3. Data → HttpRequest.parse()
4. Config.lookup(Request.path) → Location directive
5a. If static: File System → HttpResponse.build(static file)
5b. If CGI: spawn Python process → script STDOUT → HttpResponse.build(CGI output)
6. EventPoll “write ready” → Client.write(HttpResponse) → Socket → Client

##### Architectural Patterns & Principles
- Reactor pattern (EventPoll) decoupling I/O multiplexing from business logic
- Single Responsibility: each module (Config, Parser, CGI) has one clear job
- Pluggable handlers for static vs dynamic content
- Non‐blocking I/O and edge‐triggered notifications (if using epoll)

- Title: “C++ Web Server Architecture”
- Deployment note: runs on Linux, uses epoll (or kqueue on BSD)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Server Process"
        direction TB
        Server["Listener / Server"]:::core
        EventPoll["EventPoll (Reactor)"]:::core
        Client["Client Session"]:::core
        HttpReq["HTTP Request Parser"]:::core
        HttpResp["HTTP Response Builder"]:::core
        ConfigMgr["Config Manager"]:::core
        Location["Location Directives"]:::core

        subgraph "Resource Handlers"
            direction TB
            Static["Static File Handler"]:::handler
            CGI["CGI Handler"]:::handler
        end

        FileSys["File System"]:::fs
        Python["Python Interpreter"]:::ext
    end

    Client -->|"connect"| Server
    Server -->|"register FD"| EventPoll
    EventPoll -->|"read ready"| Client
    Client -->|"read data"| HttpReq
    HttpReq -->|"parse request"| ConfigMgr
    ConfigMgr -->|"lookup path"| Location
    Location -->|"static path"| Static
    Static -->|"file read"| FileSys
    FileSys -->|"file data"| HttpResp
    Location -->|"cgi-bin path"| CGI
    CGI -->|"spawn process"| Python
    Python -->|"stdout"| HttpResp
    HttpResp -->|"build response"| Client
    Client -->|"write response"| EventPoll
    EventPoll -->|"write ready"| Server

    click Server "https://github.com/akrepkov/webserv/blob/main/include/Server.hpp"
    click EventPoll "https://github.com/akrepkov/webserv/blob/main/include/EventPoll.hpp"
    click Client "https://github.com/akrepkov/webserv/blob/main/include/Client.hpp"
    click HttpReq "https://github.com/akrepkov/webserv/blob/main/include/HttpRequest.hpp"
    click HttpResp "https://github.com/akrepkov/webserv/blob/main/include/HttpResponse.hpp"
    click ConfigMgr "https://github.com/akrepkov/webserv/blob/main/include/Config.hpp"
    click Location "https://github.com/akrepkov/webserv/blob/main/include/Location.hpp"
    click Static "https://github.com/akrepkov/webserv/blob/main/include/utils.hpp"
    click CGI "https://github.com/akrepkov/webserv/blob/main/include/CGI.hpp"
    click FileSys "https://github.com/akrepkov/webserv/tree/main/www/html/"
    click Python "https://github.com/akrepkov/webserv/tree/main/www/html/cgi-bin/"

    classDef core fill:#a4fba8,stroke:#333,stroke-width:1px
    classDef handler fill:#A8D1FB,stroke:#333,stroke-width:1px
    classDef fs fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef ext fill:#F6A560,stroke:#333,stroke-width:1px
```
