# dexter-xd/nxlite architecture

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

- Interactive diagram: https://gitdiagram.com/dexter-xd/nxlite
- Repository: https://github.com/dexter-xd/nxlite

## Overview

##### Project Type and Purpose
- NxLite is a standalone, high-performance HTTP server written in C.
- It follows a master-worker (pre-fork) model to handle thousands of concurrent connections efficiently, using epoll for non-blocking I/O, zero-copy sendfile, in-memory caching, and a custom memory pool.

##### File Structure Analysis
- Top-level: CMake build files, configuration (server.conf), static content (static/index.html), headers (include/*.h), and source code (src/*.c).
- src/main.c initializes the server (reads config, forks master), src/master.c manages worker processes, src/worker.c contains per-connection logic, src/http.c and src/server.c parse/process requests, src/mempool.c implements custom allocator, src/log.c handles logging, src/shutdown.c handles graceful shutdown.

##### Key Components
a. External Clients – browsers or benchmarking tools (ab, wrk, hey)
b. Master Process
- Reads server.conf
- Creates and binds listening socket
- Forks N worker processes and supervises them
- Handles graceful shutdown/restart
c. Shared Listening Socket
- A single socket descriptor passed via fork to all workers
d. Worker Processes (multiple instances)
- Each runs an event loop (epoll)
- Accepts new connections from the shared socket
- Parses HTTP requests (http.c)
- Uses memory pool (mempool.c) for buffers
- Checks in-memory cache for static assets (simple hash or lookup)
- Serves static files using zero-copy sendfile()
- Writes access/error logs (log.c)
- Manages keep-alive and connection teardown
e. Operating System Kernel
- epoll subsystem
- sendfile zero-copy path
- TCP/IP stack
f. File System
- Static root directory (static/)
- Log files (e.g., build/logs/access.log)

##### Relationships and Data Flow
- Clients → TCP connection → Master Process’s listening socket
- Shared Listening Socket → Worker’s epoll wait → Worker accepts
- Worker: parse request → check cache →
- cache hit → generate response in memory → send over socket
- cache miss → open file → sendfile() → store in cache → send over socket
- Worker → writes logs → Log file on disk
- Master ↔ Worker (monitoring via signals or IPC for health checks)

##### Architectural Patterns & Design Principles
- Master-Worker (pre-fork) pattern for process isolation and multi-core utilization
- Event-driven, non-blocking I/O (epoll) for high concurrency
- Zero-copy I/O (sendfile) for minimal CPU overhead on file transfers
- Custom memory pooling to reduce fragmentation and allocator overhead
- Simple in-memory caching for static assets

##### Detail and Clarity
- Shared listening socket as a central hub fed into each worker.
- Explicitly capture the OS kernel’s role in epoll and sendfile.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    Clients["External Clients"]:::external

    %% Master Layer
    subgraph "Master & Control"
        Master["Master Process"]:::process
        ConfigLoader["Configuration Loader"]:::process
        Shutdown["Graceful Shutdown"]:::process
        SharedSocket["Shared Listening Socket"]:::process
    end

    %% Worker Pool
    subgraph "Worker Pool"
        Worker["Worker Process"]:::process
        subgraph "Worker Internals"
            EventLoop["Epoll Event Loop"]:::kernel
            HTTPParser["HTTP Parser"]:::process
            MemoryPool["Memory Pool"]:::cache
            InMemoryCache["In-Memory Cache"]:::cache
            FileIO["File I/O (sendfile)"]:::kernel
            Log["Logging Module"]:::external
        end
    end

    %% OS Kernel
    subgraph "OS Kernel"
        Epoll["epoll subsystem"]:::kernel
        Sendfile["sendfile zero-copy"]:::kernel
        TCPIP["TCP/IP Stack"]:::kernel
    end

    %% File System
    subgraph "File System"
        StaticContent["Static Content Directory"]:::filesystem
        LogFiles["Log Files"]:::filesystem
        BuildConfig["Build Configuration"]:::filesystem
    end

    %% Connections
    Clients -->|"TCP connect"| SharedSocket
    SharedSocket -->|"fork & inherit"| Worker
    Master -->|"fork()/supervise"| Worker
    Master -->|"read config"| ConfigLoader
    Master -->|"handle signals"| Shutdown

    Worker -->|"epoll_wait()"| EventLoop
    EventLoop -->|"accept()"| Worker
    Worker -->|"parse request"| HTTPParser
    HTTPParser --> Worker
    Worker -->|"allocate buffer"| MemoryPool
    Worker -->|"check cache"| InMemoryCache
    InMemoryCache -->|hit| Worker
    InMemoryCache -->|miss| FileIO
    FileIO -->|"sendfile()"| TCPIP
    TCPIP --> Clients
    Worker -->|"write_log()"| Log
    Log --> LogFiles
    FileIO --> StaticContent
    ConfigLoader -->|"read file"| BuildConfig

    %% Kernel interactions
    EventLoop --> Epoll
    FileIO --> Sendfile
    TCPIP --> Epoll

    %% Click Events
    click Master "https://github.com/dexter-xd/nxlite/blob/main/include/master.h"
    click Master "https://github.com/dexter-xd/nxlite/blob/main/src/master.c"
    click Master "https://github.com/dexter-xd/nxlite/blob/main/src/main.c"
    click Worker "https://github.com/dexter-xd/nxlite/blob/main/include/worker.h"
    click Worker "https://github.com/dexter-xd/nxlite/blob/main/src/worker.c"
    click SharedSocket "https://github.com/dexter-xd/nxlite/blob/main/include/server.h"
    click SharedSocket "https://github.com/dexter-xd/nxlite/blob/main/src/server.c"
    click HTTPParser "https://github.com/dexter-xd/nxlite/blob/main/include/http.h"
    click HTTPParser "https://github.com/dexter-xd/nxlite/blob/main/src/http.c"
    click MemoryPool "https://github.com/dexter-xd/nxlite/blob/main/include/mempool.h"
    click MemoryPool "https://github.com/dexter-xd/nxlite/blob/main/src/mempool.c"
    click Log "https://github.com/dexter-xd/nxlite/blob/main/include/log.h"
    click Log "https://github.com/dexter-xd/nxlite/blob/main/src/log.c"
    click ConfigLoader "https://github.com/dexter-xd/nxlite/blob/main/include/config.h"
    click ConfigLoader "https://github.com/dexter-xd/nxlite/blob/main/src/config.c"
    click ConfigLoader "https://github.com/dexter-xd/nxlite/blob/main/server.conf"
    click Shutdown "https://github.com/dexter-xd/nxlite/blob/main/include/shutdown.h"
    click Shutdown "https://github.com/dexter-xd/nxlite/blob/main/src/shutdown.c"
    click StaticContent "https://github.com/dexter-xd/nxlite/blob/main/static/index.html"
    click BuildConfig "https://github.com/dexter-xd/nxlite/blob/main/CMakeLists.txt"

    %% Styles
    classDef process fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef kernel fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef filesystem fill:#90EE90,stroke:#000,stroke-width:1px
    classDef cache fill:#FFD700,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
```
