Architecture & Tools

Moul is designed around a clean separation of concerns: a single headless daemon engine (moul) that manages data, background jobs, authentication, and real-time streams, paired with two dedicated client interfaces (moul-ctl TUI and the Web Admin Console) to inspect and administer it.

The Three Core Components

graph TD
    subgraph ClientConsoles["Client Consoles (Management Interfaces)"]
        WebAdmin["Web Admin Console\n(Browser at /_moul_/)"]
        MoulTUI["Moul TUI (moul-ctl)\n(Terminal Client)"]
        ExternalApps["Your Applications & SDKs\n(Web, Mobile, Scripts)"]
    end

    subgraph MoulEngine["Moul Engine Daemon (moul)"]
        HTTPServer["Echo HTTP Server (:8090)\nREST API · SSE · MCP Server"]
        EmbeddedUI["Embedded Web Admin Assets"]
        WorkerEngine["Oban-Style Background Workers"]
        SQLiteDB[("Embedded SQLite Database\n(WAL Mode + Litestream Replication)")]
    end

    WebAdmin -->|"HTTP REST / SSE"| HTTPServer
    MoulTUI -->|"HTTP REST / SSE"| HTTPServer
    ExternalApps -->|"REST API / Bearer Tokens"| HTTPServer
    HTTPServer --> SQLiteDB
    HTTPServer --> WorkerEngine
    HTTPServer --> EmbeddedUI

1. moul — The Engine Daemon

moul is the core backend daemon. When you run moul start, it initializes your SQLite database, starts the Echo HTTP/REST API server on port :8090, launches the background worker queue engine, activates real-time Server-Sent Events (SSE), and serves the static assets for the Web Admin Console.

• Primary Role: Server engine & background runtime.
• Key Responsibilities:
  • SQLite database management with dynamic runtime schema alterations.
  • Multi-factor authentication (Password, Email OTP, Passkeys, OAuth2).
  • Background worker pool with exponential retry and dead-letter queues.
  • Real-time Server-Sent Events (SSE) subscriptions.
  • Built-in Model Context Protocol (MCP) server for AI assistants.
  • First-party visitor analytics and optional GeoIP lookup.
• CLI Usage:

  moul start               # Start the engine daemon (default: :8090)
  moul ctl                 # Launch moul-ctl management TUI
  moul seed                # Seed demo collections, records, and feature flags
  moul typegen             # Generate TypeScript types from schemas
  moul test-rule           # Evaluate and benchmark access rule expressions
  moul worker list-failed  # Inspect dead-letter queue (DLQ)
  moul worker retry        # Retry failed background worker jobs
  moul mcp                 # Start native MCP server over stdio
  moul restore             # Point-in-time restore from S3/Litestream backup
  moul update              # Self-update binary to latest release

2. moul-ctl — The Terminal Client (TUI)

moul-ctl is an interactive, keyboard-driven Terminal User Interface built with Charm's Bubble Tea. It connects to a running moul server (locally or over the network via HTTP/HTTPS) and provides full administrative control without needing a web browser.

• Primary Role: Terminal-native client for managing moul.
• Key Responsibilities:
  • Browse dynamic collections and inspect schema definitions.
  • Live record CRUD (search, filter, view formatted JSON, edit, create, delete).
  • Background worker queue monitor (live statuses, DLQ inspection, job retries).
  • Host and runtime health telemetry monitoring.
  • Trigger server-side hot-reloads of configuration.
• CLI Usage:

  # Connect interactively (prompts for URL and Admin Key)
  moul-ctl
  
  # Or launch via moul convenience command:
  moul ctl
  
  # Or connect directly with flags:
  moul-ctl -server http://localhost:8090 -admin-key your-admin-key
  
  # Update TUI client to latest release:
  moul-ctl update

3. Web Admin Console — The Browser Dashboard

The Web Admin Console is a single-page web application embedded directly inside the moul binary and served at http://localhost:8090/_moul_/.

• Primary Role: Browser-based graphical management dashboard.
• Key Responsibilities:
  • Visual drag-and-drop schema designer and field configuration.
  • Full-screen interactive data tables with search, sorting, and pagination.
  • Live charts for request throughput, latency percentiles, and error rates.
  • Real-time SSE live log stream viewer.
  • OpenFeature feature flags playground and rule targeting validator.
  • System settings and SMTP/S3 credentials manager.
• Access: Navigate to http://localhost:8090/_moul_/ in any modern web browser and log in with your root administrative credentials or master MOUL_ADMIN_KEY.

Comparison: When to Use What?

How Consoles Connect to moul

Both the Web Admin Console and moul-ctl TUI communicate with moul through its standard REST API and Server-Sent Events endpoints:

  ┌────────────────────────────────────────────────────────┐
  │                   Management Consoles                  │
  │  [ Web Admin (/_moul_/) ]     [ TUI Client (moul-ctl) ]│
  └───────────────┬────────────────────────┬───────────────┘
                  │                        │
     HTTP REST    │                        │  HTTP REST
     & Live SSE   │                        │  & Live SSE
                  ▼                        ▼
  ┌────────────────────────────────────────────────────────┐
  │                  moul Engine Server                    │
  │                  (Default: :8090)                      │
  │                                                        │
  │  • Authenticates via:                                  │
  │    - Master Key (X-Admin-Key / ?adminKey=...)          │
  │    - Root User JWT Token (_rootUsers)                  │
  │                                                        │
  │  • Endpoints:                                          │
  │    - /api/moul/*       (Collections, Schemas & CRUD)   │
  │    - /api/system/*     (Host Metrics & Collector)      │
  │    - /api/analytics/*  (Visitor Telemetry)             │
  │    - /api/mcp          (Model Context Protocol)        │
  └────────────────────────────────────────────────────────┘

Next Steps

• Quick Start Guide: Install Moul and start your local engine in 2 minutes.
• Configuration & Environment: Complete guide to environment variables and runtime settings.
• Admin Consoles Guide: Detailed walkthrough and keybindings for the Web Admin and TUI.