# unf0r9et/ceptember architecture

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

- Interactive diagram: https://gitdiagram.com/unf0r9et/ceptember
- Repository: https://github.com/unf0r9et/ceptember

## Overview

1. **Overall shape**
   CEPTEMBER is a small C++ HTTP micro-framework built around the Linux socket API. The repo is split into a reusable `core/` framework layer and an application layer under `src/main/` that defines the actual route handlers.

2. **Startup and server runtime**
   `src/main/main.cpp` is the entry point. It boots the server engine in `core/engine/engine.cpp`, which is the central runtime component responsible for accepting connections and driving the request/response flow.

3. **Request lifecycle**
   Raw network data is parsed into a `requestEntity` object. That entity is the shared request model used by the rest of the stack: method, path, headers, and body. The README notes that oversized bodies can be moved to disk, with the body field then holding a file path instead of inline bytes.

4. **HTTP parsing layer**
   Parsing is handled by `core/parser/` and includes two important pieces: `picoHttpParser` for HTTP message parsing and `MultipartParser` for multipart/form-data. This layer turns socket input into structured request data and is the main boundary between transport bytes and application logic.

5. **Dispatch and routing**
   `core/httpController/httpController.cpp` routes requests by HTTP method. The method-specific entry points are `methods_GET`, `methods_POST`, `methods_PUT`, and `methods_DELETE`, which are implemented in `src/main/handlers/*.cpp`. Routing within handlers uses a custom hashed-string switch mechanism, so path-based dispatch is compile-time-friendly and avoids chained string comparisons.

6. **Application handler layer**
   The four files in `src/main/handlers/` are the user extension points. They contain the project-specific business logic for each verb and decide how to respond to a given path. The README’s example shows handlers reading from a thread-local `rqEntity`, so per-request state is exposed directly to handler code.

7. **Static file serving**
   Static content is handled separately by `core/staticHandler/staticHandler.cpp` and its related file-search/read helpers. The framework is designed to map URL paths to directories under `static/`, so HTML/CSS/JS are treated as a distinct serving path from API-style request handlers.

8. **File upload and large-body processing**
   There is a dedicated upload/storage subsystem: `fileSaver`, `MultipartParser`, `requestBodiesWorker`, and the type-specific workers under `core/utils/workers/` (`photoWorker`, `videoWorker`, `txtWorker`, `docsWorker`). This suggests the framework can classify incoming content and persist it appropriately rather than keeping all uploads in memory.

9. **Filesystem helpers**
   File I/O is factored into reusable helpers: `fileReader`, `fileWriter`, `fileSearch`, and `deleteFile`. These are used by both static serving and upload persistence, which keeps low-level filesystem concerns out of the request handlers.

10. **Response construction**
   Responses are built through two layers: `basicResponse` provides standard canned HTTP responses such as 404/405, while `responseBuilder` assembles custom responses with headers, status, content type, and optional binary attachments. This cleanly separates simple error responses from dynamic or file-backed responses.

11. **Core API vs internal implementation**
   `core/publicHeaders/` exposes the framework-facing API (`engine.hpp`, `httpController.hpp`, `requestEntity.hpp`, `responseBuilder.hpp`, `fileSaver.hpp`, `logger.hpp`). `core/internalHeaders/` contains implementation details used by the framework itself. That boundary is important for diagramming: application code depends on the public headers, while the parser/workers/storage internals stay inside the core.

12. **Cross-cutting concerns**
   `core/logger/logger.cpp` provides logging, and `core/raindrop.hpp` appears to act as an umbrella include for framework internals. The build is managed with `CMakeLists.txt`, so the project is packaged as a native C++ service rather than a web framework deployed on a separate runtime.

13. **Key architecture takeaway**
   The main flow is: socket input → HTTP parsing → `requestEntity` → method dispatch in `httpController` → route handler → static/file/response utilities → serialized HTTP response back to the client. The main boundaries are transport/parsing, request dispatch, filesystem/file upload handling, and response construction.

