# z101/quark architecture

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

- Interactive diagram: https://gitdiagram.com/z101/quark
- Repository: https://github.com/z101/quark

## Overview

##### Project type and purpose
- quark is a minimalist, single-host HTTP web server written in C.
- Its core features are:
- Serving static files from a specified web-root directory
- Basic CGI support for dynamic content

##### File structure
- Top-level C source and headers:
- quark.c            – main server loop, dispatch, request parser
- arg.h              – command-line argument definitions
- config.def.h       – compile-time defaults for ports, paths, etc.
- config.mk          – user’s local build/install configuration
- Build and packaging:
- Makefile           – build, clean, install targets
- LICENSE, .gitignore, patches, Debian init script (quark.daemon.debian)
- quark.1            – manpage for server usage

##### README for additional insights
- Confirms configuration via config.mk
- Installation path (/usr/local/bin) and startup invocation (sudo quark)
- Operational flow: change into <web-root>, run quark to bind port 80 and handle HTTP requests

a. Main components
1. Client (Web browser or HTTP client)
2. quark Server Process
- Command‐line / config parser
- Listener / socket accept loop
- HTTP request parser
- Static file handler
- CGI launcher (fork + exec)
- Response generator (headers, payload)
- Logger (optional status logging)
3. File System (web-root directory, CGI scripts)
4. Operating System / Network Stack (TCP/IP, process management)
b. Relationships and interactions
- Client → TCP/IP stack → quark listener socket
- quark request parser dispatches to either:
- Static file handler → File I/O → File System → build response
- CGI handler → fork/exec CGI script → capture stdout → build response
- quark → TCP/IP stack → client (response)
- quark logs events (errors/status) to stdout or log file
c. Architectural patterns & design principles
- Single-process, sequential or simple event loop (no thread pool)
- Modular dispatch: parsing → handler → response
- Compile‐time configuration via headers and Makefile
d. Key technologies & libraries
- POSIX sockets for networking
- Standard C library for file I/O, string parsing, fork/exec
- Makefile for build automation
- CGI standard for dynamic scripts

##### Detailed capture of essential elements
1. Config & Argument Parser
2. Socket Acceptor
3. HTTP Parser
4. Static File Server
5. CGI Dispatcher
6. Logger
- How build files (config.mk, config.def.h) feed into the compiled binary (quark).
- Call out the manpage and Debian init script as deployment artifacts (not part of runtime flow but part of the overall system lifecycle).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Network Layer
    Client["Client (Browser)"]:::network
    OS["OS Kernel\n(TCP/IP & Process Mgmt)"]:::network

    %% Server Process
    subgraph "quark Server Process"
        Config["Config & Arg Parser"]:::server
        Listener["Socket Acceptor"]:::server
        HTTP["HTTP Parser"]:::server
        Static["Static File Handler"]:::server
        CGI["CGI Dispatcher"]:::server
        Response["Response Generator"]:::server
        Logger["Logger"]:::server
    end

    %% Storage
    FileSys["File System\n(Web-root)"]:::storage

    %% Build & Deployment
    subgraph "Build & Deployment"
        argh["arg.h"]:::artifact
        cfgdef["config.def.h"]:::artifact
        cfgmk["config.mk"]:::artifact
        mkfile["Makefile"]:::artifact
        qman["quark.1 (Manpage)"]:::artifact
        qinit["quark.daemon.debian"]:::artifact
        p1["patch.01.fixstatus"]:::artifact
        p2["patch.02.sanelog"]:::artifact
        quarkbin["quark (Compiled Binary)"]:::artifact
    end

    %% Runtime Flow
    Client -->|"HTTP Request\n(GET/POST)"| OS
    OS --> Listener
    Listener --> HTTP
    HTTP -->|"Static Request"| Static
    HTTP -->|"CGI Request"| CGI
    Static -->|"file read"| FileSys
    CGI -->|"fork/exec\nstdout capture"| OS
    Static --> Response
    CGI --> Response
    Response --> OS
    OS -->|"HTTP Response"| Client

    %% Logging
    HTTP --> Logger
    Static --> Logger
    CGI --> Logger

    %% Build Flow
    argh --> quarkbin
    cfgdef --> quarkbin
    cfgmk --> quarkbin
    mkfile --> quarkbin
    p1 --> quarkbin
    p2 --> quarkbin

    %% Deployment Artifacts
    quarkbin --> qman
    quarkbin --> qinit

    %% Click Events
    click Config "https://github.com/z101/quark/blob/master/arg.h"
    click Config "https://github.com/z101/quark/blob/master/config.def.h"
    click Config "https://github.com/z101/quark/blob/master/config.mk"
    click Listener "https://github.com/z101/quark/blob/master/quark.c"
    click HTTP "https://github.com/z101/quark/blob/master/quark.c"
    click Static "https://github.com/z101/quark/blob/master/quark.c"
    click CGI "https://github.com/z101/quark/blob/master/quark.c"
    click Logger "https://github.com/z101/quark/blob/master/quark.c"
    click mkfile "https://github.com/z101/quark/tree/master/Makefile"
    click qman "https://github.com/z101/quark/blob/master/quark.1"
    click qinit "https://github.com/z101/quark/blob/master/quark.daemon.debian"
    click p1 "https://github.com/z101/quark/blob/master/patch.01.fixstatus"
    click p2 "https://github.com/z101/quark/blob/master/patch.02.sanelog"

    %% Styles
    classDef network fill:#D0E6FF,stroke:#0066CC,color:#003366;
    classDef server fill:#DFFFD0,stroke:#33AA00,color:#336600;
    classDef storage fill:#FFF7C0,stroke:#CCA300,color:#665500;
    classDef artifact fill:#F0F0F0,stroke:#888888,color:#333333;
```
