# elouangrimm/srv-it architecture

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

- Interactive diagram: https://gitdiagram.com/elouangrimm/srv-it
- Repository: https://github.com/elouangrimm/srv-it

## Overview

1. **Project shape**
   - `srv-it` is a small **Node.js CLI package** with one main runtime process.
   - The executable entrypoint is `bin/srv.js`, which hands off to the CLI layer in `src/cli.js`.
   - The core behavior lives in `src/server.js`, with configuration loading/merging in `src/config.js`.

2. **Top-level flow**
   - A user runs the CLI from a terminal.
   - The CLI resolves the target folder, merges config sources, then starts the server.
   - The server serves static files, optionally opens a browser, and enables live reload/watch behavior.

3. **Configuration architecture**
   - Config can come from multiple layers: built-in defaults, global `~/.srvrc.json`, project `srv.config.json`, an explicit `--config` file, and CLI flags.
   - CLI flags always win over file-based config.
   - The repo includes `srv.config.example.json` as a template for per-project defaults.

4. **Static file serving boundary**
   - The server is centered on a single document root: the current directory or a path passed on the command line.
   - It serves files directly from disk and treats the folder itself as the content source.
   - This is not an app framework; it is a file server with a few behaviors layered on top.

5. **Route handling and fallbacks**
   - If a requested path maps to a real file, that file is served.
   - If a folder contains `index.html`, that file is preferred.
   - With `--single`, unknown routes fall back to `index.html`, which supports SPA-style client routing.
   - If there is no index file and directory listing is enabled, a generated listing page is returned instead.

6. **Live reload subsystem**
   - The server injects a small browser client into served HTML pages for live reload.
   - File watching drives updates back to the browser over a websocket-style channel.
   - CSS changes are treated specially: they refresh styles without a full page reload unless `--no-css-inject` is set.

7. **Watcher behavior and resilience**
   - Watch mode can include extra paths via repeated `--watch` flags.
   - Ignore rules can be added via `--ignore`, and some paths are always excluded, notably `.git` and `node_modules`.
   - The implementation is defensive: if the OS watcher limit is reached (`ENOSPC`), the server keeps serving files but disables live reload instead of crashing.

8. **Directory listing and presentation**
   - When a directory has no `index.html`, `srv-it` can render a styled directory listing page.
   - The listing style is configurable with presets like `midnight` and `paper`.
   - Custom styling can also be supplied through `--style-css`.

9. **Network and transport options**
   - The server binds to a configurable host and port, defaulting to `0.0.0.0:3000`.
   - HTTPS is optional and driven by `--ssl-cert`, `--ssl-key`, and `--ssl-pass`.
   - CORS can be enabled with `--cors`, making the server usable from other origins during development.

10. **Operational UX**
    - The CLI includes browser auto-open behavior, request logging control, and startup verbosity controls.
    - `--open` can open `/` or a specific path in the browser.
    - `--no-request-logging` and `--log-level` adjust how chatty the tool is in the terminal.

11. **Repository boundaries**
    - There is no separate frontend app, database, or background worker.
    - The architecture is intentionally narrow: CLI parsing, config resolution, file serving, watching, and browser reload messaging.
    - That makes the main diagram a single Node process with disk I/O, terminal I/O, and browser-facing HTTP/WebSocket traffic.

12. **Packaging and delivery**
    - The package is meant for npm installation and global CLI use.
    - `.github/workflows/npm-publish-github-packages.yml` indicates automated publishing/distribution from GitHub Actions.

