# maemran/webserver architecture

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

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

## Overview

1. **What this repository is**
   - `WebServ` is a C++98 HTTP/1.1 server built as a single executable from `srcs/main.cpp`.
   - The architecture is split into clear modules: **configuration**, **network/socket handling**, **HTTP parsing and response generation**, **CGI execution**, and **cookie/session support**.

2. **Startup and configuration boundary**
   - On launch, the server reads `config_file/config.conf`.
   - The config subsystem (`ConfigLexer`, `ConfigParser`, `ConfigValidator`, plus `HttpConfig`, `ServerConfig`, `LocationConfig`) turns the text config into structured server/location rules.
   - This layer defines the runtime topology: which ports to listen on, which roots to use, allowed methods, redirects, error pages, CGI mappings, and body-size limits.

3. **Socket and connection layer**
   - The socket subsystem (`serversocket`, `connection`) owns all POSIX networking concerns: bind/listen/accept, client connection lifecycle, and monitoring multiple file descriptors.
   - The README indicates a non-blocking event loop using `select()` or `poll()`, so the server is a **single-process, multiplexed I/O** design rather than a thread-per-client model.

4. **Event-driven request ingestion**
   - Incoming bytes from client sockets are accumulated into a connection object and handed to the HTTP layer.
   - This creates the first major runtime boundary: **raw TCP stream** on one side, **parsed HTTP request object** on the other.

5. **HTTP parsing and request model**
   - `HttpRequest`, `URI`, and the HTTP-related parsing logic convert raw request data into method, target URI, headers, and body.
   - This layer is responsible for validating basic HTTP syntax, handling request metadata, and preparing the request for routing and execution.

6. **Routing and config matching**
   - `router.cpp` connects the parsed request to the active config context.
   - It resolves the correct `server` block and then the most specific `location` block for the URI.
   - From there it enforces per-location rules such as allowed methods, roots, indexes, autoindex, redirects, and body-size limits.

7. **Static content serving**
   - For normal file requests, the server resolves paths against the configured `root` and serves files from `webroot/`.
   - The repository contains representative static content: HTML pages, CSS, images, blog pages, forms, and custom error pages.
   - Directory requests are handled through index resolution and, where enabled, directory listing behavior.

8. **CGI execution boundary**
   - The CGI subsystem (`CgiHandler`) is the dynamic-content path.
   - Requests targeting configured CGI extensions in `webroot/cgi-bin/` are executed via an external interpreter such as Python or PHP.
   - The server acts as the bridge: it prepares environment variables, passes request data to the child process, reads CGI output, and converts it into an HTTP response.

9. **Response construction**
   - `HttpResponse` assembles the outbound message: status line, headers, and body.
   - It is responsible for producing standards-compliant responses for success cases, redirects, errors, HEAD responses, and CGI output.
   - The response path also handles connection metadata and content headers.

10. **Error handling and custom pages**
   - The config and response layers work together to map failures to HTTP status codes and custom HTML pages.
   - The repository includes `webroot/errors/403.html`, `404.html`, and `500.html`, which are used as configured error documents rather than generic fallback text.

11. **Cookie/session support**
   - `cookies/Cookie` and `cookies/Session` suggest a lightweight state-management subsystem.
   - This is a supporting boundary, not the core server loop: it likely helps with request/response state, tracking client sessions, or formatting cookie headers.

12. **Repository structure mirrors runtime roles**
   - `includes/` contains the public interfaces for each subsystem.
   - `srcs/` contains the implementation.
   - `webroot/` is the served content tree, while `assets/` contains project documentation imagery rather than runtime assets.

13. **Overall data flow**
   - The runtime flow is: **config parse → socket setup → event loop → request parse → route match → static file / CGI / redirect / error handling → response assembly → socket write**.
   - That is the key diagram to draw: a config-driven, event-loop-based HTTP server with explicit boundaries between networking, HTTP semantics, routing, and CGI execution.

