# kartofi/choki architecture

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

- Interactive diagram: https://gitdiagram.com/kartofi/choki
- Repository: https://github.com/kartofi/choki

## Overview

##### Project Type & Purpose
- This is a Rust-based HTTP server library inspired by Express.js.
- Its purpose is to allow users to easily define RESTful endpoints (GET, POST, PUT, DELETE), static file handling, and response management (including chunked responses, file downloads, headers, cookies, etc.) using a minimal set of external dependencies (threadpool, num_cpus, flate2, bumpalo).
- It’s meant to be lightweight and give direct control over request parsing and response generation.

##### Analyzing the File Structure
- Top-Level Files and Directories:
- Cargo.toml, Cargo.lock, and Dockerfile indicate a package that is built and can be containerized.
- README.md gives usage examples and describes features.
- Source Code:
- The “src” folder contains both a library file (lib.rs) and an example “main.rs” demonstrating usage.
- Inside “src/src” you have modules like mod.rs (for module scanning), request.rs and response.rs which define the HTTP request/response structures and logic.
- The “src/src/structs.rs” contains core data types.
- The “src/src/utils” folder (with logger.rs and utils.rs) contains supporting utilities like logging and additional helper functions.
- Testing:
- The “tests/static” directory provides sample static files (like an HTML page, a test file, and a video) to validate static endpoint functionality.

##### Main Components
a. Client Interaction:
- Clients (browsers, API consumers) send HTTP requests.
b. HTTP Server:
- A listener that accepts incoming HTTP requests.
- It uses a threadpool (from the threadpool and num_cpus crates) to handle concurrent requests.
c. Router / Endpoint Manager:
- Routes requests to appropriate handlers (GET, POST, PUT, DELETE, or STATIC endpoints).
- Supports endpoints with parameters and query parsing.
d. Request Parser & Data Structures:
- The Request module (src/src/request.rs) parses incoming HTTP data into a Request object which encapsulates queries, URL parameters, headers, cookies, etc.
e. Response Builder:
- The Response module (src/src/response.rs) provides various methods (send_string, send_json, etc.) for building HTTP responses.
f. Static File Handler:
- Logic for serving static files (using a directory like tests/static as a source).
g. Utilities & Logging:
- Utility modules (src/src/utils/) including logger support, to assist with debugging and diagnostics.
h. External Components/Dependencies:
- Thread pool management, compression (using flate2), bump allocation for efficient memory use, etc.

##### Relationships & Data Flow
- Upon receiving a request, the server hands it off to the “Threadpool Manager” which picks a worker thread.
- Each worker thread uses the “Request Parser” to convert raw data into a Request object and interacts with the “Endpoint Router” to find the proper endpoint handler.
- The corresponding Handler (based on the defined GET, POST, etc. endpoints) processes the request.
- The handler then uses the “Response Builder” to prepare the output (sending strings, JSON, files, or streams).
- If the endpoint is static, the “Static File Handler” takes over to locate and serve files from the file system.
- Throughout this flow, utility modules (including Logger) record key events and errors.
- Finally, the response is sent back to the client.

##### Architectural Patterns & Technologies
- Concurrency using thread pools for managing multiple simultaneous requests.
- Separation of concerns: Dedicated modules for HTTP processing (request/response), routing, and utility operations.
- Inspired by Express.js, the API design is modular and declarative for defining endpoints.
- Leverage Rust’s efficient memory management and external crates (bumpalo, flate2, etc.) for performance and low-level control.

##### Final Steps
- Every module (especially those with a direct impact on request/response processing) is included.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client (Browser/API Consumer)"]:::client
    Server["HTTP Server Listener"]:::server
    ThreadPool["Threadpool Manager"]:::threadpool
    ReqParser["Request Parser"]:::parser
    Router["Endpoint Router/Manager"]:::router
    Handler["Endpoint Handler (GET/POST/PUT/DELETE)"]:::handler
    RespBuilder["Response Builder"]:::response
    StaticHandler["Static File Handler"]:::static
    Utils["Utilities & Logging"]:::utils
    CoreData["Core Data Structures"]:::core
    Deploy["Deployment Configuration (Containerization)"]:::deploy

    %% External Dependencies subgraph
    subgraph "External Dependencies"
        TP("Threadpool & num_cpus"):::ext
        FL("Compression (flate2)"):::ext
        BA("Bump Allocator (bumpalo)"):::ext
    end

    %% Main Request Flow
    Client -->|"sends_request"| Server
    Server -->|"dispatches_to"| ThreadPool
    ThreadPool -->|"assigns_worker"| ReqParser
    ReqParser -->|"parses_and_forwards"| Router
    Router -->|"invokes"| Handler
    Handler -->|"builds_response"| RespBuilder
    Router -->|"handles_static"| StaticHandler
    StaticHandler -->|"feeds_into"| RespBuilder
    RespBuilder -->|"sends_response"| Client

    %% Utilities and Core Dependencies (dotted connections)
    ReqParser ---|"logs"| Utils
    Router ---|"logs"| Utils
    RespBuilder ---|"logs"| Utils
    ReqParser ---|"uses"| CoreData
    Router ---|"uses"| CoreData

    %% External Dependencies Usage
    ThreadPool ---|"uses"| TP
    ReqParser ---|"uses"| BA
    RespBuilder ---|"uses"| FL

    %% Deployment Link
    Server ---|"containerized_by"| Deploy

    %% Click Events
    click Server "https://github.com/kartofi/choki/blob/master/src/main.rs"
    click ReqParser "https://github.com/kartofi/choki/blob/master/src/src/request.rs"
    click RespBuilder "https://github.com/kartofi/choki/blob/master/src/src/response.rs"
    click Router "https://github.com/kartofi/choki/blob/master/src/src/mod.rs"
    click CoreData "https://github.com/kartofi/choki/blob/master/src/src/structs.rs"
    click Utils "https://github.com/kartofi/choki/blob/master/src/src/utils/logger.rs"
    click Utils "https://github.com/kartofi/choki/blob/master/src/src/utils/utils.rs"
    click StaticHandler "https://github.com/kartofi/choki/tree/master/tests/static"
    click Deploy "https://github.com/kartofi/choki/tree/master/Dockerfile"

    %% Styles
    classDef client fill:#ffeb3b,stroke:#333,stroke-width:2px;
    classDef server fill:#9ccc65,stroke:#333,stroke-width:2px;
    classDef threadpool fill:#90caf9,stroke:#333,stroke-width:2px;
    classDef parser fill:#a5d6a7,stroke:#333,stroke-width:2px;
    classDef router fill:#ce93d8,stroke:#333,stroke-width:2px;
    classDef handler fill:#f48fb1,stroke:#333,stroke-width:2px;
    classDef response fill:#80deea,stroke:#333,stroke-width:2px;
    classDef static fill:#ffe082,stroke:#333,stroke-width:2px;
    classDef utils fill:#e0e0e0,stroke:#333,stroke-width:2px;
    classDef core fill:#b0bec5,stroke:#333,stroke-width:2px;
    classDef ext fill:#ffab91,stroke:#333,stroke-width:2px;
    classDef deploy fill:#d7ccc8,stroke:#333,stroke-width:2px;
```