Main entry points: [`src/server.js`](https://github.com/elouangrimm/srv-it/blob/main/src/server.js) (Server), [`src/config.js`](https://github.com/elouangrimm/srv-it/blob/main/src/config.js) (Config), [`src/cli.js`](https://github.com/elouangrimm/srv-it/blob/main/src/cli.js) (CLI), [`bin/srv.js`](https://github.com/elouangrimm/srv-it/blob/main/bin/srv.js) (srv.js)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["CLI Runtime"]
  node_bin_srv["srv.js<br/>entrypoint<br/>[srv.js]"]
  node_cli["CLI<br/>command parser<br/>[cli.js]"]
end

subgraph group_config["Config Layer"]
  node_config["Config<br/>merger<br/>[config.js]"]
  node_defaults["Defaults<br/>built-in config"]
  node_global_rc["Global rc<br/>user config"]
  node_project_cfg["Project cfg<br/>project config"]
  node_flags["CLI flags<br/>runtime options"]
end

subgraph group_serve["File Server"]
  node_server[("Server<br/>[server.js]")]
  node_router["Routing<br/>path resolver"]
  node_listing["Directory list<br/>rendered listing"]
  node_styles["Themes<br/>presentation styles"]
  node_reload["Reload client<br/>browser inject"]
  node_watcher["Watcher<br/>file monitor"]
  node_transport(("HTTP/WS<br/>network transport"))
end

subgraph group_delivery["Delivery"]
  node_publish["Publish workflow<br/>ci release"]
end

node_bin_srv -->|"invoke"| node_cli
node_cli -->|"load/merge"| node_config
node_defaults -->|"base"| node_config
node_global_rc -->|"merge"| node_config
node_project_cfg -->|"merge"| node_config
node_flags -->|"override"| node_config
node_cli -->|"start"| node_server
node_server -->|"serve files"| node_router
node_router -->|"fallback"| node_listing
node_listing -->|"theme"| node_styles
node_server -->|"inject"| node_reload
node_server -->|"watch"| node_watcher
node_watcher -->|"notify"| node_reload
node_server -->|"http/https"| node_transport
node_reload -->|"ws channel"| node_transport
node_publish -.->|"ship CLI"| node_bin_srv

click node_bin_srv "https://github.com/elouangrimm/srv-it/blob/main/bin/srv.js"
click node_cli "https://github.com/elouangrimm/srv-it/blob/main/src/cli.js"
click node_config "https://github.com/elouangrimm/srv-it/blob/main/src/config.js"
click node_project_cfg "https://github.com/elouangrimm/srv-it/blob/main/srv.config.example.json"
click node_server "https://github.com/elouangrimm/srv-it/blob/main/src/server.js"
click node_publish "https://github.com/elouangrimm/srv-it/blob/main/.github/workflows/npm-publish-github-packages.yml"

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_bin_srv,node_cli toneBlue
class node_config,node_defaults,node_global_rc,node_project_cfg,node_flags toneAmber
class node_server,node_router,node_listing,node_styles,node_reload,node_watcher,node_transport toneMint
class node_publish toneRose
```

## Components

### CLI Runtime

The npm-installed command and its request/config/server execution path.

- [srv.js](https://github.com/elouangrimm/srv-it/blob/main/bin/srv.js): entrypoint · Executable launcher for the CLI. · `bin/srv.js`
- [CLI](https://github.com/elouangrimm/srv-it/blob/main/src/cli.js): command parser · Resolves args, target folder, and startup options. · `src/cli.js`

### Config Layer

Sources and merging logic for runtime options.

- [Config](https://github.com/elouangrimm/srv-it/blob/main/src/config.js): merger · Combines defaults, files, and flags into final settings. · `src/config.js`
- **Defaults**: built-in config · Base option values used when no external config is provided.
- **Global rc**: user config · Optional per-user settings from ~/.srvrc.json.
- [Project cfg](https://github.com/elouangrimm/srv-it/blob/main/srv.config.example.json): project config · Per-repository settings from srv.config.json. · `srv.config.example.json`
- **CLI flags**: runtime options · Command-line overrides such as watch, open, cors, ssl, and logging.

### File Server

Static file serving, directory handling, and live reload behavior.

- [Server](https://github.com/elouangrimm/srv-it/blob/main/src/server.js): http static server · Main process that serves files and coordinates reload/watch behavior. · `src/server.js`
- **Routing**: path resolver · Maps requests to files, index.html, SPA fallback, or listings.
- **Directory list**: rendered listing · Generates styled listings when a directory has no index file.
- **Themes**: presentation styles · Listing styling presets and custom CSS injection.
- **Reload client**: browser inject · Injected browser-side code that listens for file change events.
- **Watcher**: file monitor · Observes the document root and extra paths for changes.
- **HTTP/WS**: network transport · Serves content over HTTP/HTTPS and pushes reload events over a websocket-style channel.

### Delivery

Packaging and automated publishing.

- [Publish workflow](https://github.com/elouangrimm/srv-it/blob/main/.github/workflows/npm-publish-github-packages.yml): ci release · Automated npm/package publishing via GitHub Actions. · `.github/workflows/npm-publish-github-packages.yml`

## Connections

- srv.js → CLI: invoke · The executable hands off to the CLI layer.
- CLI → Config: load/merge · CLI resolves config sources and final options.
- Defaults → Config: base · Built-in defaults seed the configuration.
- Global rc → Config: merge · User-level config is layered in.
- Project cfg → Config: merge · Project config contributes repository defaults.
- CLI flags → Config: override · CLI flags take precedence over file-based config.
- CLI → Server: start · CLI launches the server with the resolved options.
- Server → Routing: serve files · Server delegates request path resolution to file routing logic.
- Routing → Directory list: fallback · Directories without index.html can render a listing.
- Directory list → Themes: theme · Listings use presets or custom CSS.
- Server → Reload client: inject · HTML responses can include the browser reload client.
- Server → Watcher: watch · Filesystem changes drive live reload behavior.
- Watcher → Reload client: notify · Change events are forwarded to connected browsers.
- Server → HTTP/WS: http/https · Content is served over the configured network transport.
- Reload client → HTTP/WS: ws channel · Browser client communicates over a websocket-style channel.
- Publish workflow → srv.js: ship CLI · Release workflow publishes the installable command package.
