↵ to select ↓ ↑ to navigate esc to close
stigmergic

Architecture

Stigmergic is a single Go binary with no runtime dependencies. Everything is embedded at compile time.

How It Works

graph TD
    A[File System] -->|fsnotify| B[Watcher]
    B -->|Change Events| C[HTTP Server]
    C -->|SSE| D[Browser]
    C -->|Render| E[Markdown Parser]
    E -->|HTML| C
    D -->|HTMX| C

    style A fill:#89b8c2
    style B fill:#84a0c6
    style C fill:#a093c7
    style D fill:#b4be82
    style E fill:#e2a478
  1. Watcher monitors the directory tree using fsnotify with debouncing
  2. On file change, the Server pushes an event via SSE to connected browsers
  3. The browser uses HTMX to fetch the updated content (partial page update, no full reload)
  4. The Markdown Parser renders the file using Goldmark with extensions
  5. HTML is generated by Templ templates and returned to the browser

Request Flow

sequenceDiagram
    participant User
    participant Browser
    participant Server
    participant FS as File System

    User->>Browser: Navigate to /file/readme.md
    Browser->>Server: GET /file/readme.md (HTMX)
    Server->>FS: Read file
    FS-->>Server: Markdown content
    Server->>Server: Parse & render
    Server-->>Browser: HTML fragment
    Browser->>Browser: Swap content (no page reload)

    Note over FS,Server: Later, file changes...
    FS->>Server: fsnotify event
    Server->>Browser: SSE: file changed
    Browser->>Server: GET /file/readme.md (HTMX)
    Server-->>Browser: Updated HTML

Stack

Layer Technology Purpose
CLI Cobra Command parsing
Config Viper Hierarchical config (flags > env > file > defaults)
Watcher fsnotify File system events with debouncing
Server Go net/http HTTP server with middleware stack
Markdown Goldmark CommonMark + GFM + extensions
Highlighting Chroma Syntax highlighting (Nord theme)
Templates Templ Type-safe HTML generation
Frontend HTMX Partial page updates
Styling Tailwind CSS Utility-first CSS (compiled at build time)
Math KaTeX LaTeX rendering (client-side)
Diagrams Mermaid Diagram rendering (client-side)

Design Decisions

No database. All state comes from the filesystem. Discovery happens on-demand by scanning the directory tree. This keeps things simple and means your content is always just files — version-controlled, portable, yours.

HTMX over SPA. Navigation uses HTMX partial page updates instead of a JavaScript SPA framework. This means the server renders HTML, the browser swaps content, and there's no client-side routing or state management. Pages work without JavaScript (degraded but functional).

Embedded assets. Static files (CSS, JS, fonts) are embedded in the binary using Go's embed package. One binary, nothing to configure, nothing to lose.

Security by default. Path traversal protection, security headers, and read-only filesystem access. Stigmergic never writes to your files.

Project Structure

stigmergic.dev/
├── cmd/stigmergic/       # CLI entry point
├── internal/
│   ├── config/           # Viper configuration
│   ├── embed/            # Embedded static assets
│   ├── logger/           # Structured logging
│   ├── markdown/         # Goldmark parser + extensions
│   ├── models/           # Data structures
│   ├── server/           # HTTP server + handlers
│   ├── theme/            # Theme loading
│   ├── watcher/          # File system watcher
│   └── workdir/          # Work directory management
├── web/templates/        # Templ HTML templates
├── example/              # Example content (this site!)
├── flake.nix             # Nix packaging
└── Makefile              # Build commands