# jeremycw/httpserver.h architecture

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

- Interactive diagram: https://gitdiagram.com/jeremycw/httpserver.h
- Repository: https://github.com/jeremycw/httpserver.h

## Overview

httpserver.h is a single-header C library for non-blocking, event-driven HTTP servers on Linux epoll and BSD/macOS kqueue. Its main workflow accepts a client connection, reads and parses an HTTP request, invokes the application’s request handler, then serializes and writes the response; connections can be reused or closed, and responses can be chunked. The graph separates event dispatch, request processing, response handling, and the public API. Some source is unsampled, so only documented or indexed relationships are shown; unverified links are omitted.

Main entry points: [`src/io_events.c`](https://github.com/jeremycw/httpserver.h/blob/master/src/io_events.c) (Event dispatch), [`src/api.h`](https://github.com/jeremycw/httpserver.h/blob/master/src/api.h) (Public API), [`src/read_socket.c`](https://github.com/jeremycw/httpserver.h/blob/master/src/read_socket.c) (Socket reading), [`src/server.c`](https://github.com/jeremycw/httpserver.h/blob/master/src/server.c) (Server lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_api["Public API<br/>[api.h]"]
end

subgraph group_events["Event and connection runtime"]
  node_server["Server lifecycle<br/>[server.c]"]
  node_connection["Connection management<br/>[connection.c]"]
  node_dispatch["Event dispatch<br/>[io_events.c]"]
  node_shared_state["Session state<br/>[common.h]"]
end

subgraph group_requests["Request processing"]
  node_read["Socket reading<br/>[read_socket.c]"]
  node_parser["HTTP parser<br/>[parser.rl]"]
  node_request_util["Request accessors<br/>[request_util.c]"]
  node_buffers["Buffer utilities<br/>[buffer_util.h]"]
end

subgraph group_responses["Response handling"]
  node_response["Response construction<br/>[respond.c]"]
  node_write["Socket writing<br/>[write_socket.c]"]
end

node_client(("HTTP client"))
node_app(("Application handler"))

node_client -->|"connects to"| node_server
node_api -->|"configures"| node_server
node_api -->|"exposes"| node_request_util
node_api -->|"exposes"| node_response
node_server -.->|"runs events"| node_dispatch
node_dispatch -->|"accepts clients"| node_connection
node_dispatch -->|"reads requests"| node_read
node_dispatch -->|"writes responses"| node_write
node_read -->|"parses bytes"| node_parser
node_read -.->|"invokes handler"| node_app
node_app -->|"uses API"| node_api
node_api -->|"submits response"| node_response
node_response -->|"serializes response"| node_write
node_request_util -->|"reads tokens"| node_parser
node_dispatch -->|"frees buffers"| node_buffers
node_dispatch -->|"updates session"| node_shared_state
node_connection -.->|"manages session"| node_shared_state

click node_api "https://github.com/jeremycw/httpserver.h/blob/master/src/api.h"
click node_server "https://github.com/jeremycw/httpserver.h/blob/master/src/server.c"
click node_connection "https://github.com/jeremycw/httpserver.h/blob/master/src/connection.c"
click node_dispatch "https://github.com/jeremycw/httpserver.h/blob/master/src/io_events.c"
click node_read "https://github.com/jeremycw/httpserver.h/blob/master/src/read_socket.c"
click node_parser "https://github.com/jeremycw/httpserver.h/blob/master/src/parser.rl"
click node_request_util "https://github.com/jeremycw/httpserver.h/blob/master/src/request_util.c"
click node_response "https://github.com/jeremycw/httpserver.h/blob/master/src/respond.c"
click node_write "https://github.com/jeremycw/httpserver.h/blob/master/src/write_socket.c"
click node_buffers "https://github.com/jeremycw/httpserver.h/blob/master/src/buffer_util.h"
click node_shared_state "https://github.com/jeremycw/httpserver.h/blob/master/src/common.h"

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_api,node_client toneBlue
class node_server,node_connection,node_dispatch,node_shared_state toneAmber
class node_read,node_parser,node_request_util,node_buffers,node_app toneMint
class node_response,node_write toneRose
```

## Components

### Public API

- [Public API](https://github.com/jeremycw/httpserver.h/blob/master/src/api.h): `src/api.h`

### Event and connection runtime

- [Server lifecycle](https://github.com/jeremycw/httpserver.h/blob/master/src/server.c): `src/server.c`
- [Connection management](https://github.com/jeremycw/httpserver.h/blob/master/src/connection.c): `src/connection.c`
- [Event dispatch](https://github.com/jeremycw/httpserver.h/blob/master/src/io_events.c): `src/io_events.c`
- [Session state](https://github.com/jeremycw/httpserver.h/blob/master/src/common.h): `src/common.h`

### Request processing

- [Socket reading](https://github.com/jeremycw/httpserver.h/blob/master/src/read_socket.c): `src/read_socket.c`
- [HTTP parser](https://github.com/jeremycw/httpserver.h/blob/master/src/parser.rl): `src/parser.rl`
- [Request accessors](https://github.com/jeremycw/httpserver.h/blob/master/src/request_util.c): `src/request_util.c`
- [Buffer utilities](https://github.com/jeremycw/httpserver.h/blob/master/src/buffer_util.h): `src/buffer_util.h`

### Response handling

- [Response construction](https://github.com/jeremycw/httpserver.h/blob/master/src/respond.c): `src/respond.c`
- [Socket writing](https://github.com/jeremycw/httpserver.h/blob/master/src/write_socket.c): `src/write_socket.c`

### Other components

- **HTTP client**
- **Application handler**

## Connections

- HTTP client → Server lifecycle: connects to (evidence: `README.md`)
- Public API → Server lifecycle: configures
- Public API → Request accessors: exposes
- Public API → Response construction: exposes
- Server lifecycle → Event dispatch: runs events
- Event dispatch → Connection management: accepts clients (evidence: `src/io_events.c`)
- Event dispatch → Socket reading: reads requests (evidence: `src/io_events.c`)
- Event dispatch → Socket writing: writes responses (evidence: `src/io_events.c`)
- Socket reading → HTTP parser: parses bytes (evidence: `src/read_socket.c`)
- Socket reading → Application handler: invokes handler
- Application handler → Public API: uses API (evidence: `README.md`)
- Public API → Response construction: submits response (evidence: `README.md`)
- Response construction → Socket writing: serializes response
- Request accessors → HTTP parser: reads tokens
- Event dispatch → Buffer utilities: frees buffers (evidence: `src/io_events.c`)
- Event dispatch → Session state: updates session (evidence: `src/io_events.c`)
- Connection management → Session state: manages session (evidence: `src/connection.c`)