Main entry points: [`includes/HTTP/router.hpp`](https://github.com/maemran/webserver/blob/main/includes/HTTP/router.hpp) (Router), [`includes/HTTP/HttpResponse.hpp`](https://github.com/maemran/webserver/blob/main/includes/HTTP/HttpResponse.hpp) (Http response), [`includes/HTTP/HttpRequest.hpp`](https://github.com/maemran/webserver/blob/main/includes/HTTP/HttpRequest.hpp) (Http request), [`includes/Socket/serversocket.hpp`](https://github.com/maemran/webserver/blob/main/includes/Socket/serversocket.hpp) (Server socket)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_config["Config"]
  node_node_cfg_lexer["Config lexer<br/>[ConfigLexer.hpp]"]
  node_node_cfg_parser["Config parser<br/>[ConfigParser.hpp]"]
  node_node_cfg_validator["Config validator"]
  node_node_cfg_runtime["Server config<br/>runtime config<br/>[HttpConfig.hpp]"]
end

subgraph group_group_network["Network"]
  node_node_socket["Server socket<br/>listener<br/>[serversocket.hpp]"]
  node_node_conn["Connection<br/>client state<br/>[connection.hpp]"]
end

subgraph group_group_http["HTTP"]
  node_node_req["Http request<br/>request model<br/>[HttpRequest.hpp]"]
  node_node_uri["URI<br/>target parser<br/>[URI.hpp]"]
  node_node_router["Router<br/>dispatch<br/>[router.hpp]"]
  node_node_resp["Http response<br/>response builder<br/>[HttpResponse.hpp]"]
end

subgraph group_group_cgi["CGI"]
  node_node_cgi["Cgi handler<br/>dynamic exec<br/>[CgiHandler.hpp]"]
end

subgraph group_group_state["State"]
  node_node_cookie["Cookie<br/>header support<br/>[Cookie.hpp]"]
  node_node_session["Session<br/>[Session.hpp]"]
end

subgraph group_group_content["Content"]
  node_node_webroot[("Webroot<br/>served files")]
  node_node_errors["Error pages<br/>custom docs"]
end

node_node_main["Server main<br/>entrypoint<br/>[main.cpp]"]

node_node_main -->|"loads config"| node_node_cfg_lexer
node_node_cfg_lexer -->|"tokens"| node_node_cfg_parser
node_node_cfg_parser -->|"validates"| node_node_cfg_validator
node_node_cfg_validator -->|"builds runtime rules"| node_node_cfg_runtime
node_node_main -->|"starts listener"| node_node_socket
node_node_socket -->|"accepts clients"| node_node_conn
node_node_conn -->|"assembles request"| node_node_req
node_node_req -->|"parses target"| node_node_uri
node_node_req -->|"dispatches"| node_node_router
node_node_cfg_runtime -->|"routes by rules"| node_node_router
node_node_router -->|"serves content"| node_node_webroot
node_node_router -->|"maps failures"| node_node_errors
node_node_router -->|"executes cgi"| node_node_cgi
node_node_router -->|"produces response"| node_node_resp
node_node_cgi -->|"cgi output"| node_node_resp
node_node_resp -->|"writes back"| node_node_socket
node_node_resp -->|"sets cookies"| node_node_cookie
node_node_cookie -->|"supports session"| node_node_session

click node_node_main "https://github.com/maemran/webserver/blob/main/srcs/main.cpp"
click node_node_cfg_lexer "https://github.com/maemran/webserver/blob/main/includes/Config/ConfigLexer.hpp"
click node_node_cfg_parser "https://github.com/maemran/webserver/blob/main/includes/Config/ConfigParser.hpp"
click node_node_cfg_validator "https://github.com/maemran/webserver/blob/main/includes/Config/ConfigValidator.hpp"
click node_node_cfg_runtime "https://github.com/maemran/webserver/blob/main/includes/Config/HttpConfig.hpp"
click node_node_socket "https://github.com/maemran/webserver/blob/main/includes/Socket/serversocket.hpp"
click node_node_conn "https://github.com/maemran/webserver/blob/main/includes/Socket/connection.hpp"
click node_node_req "https://github.com/maemran/webserver/blob/main/includes/HTTP/HttpRequest.hpp"
click node_node_uri "https://github.com/maemran/webserver/blob/main/includes/HTTP/URI.hpp"
click node_node_router "https://github.com/maemran/webserver/blob/main/includes/HTTP/router.hpp"
click node_node_resp "https://github.com/maemran/webserver/blob/main/includes/HTTP/HttpResponse.hpp"
click node_node_cgi "https://github.com/maemran/webserver/blob/main/includes/CGI/CgiHandler.hpp"
click node_node_cookie "https://github.com/maemran/webserver/blob/main/includes/cookies/Cookie.hpp"
click node_node_session "https://github.com/maemran/webserver/blob/main/includes/cookies/Session.hpp"
click node_node_webroot "https://github.com/maemran/webserver/tree/main/webroot"
click node_node_errors "https://github.com/maemran/webserver/tree/main/webroot/errors"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_cfg_lexer,node_node_cfg_parser,node_node_cfg_validator,node_node_cfg_runtime toneBlue
class node_node_socket,node_node_conn toneAmber
class node_node_req,node_node_uri,node_node_router,node_node_resp toneMint
class node_node_cgi toneRose
class node_node_cookie,node_node_session toneIndigo
class node_node_webroot,node_node_errors toneTeal
class node_node_main toneNeutral
```

## Components

### Config

Configuration parsing and runtime server rules

- [Config lexer](https://github.com/maemran/webserver/blob/main/includes/Config/ConfigLexer.hpp): lexer · Tokenizes the config file · `includes/Config/ConfigLexer.hpp`
- [Config parser](https://github.com/maemran/webserver/blob/main/includes/Config/ConfigParser.hpp): parser · Builds structured config objects · `includes/Config/ConfigParser.hpp`
- [Config validator](https://github.com/maemran/webserver/blob/main/includes/Config/ConfigValidator.hpp): validator · Checks config consistency and limits · `includes/Config/ConfigValidator.hpp`
- [Server config](https://github.com/maemran/webserver/blob/main/includes/Config/HttpConfig.hpp): runtime config · HttpConfig, ServerConfig, LocationConfig · `includes/Config/HttpConfig.hpp`

### Network

Socket lifecycle and event-driven client I/O

- [Server socket](https://github.com/maemran/webserver/blob/main/includes/Socket/serversocket.hpp): listener · Bind/listen/accept and multiplexed I/O · `includes/Socket/serversocket.hpp`
- [Connection](https://github.com/maemran/webserver/blob/main/includes/Socket/connection.hpp): client state · Per-client socket buffering and lifecycle · `includes/Socket/connection.hpp`

### HTTP

Request parsing, routing, and response generation

- [Http request](https://github.com/maemran/webserver/blob/main/includes/HTTP/HttpRequest.hpp): request model · Parses method, URI, headers, and body · `includes/HTTP/HttpRequest.hpp`
- [URI](https://github.com/maemran/webserver/blob/main/includes/HTTP/URI.hpp): target parser · Normalizes and interprets request targets · `includes/HTTP/URI.hpp`
- [Router](https://github.com/maemran/webserver/blob/main/includes/HTTP/router.hpp): dispatch · Matches request to server and location rules · `includes/HTTP/router.hpp`
- [Http response](https://github.com/maemran/webserver/blob/main/includes/HTTP/HttpResponse.hpp): response builder · Assembles status, headers, body, and errors · `includes/HTTP/HttpResponse.hpp`

### CGI

Dynamic execution boundary for external scripts

- [Cgi handler](https://github.com/maemran/webserver/blob/main/includes/CGI/CgiHandler.hpp): dynamic exec · Runs external CGI scripts and reads output · `includes/CGI/CgiHandler.hpp`

### State

Lightweight cookie and session support

- [Cookie](https://github.com/maemran/webserver/blob/main/includes/cookies/Cookie.hpp): header support · Formats and parses cookie state · `includes/cookies/Cookie.hpp`
- [Session](https://github.com/maemran/webserver/blob/main/includes/cookies/Session.hpp): session state · Tracks lightweight client session data · `includes/cookies/Session.hpp`

### Content

Served filesystem tree and custom error pages

- [Webroot](https://github.com/maemran/webserver/tree/main/webroot): served files · Static pages, CGI scripts, and error documents · `webroot`
- [Error pages](https://github.com/maemran/webserver/tree/main/webroot/errors): custom docs · Configured 403, 404, and 500 responses · `webroot/errors`

### Other components

- [Server main](https://github.com/maemran/webserver/blob/main/srcs/main.cpp): entrypoint · Program startup and orchestration · `srcs/main.cpp`

## Connections

- Server main → Config lexer: loads config · Startup reads the config file through the config pipeline
- Config lexer → Config parser: tokens · Lexer output feeds the parser
- Config parser → Config validator: validates · Parsed config is checked for correctness and limits
- Config validator → Server config: builds runtime rules · Validated config becomes server and location topology
- Server main → Server socket: starts listener · Main initializes the multiplexed server socket
- Server socket → Connection: accepts clients · Listener creates and manages per-client connection state
- Connection → Http request: assembles request · Incoming bytes are accumulated into HTTP requests
- Http request → URI: parses target · Request target is normalized and interpreted as a URI
- Http request → Router: dispatches · Parsed request enters routing and config matching
- Server config → Router: routes by rules · Router uses server and location config to select behavior
- Router → Webroot: serves content · Static file requests resolve into the served tree
- Router → Error pages: maps failures · Routing and validation errors select custom error pages
- Router → Cgi handler: executes cgi · Configured CGI targets are handed to the CGI subsystem
- Router → Http response: produces response · Routing outcomes are converted into outbound HTTP responses
- Cgi handler → Http response: cgi output · CGI stdout is wrapped into an HTTP response
- Http response → Server socket: writes back · Response data is sent to the client socket
- Http response → Cookie: sets cookies · Response headers may carry cookie metadata
- Cookie → Session: supports session · Cookie state can back lightweight session tracking