# mufeedvh/binserve architecture

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

- Interactive diagram: https://gitdiagram.com/mufeedvh/binserve
- Repository: https://github.com/mufeedvh/binserve

## Overview

##### Project Type and Purpose
- **Type**: CLI-driven, full-feature static web server.
- **Purpose**: Serve static files (and templates) over HTTP/HTTPS with fast in-memory caching, file-system hot-reload, custom routing, and basic security measures.

##### File Structure
- **Top-level files**:
- `Cargo.toml` (Rust dependency manifest)
- `Dockerfile` (containerization)
- `binserve.json` (default config)
- `BENCHMARKS.md`, `README.md`
- **Directories**:
- `.github/` (CI pipeline)
- `assets/` (logo, images)
- `src/cli/` (CLI interface, banners, messages)
- `src/core/`: core engine modules—config loader, server, router, caching, filesystem watcher, TLS, templating
- `src/starter/`: boilerplate HTML, assets, Handlebars templates
- **Key modules**:
- `main.rs` launches CLI → config → core
- `core/server.rs` wires up Actix-Web HTTP/TLS server
- `core/engine.rs` initializes cache, router, watcher
- `core/watcher.rs` watches FS events, triggers cache updates
- `core/templates.rs` integrates Handlebars
- `core/files.rs` reads files and metadata
- `core/routes.rs` maps URIs to resources
- `core/tls.rs` configures Rustls for HTTPS
- `core/config.rs` parses `binserve.json` + CLI args

##### Extract Insights from the README
- **Stack**: Rust, Actix-Web, DashMap, Handlebars-Rust, notify, rustls
- **Features**: Routing, Caching (fast_mem_cache), Hot-Reload, Templating, TLS, Security (directory traversal prevention), Configuration via JSON + CLI flags
- **Runtime flow**: load config → build route index → preload files into in-memory DashMap → start HTTP/TLS listeners → on request, consult cache & router → serve file/template with correct headers → watcher thread listens for changes → update cache atomically

##### Main Components & Interactions
a. **CLI & Config Loader**
- Reads `binserve.json` and CLI flags → produces a `Config` object
b. **Core Engine**
- **Router Module**: builds URI→resource map
- **Cache Module**: DashMap storing preloaded file content + metadata
- **Filesystem Reader**: reads files, MIME types, generates ETags/Last-Modified
- **Template Engine**: Handlebars runtime for `.hbs` files + partials
- **Watcher**: background thread using `notify` to detect FS changes → triggers cache update
- **TLS Module**: configures Rustls server if enabled
c. **HTTP/TLS Server**
- Actix-Web application with routes wired to handler functions
- Handlers consult Router + Cache + Template Engine → build HTTP response
d. **External Services & Tools**
- CI/CD (GitHub Actions)
- Docker containerization (via `Dockerfile`)

##### Architectural Patterns & Principles
- **Modular layering**: clear separation between CLI, core logic, HTTP layer
- **Event-driven concurrency**: Actix event loop + file watcher thread
- **In-memory cache**: DashMap for thread-safe, concurrent reads/writes
- **Configuration via Data**: JSON + CLI flags → no hard-coded behavior
- **Single-binary deployment**: static linking, zero external dependencies

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Config Layer
    subgraph "CLI & Config Loader"
        CLIInterface["CLI Interface"]:::cli
        CLIMessages["CLI Messages & Banner"]:::cli
        CLIMod["CLI Module Entrypoint"]:::cli
        Main["Main Entrypoint & Startup Flow"]:::cli
        ConfigLoader["Configuration Loader\n(JSON + CLI flags)"]:::config
    end

    %% Core Engine Layer
    subgraph "Core Engine Modules"
        Engine["Core Engine Initialization"]:::core
        Router["Router Module\n(URI→Resource Map)"]:::core
        Cache["Cache Module\n(DashMap)"]:::datastore
        FSReader["Filesystem Reader\n(file I/O, MIME, metadata)"]:::fileio
        Templates["Template Engine\n(Handlebars)"]:::core
        Watcher["Filesystem Watcher\n(hot-reload thread)"]:::fileio
        TLSMod["TLS Configuration\n(Rustls)"]:::security
    end

    %% HTTP/TLS Server Layer
    subgraph "HTTP/TLS Server"
        Server["HTTP/TLS Server (Actix-Web)"]:::network
        Handler["Request Handler"]:::network
    end

    %% External Services & Resources
    subgraph "External"
        Client["Client"]:::external
        FS["Filesystem"]:::fileio
        Docker["Docker Container"]:::external
        CI["CI/CD Pipeline"]:::external
    end

    %% Startup Flow
    Main -->|reads configs| ConfigLoader
    ConfigLoader -->|creates Config| Engine

    Engine -->|initializes| Router
    Engine -->|initializes| Cache
    Engine -->|initializes| FSReader
    Engine -->|initializes| Templates
    Engine -->|spawns| Watcher
    Engine -->|configures| TLSMod
    Engine -->|wires up| Server

    %% Request Flow
    Client -->|HTTP/S Request| Server
    Server -->|forwards to| Handler
    Handler -->|lookup| Router
    Handler -->|fetch from| Cache
    Handler -->|fallback read| FSReader
    Handler -->|render| Templates
    Handler -->|responds| Client

    %% Hot-reload Flow
    Watcher -->|detects change| FS
    Watcher -->|updates| Cache

    %% Deployment & CI
    Docker -->|builds binary| Main
    CI -->|tests & builds| Main

    %% Click Events
    click CLIInterface "https://github.com/mufeedvh/binserve/blob/master/src/cli/interface.rs"
    click CLIMessages "https://github.com/mufeedvh/binserve/blob/master/src/cli/messages.rs"
    click CLIMessages "https://github.com/mufeedvh/binserve/tree/master/src/cli/banner/"
    click CLIMod "https://github.com/mufeedvh/binserve/blob/master/src/cli/mod.rs"
    click Main "https://github.com/mufeedvh/binserve/blob/master/src/main.rs"
    click ConfigLoader "https://github.com/mufeedvh/binserve/blob/master/src/core/config.rs"
    click Engine "https://github.com/mufeedvh/binserve/blob/master/src/core/engine.rs"
    click Server "https://github.com/mufeedvh/binserve/blob/master/src/core/server.rs"
    click Router "https://github.com/mufeedvh/binserve/blob/master/src/core/routes.rs"
    click FSReader "https://github.com/mufeedvh/binserve/blob/master/src/core/files.rs"
    click Templates "https://github.com/mufeedvh/binserve/blob/master/src/core/templates.rs"
    click Watcher "https://github.com/mufeedvh/binserve/blob/master/src/core/watcher.rs"
    click TLSMod "https://github.com/mufeedvh/binserve/blob/master/src/core/tls.rs"
    click Docker "https://github.com/mufeedvh/binserve/tree/master/Dockerfile"
    click CI "https://github.com/mufeedvh/binserve/blob/master/.github/workflows/build.yml"

    %% Styles
    classDef cli fill:#D6EAF8,stroke:#3498DB,color:#1B4F72
    classDef config fill:#EBDEF0,stroke:#8E44AD,color:#512E5F
    classDef core fill:#FCF3CF,stroke:#F1C40F,color:#7D6608
    classDef network fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef datastore fill:#D1F2EB,stroke:#48C9B0,color:#0E6251
    classDef fileio fill:#FADBD8,stroke:#EC7063,color:#641E16
    classDef security fill:#E8DAEF,stroke:#9B59B6,color:#4A235A
    classDef external fill:#F2F3F4,stroke:#7B7D7D,color:#1C2833
```