Main entry points: [`core/publicHeaders/engine.hpp`](https://github.com/unf0r9et/ceptember/blob/main/core/publicHeaders/engine.hpp) (Public API), [`core/utils/workers/requestBodiesWorker/requestBodiesWorker.cpp`](https://github.com/unf0r9et/ceptember/blob/main/core/utils/workers/requestBodiesWorker/requestBodiesWorker.cpp) (Body worker), [`src/main/handlers/GET.cpp`](https://github.com/unf0r9et/ceptember/blob/main/src/main/handlers/GET.cpp) (Route handlers), [`core/engine/engine.cpp`](https://github.com/unf0r9et/ceptember/blob/main/core/engine/engine.cpp) (Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build & support"]
  node_logger["Logger<br/>logging<br/>[logger.cpp]"]
end

subgraph group_core["Framework core"]
  node_engine["Engine<br/>runtime<br/>[engine.cpp]"]
  node_http_controller["HTTP controller<br/>dispatcher<br/>[httpController.cpp]"]
  node_parser["Parser<br/>request parsing<br/>[parser.cpp]"]
  node_pico_parser["HTTP parser<br/>[picoHttpParser.c]"]
  node_multipart_parser["Multipart parser"]
  node_request_entity["Request entity<br/>request model<br/>[requestEntity.hpp]"]
  node_static_handler["Static handler<br/>file serving<br/>[staticHandler.cpp]"]
  node_response_builder["Response builder<br/>response assembly"]
  node_basic_response["Basic responses<br/>canned responses<br/>[basicResponse.h]"]
  node_file_saver["File saver<br/>upload storage<br/>[fileSaver.cpp]"]
  node_request_bodies_worker["Body worker<br/>body processing"]
  node_photo_worker["Photo worker<br/>media worker<br/>[photoWorker.cpp]"]
  node_video_worker["Video worker<br/>media worker<br/>[videoWorker.cpp]"]
  node_txt_worker["Text worker<br/>content worker<br/>[txtWorker.cpp]"]
  node_docs_worker["Docs worker<br/>content worker<br/>[docsWorker.cpp]"]
  node_file_io["File IO<br/>filesystem helpers<br/>[fileReader.cpp]"]
  node_public_api["Public API<br/>framework API<br/>[engine.hpp]"]
  node_internal_api["Internal headers<br/>internal API<br/>[parser.hpp]"]
end

subgraph group_app["Application layer"]
  node_main["Main<br/>entrypoint<br/>[main.cpp]"]
  node_handlers["Route handlers<br/>application routes<br/>[GET.cpp]"]
end

node_main -->|"boots"| node_engine
node_engine -->|"parses"| node_parser
node_parser -->|"uses"| node_pico_parser
node_parser -->|"uses"| node_multipart_parser
node_parser -->|"builds"| node_request_entity
node_engine -->|"dispatches"| node_http_controller
node_http_controller -->|"calls"| node_handlers
node_handlers -->|"creates"| node_response_builder
node_handlers -->|"returns"| node_basic_response
node_handlers -->|"serves"| node_static_handler
node_handlers -->|"stores"| node_file_saver
node_file_saver -->|"delegates"| node_request_bodies_worker
node_request_bodies_worker -->|"classifies"| node_photo_worker
node_request_bodies_worker -->|"classifies"| node_video_worker
node_request_bodies_worker -->|"classifies"| node_txt_worker
node_request_bodies_worker -->|"classifies"| node_docs_worker
node_static_handler -->|"reads"| node_file_io
node_file_saver -->|"writes"| node_file_io
node_response_builder -->|"reuses"| node_basic_response
node_engine -->|"logs"| node_logger
node_public_api -->|"exposes"| node_engine
node_public_api -->|"exposes"| node_http_controller
node_public_api -->|"exposes"| node_request_entity
node_public_api -->|"exposes"| node_response_builder
node_public_api -->|"exposes"| node_file_saver
node_public_api -->|"exposes"| node_logger
node_internal_api -->|"supports"| node_parser
node_internal_api -->|"supports"| node_static_handler
node_internal_api -->|"supports"| node_file_io
node_internal_api -->|"supports"| node_request_bodies_worker

click node_main "https://github.com/unf0r9et/ceptember/blob/main/src/main/main.cpp"
click node_engine "https://github.com/unf0r9et/ceptember/blob/main/core/engine/engine.cpp"
click node_http_controller "https://github.com/unf0r9et/ceptember/blob/main/core/httpController/httpController.cpp"
click node_parser "https://github.com/unf0r9et/ceptember/blob/main/core/parser/parser.cpp"
click node_pico_parser "https://github.com/unf0r9et/ceptember/blob/main/core/parser/picoHttpParser/picoHttpParser.c"
click node_multipart_parser "https://github.com/unf0r9et/ceptember/blob/main/core/parser/MultipartParser/MultipartParser.cpp"
click node_request_entity "https://github.com/unf0r9et/ceptember/blob/main/core/publicHeaders/requestEntity.hpp"
click node_static_handler "https://github.com/unf0r9et/ceptember/blob/main/core/staticHandler/staticHandler.cpp"
click node_response_builder "https://github.com/unf0r9et/ceptember/blob/main/core/utils/responseBuilder/responseBuilder.cpp"
click node_basic_response "https://github.com/unf0r9et/ceptember/blob/main/core/publicHeaders/basicResponse.h"
click node_file_saver "https://github.com/unf0r9et/ceptember/blob/main/core/utils/fileSaver/fileSaver.cpp"
click node_request_bodies_worker "https://github.com/unf0r9et/ceptember/blob/main/core/utils/workers/requestBodiesWorker/requestBodiesWorker.cpp"
click node_photo_worker "https://github.com/unf0r9et/ceptember/blob/main/core/utils/workers/photoWorker/photoWorker.cpp"
click node_video_worker "https://github.com/unf0r9et/ceptember/blob/main/core/utils/workers/videoWorker/videoWorker.cpp"
click node_txt_worker "https://github.com/unf0r9et/ceptember/blob/main/core/utils/workers/txtWorker/txtWorker.cpp"
click node_docs_worker "https://github.com/unf0r9et/ceptember/blob/main/core/utils/workers/docsWorker/docsWorker.cpp"
click node_file_io "https://github.com/unf0r9et/ceptember/blob/main/core/utils/workers/fileWorker/fileReader.cpp"
click node_logger "https://github.com/unf0r9et/ceptember/blob/main/core/logger/logger.cpp"
click node_public_api "https://github.com/unf0r9et/ceptember/blob/main/core/publicHeaders/engine.hpp"
click node_internal_api "https://github.com/unf0r9et/ceptember/blob/main/core/internalHeaders/parser.hpp"
click node_handlers "https://github.com/unf0r9et/ceptember/blob/main/src/main/handlers/GET.cpp"

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_logger toneBlue
class node_engine,node_http_controller,node_parser,node_pico_parser,node_multipart_parser,node_request_entity,node_static_handler,node_response_builder,node_basic_response,node_file_saver,node_request_bodies_worker,node_photo_worker,node_video_worker,node_txt_worker,node_docs_worker,node_file_io,node_public_api,node_internal_api toneAmber
class node_main,node_handlers toneMint
```

## Components

### Build & support

Project packaging and cross-cutting support

- [Logger](https://github.com/unf0r9et/ceptember/blob/main/core/logger/logger.cpp): logging · Cross-cutting logging facility for framework activity. · `core/logger/logger.cpp`

### Framework core

HTTP runtime, parsing, routing, storage, and response utilities

- [Engine](https://github.com/unf0r9et/ceptember/blob/main/core/engine/engine.cpp): runtime · Central server loop that accepts connections and drives request handling. · `core/engine/engine.cpp`
- [HTTP controller](https://github.com/unf0r9et/ceptember/blob/main/core/httpController/httpController.cpp): dispatcher · Routes requests by HTTP method into the application handler layer. · `core/httpController/httpController.cpp`
- [Parser](https://github.com/unf0r9et/ceptember/blob/main/core/parser/parser.cpp): request parsing · Converts raw socket input into structured request data. · `core/parser/parser.cpp`
- [HTTP parser](https://github.com/unf0r9et/ceptember/blob/main/core/parser/picoHttpParser/picoHttpParser.c): HTTP parse · Parses HTTP messages and headers from the network stream. · `core/parser/picoHttpParser/picoHttpParser.c`
- [Multipart parser](https://github.com/unf0r9et/ceptember/blob/main/core/parser/MultipartParser/MultipartParser.cpp): multipart parse · Extracts multipart/form-data payloads for uploads. · `core/parser/MultipartParser/MultipartParser.cpp`
- [Request entity](https://github.com/unf0r9et/ceptember/blob/main/core/publicHeaders/requestEntity.hpp): request model · Shared request state for method, path, headers, and body. · `core/publicHeaders/requestEntity.hpp`
- [Static handler](https://github.com/unf0r9et/ceptember/blob/main/core/staticHandler/staticHandler.cpp): file serving · Maps URL paths to files and serves static assets. · `core/staticHandler/staticHandler.cpp`
- [Response builder](https://github.com/unf0r9et/ceptember/blob/main/core/utils/responseBuilder/responseBuilder.cpp): response assembly · Builds custom HTTP responses, headers, and attachments. · `core/utils/responseBuilder/responseBuilder.cpp`
- [Basic responses](https://github.com/unf0r9et/ceptember/blob/main/core/publicHeaders/basicResponse.h): canned responses · Provides standard responses such as 404 and 405. · `core/publicHeaders/basicResponse.h`
- [File saver](https://github.com/unf0r9et/ceptember/blob/main/core/utils/fileSaver/fileSaver.cpp): upload storage · Persists uploaded content and large request bodies to disk. · `core/utils/fileSaver/fileSaver.cpp`
- [Body worker](https://github.com/unf0r9et/ceptember/blob/main/core/utils/workers/requestBodiesWorker/requestBodiesWorker.cpp): body processing · Coordinates classification and handling of incoming request bodies. · `core/utils/workers/requestBodiesWorker/requestBodiesWorker.cpp`
- [Photo worker](https://github.com/unf0r9et/ceptember/blob/main/core/utils/workers/photoWorker/photoWorker.cpp): media worker · Handles image-oriented upload persistence and processing. · `core/utils/workers/photoWorker/photoWorker.cpp`
- [Video worker](https://github.com/unf0r9et/ceptember/blob/main/core/utils/workers/videoWorker/videoWorker.cpp): media worker · Handles video-oriented upload persistence and processing. · `core/utils/workers/videoWorker/videoWorker.cpp`
- [Text worker](https://github.com/unf0r9et/ceptember/blob/main/core/utils/workers/txtWorker/txtWorker.cpp): content worker · Handles text upload persistence and processing. · `core/utils/workers/txtWorker/txtWorker.cpp`
- [Docs worker](https://github.com/unf0r9et/ceptember/blob/main/core/utils/workers/docsWorker/docsWorker.cpp): content worker · Handles document upload persistence and processing. · `core/utils/workers/docsWorker/docsWorker.cpp`
- [File IO](https://github.com/unf0r9et/ceptember/blob/main/core/utils/workers/fileWorker/fileReader.cpp): filesystem helpers · Shared file read, write, and search helpers used by serving and upload paths. · `core/utils/workers/fileWorker/fileReader.cpp`
- [Public API](https://github.com/unf0r9et/ceptember/blob/main/core/publicHeaders/engine.hpp): framework API · Framework-facing headers exposed to application code. · `core/publicHeaders/engine.hpp`
- [Internal headers](https://github.com/unf0r9et/ceptember/blob/main/core/internalHeaders/parser.hpp): internal API · Implementation-only headers for parsing, storage, and workers. · `core/internalHeaders/parser.hpp`

### Application layer

Project-specific entrypoint and route handlers

- [Main](https://github.com/unf0r9et/ceptember/blob/main/src/main/main.cpp): entrypoint · Starts the server process and hands control to the framework engine. · `src/main/main.cpp`
- [Route handlers](https://github.com/unf0r9et/ceptember/blob/main/src/main/handlers/GET.cpp): application routes · Verb-specific application logic for GET, POST, PUT, and DELETE. · `src/main/handlers/GET.cpp`

## Connections

- Main → Engine: boots · Application startup transfers control into the server runtime.
- Engine → Parser: parses · Runtime sends raw network data into the request parsing pipeline.
- Parser → HTTP parser: uses · Core parser delegates HTTP message parsing to the low-level HTTP parser.
- Parser → Multipart parser: uses · Core parser delegates multipart form parsing to the multipart parser.
- Parser → Request entity: builds · Parsed request data is assembled into the shared request model.
- Engine → HTTP controller: dispatches · Completed requests are routed into method-based dispatch.
- HTTP controller → Route handlers: calls · Dispatcher invokes the application-defined verb handlers.
- Route handlers → Response builder: creates · Handlers construct custom responses for successful and dynamic outcomes.
- Route handlers → Basic responses: returns · Handlers can emit canned error or fallback responses.
- Route handlers → Static handler: serves · Handlers may route file-like paths through the static serving path.
- Route handlers → File saver: stores · Handlers can persist uploads or large bodies through the storage path.
- File saver → Body worker: delegates · Upload persistence is coordinated by request-body processing workers.
- Body worker → Photo worker: classifies · Media-specific handling for images.
- Body worker → Video worker: classifies · Media-specific handling for videos.
- Body worker → Text worker: classifies · Media-specific handling for text payloads.
- Body worker → Docs worker: classifies · Media-specific handling for document payloads.
- Static handler → File IO: reads · Static serving relies on shared filesystem read/search helpers.
- File saver → File IO: writes · Upload persistence uses shared filesystem read/write helpers.
- Response builder → Basic responses: reuses · Custom response assembly can fall back to canned responses.
- Engine → Logger: logs · Runtime events and errors are reported through the logger.
- Public API → Engine: exposes · Public headers expose the server engine interface to application code.
- Public API → HTTP controller: exposes · Public headers expose dispatch interfaces to application code.
- Public API → Request entity: exposes · Public headers expose the request model to handlers.
- Public API → Response builder: exposes · Public headers expose response construction APIs.
- Public API → File saver: exposes · Public headers expose upload/storage APIs.
- Public API → Logger: exposes · Public headers expose logging APIs.
- Internal headers → Parser: supports · Internal headers define parser internals and shared declarations.
- Internal headers → Static handler: supports · Internal headers define static serving internals.
- Internal headers → File IO: supports · Internal headers define filesystem helper declarations.
- Internal headers → Body worker: supports · Internal headers define body-processing worker internals.