VayuPress Architecture

Purpose

VayuPress is a single-binary publishing platform written in Go, using SQLite as its primary database. It is designed to run on a single VPS (12 GB RAM / 6 vCPU / 250 GB NVMe) and serve millions of articles with static-file performance.

System Context

graph TD
    Client -->|HTTPS| Nginx
    Nginx -->|Cache hit| StaticFiles[/var/cache/vayupress]
    Nginx -->|Cache miss| VayuPress[VayuPress :8080]
    VayuPress --> SQLite[SQLite WAL]
    VayuPress -->|Optional| Meilisearch[Meilisearch :7700]
    VayuPress -->|Optional| Isso[Isso :8081]
    Admin -->|API Key| VayuPress

Components

Request Flow

sequenceDiagram
    Client->>Nginx: GET /articles/my-post
    Nginx->>Cache: Check /var/cache/vayupress/posts/my-post.html
    alt Cache hit
        Cache-->>Nginx: HTML file
        Nginx-->>Client: 200 OK (static)
    else Cache miss
        Nginx->>VayuPress: proxy_pass :8080
        VayuPress->>SQLite: SELECT article WHERE slug=?
        VayuPress->>Cache: Write rendered HTML
        VayuPress-->>Client: 200 OK (dynamic)
    end

Write Queue

graph LR
    API[POST /api/v1/articles] --> DB[(write_jobs)]
    DB --> Worker1[Worker goroutine 1]
    DB --> Worker2[Worker goroutine 2]
    DB --> Worker3[Worker goroutine N]
    Worker1 --> Articles[(articles table)]
    Worker1 --> Meili[Meilisearch index]
    Worker1 --> CacheInval[Cache invalidation]

Write jobs are persisted in SQLite before any worker processes them. On crash, pending jobs resume from where they left off. Jobs that fail 3 times move to the dead-letter queue.

Media Pipeline

graph LR
    Upload[POST /api/v1/media] --> Validate[MIME + extension check]
    Validate --> Sandbox[libvips seccomp/apparmor]
    Sandbox --> Thumbnails[Thumbnail generation]
    Thumbnails --> Storage[/var/www/vayupress/static/media]
    Thumbnails --> Dedup[SHA-256 deduplication]

Storage Lifecycle

graph TD
    Upload --> Active[Active media]
    Active -->|MEDIA_RETAIN_DAYS| AutoDelete[Auto-delete]
    Active -->|Orphan check daily| OrphanCleanup[Orphan cleanup]
    Active -->|Parent deleted| CascadeDelete[Cascade delete thumbnails]

Security Architecture

graph TD
    Internet --> UFW[UFW firewall: 22/80/443]
    UFW --> Nginx[Nginx TLS]
    Nginx --> VayuPress
    VayuPress --> Auth[API Key / Argon2id]
    Auth --> CSRF[CSRF double-submit cookie]
    CSRF --> RateLimit[Rate limiter]
    RateLimit --> Handlers
    Handlers --> SQLite

Key Design Decisions

See /docs/adr/ for Architecture Decision Records.

Key decisions:

• ADR-0001: SQLite as primary database (WAL mode)
• ADR-0002: Self-hosted fonts (zero telemetry)
• ADR-0032: Plugin pool WaitGroup drain
• ADR-0033: WAL adaptive checkpoint
• ADR-0034: Migration checksum drift detection

Operational Constraints

Dependencies

Vendored frontend assets (self-hosted, no CDN): DOMPurify (static/js/purify.min.js, Apache-2.0/MPL-2.0) sanitizes the Admin v2 editor preview; htmx (static/js/htmx.min.js, 0BSD) drives hx-* progressive enhancement in the VayuOS admin panel; Pico CSS (static/css/pico.min.css, MIT) styles the public site. Every one is compiled into the binary via the module root //go:embed static (StaticFS), mirrored to STATIC_DIR on boot (syncEmbeddedStatic, ADR-0099), and served same-origin so the strict CSP (script-src 'self', style-src 'self') holds with no nonce and no external request. See NOTICE for attribution. VayuPress itself is Apache-2.0 licensed. See ADR-0107 for the HTMX decision.

No frontend framework. Public paths: HTMX + Alpine.js only.