Ruvocal

RuVocal — Conversational AI Interface with RVF Document Store

SvelteKit 2 application forked from HuggingFace Chat UI, replacing MongoDB with a pure TypeScript in-memory document store (RVF format) persisted to a single JSON file. Name origin: RuVector + Vocal (voice/conversation).

Purpose

Provides a self-contained conversational AI interface with zero external database dependencies. The RVF document store implements the full MongoDB Collection API, enabling a drop-in replacement across all 56 importing files in the upstream HF Chat UI codebase.

Source Location

/tmp/ruflo/ruflo/src/ruvocal/

Architecture

RuVocal Stack
  +-- RuVocal UI (SvelteKit 2)     +-- MCP Bridge (Node.js)
  |   - Chat UI                     |   - Tool proxy
  |   - Autopilot mode              |   - Autopilot SSE
  |   - Task cards                  |   - System prompt injection
  |   - Auth (OIDC)                 |   - 201+ tools
  |                                 |
  +-- RVF Document Store (In-Memory + Disk Persist)
      File: db/ruvocal.rvf.json
      Collections (16): conversations, users, sessions, settings,
        assistants, reports, messageEvents, semaphores, tokens,
        config, migrationResults, tools, _files, + per-tenant

RVF Document Store

Storage Format

{
  "rvf_version": "2.0",
  "format": "rvf-database",
  "collections": { "conversations": {...}, "users": {...} },
  "tenants": { "tenant-a": {...}, "tenant-b": {...} },
  "metadata": { "created_at": "...", "doc_count": 1234, "multi_tenant": true }
}

MongoDB-Compatible Collection API (RvfCollection<T>)

CRUD Operations:

• findOne, find, insertOne, insertMany
• updateOne, updateMany, deleteOne, deleteMany
• countDocuments, distinct, bulkWrite
• findOneAndUpdate, findOneAndDelete

Aggregation Pipeline: $match, $sort, $limit, $skip, $project, $group (with $sum, $count)

Cursor API: sort, limit, skip, project, batchSize, map, toArray, hasNext, next, tryNext, [Symbol.asyncIterator]

Query Operators: $or, $and, $not, $exists, $gt, $gte, $lt, $lte, $ne, $in, $nin, $regex

Update Operators: $set, $unset, $inc, $push (with $each), $pull, $addToSet, $setOnInsert

Multi-Tenant Support

const conversations = new RvfCollection<Conversation>("conversations");
const tenantConvs = conversations.forTenant("tenant-abc");
await tenantConvs.insertOne({ title: "Hello" });
// Global collection won't find tenant data -- full isolation

Performance Benchmarks

Deployment

Helm Chart

Kubernetes deployment via Helm chart at chart/:

• 3 replicas by default
• 2 CPU / 4Gi memory requests and limits
• Ingress with TLS support
• HPA (Horizontal Pod Autoscaler) support
• Network policies
• Infisical secrets integration
• Service monitor for Prometheus

Docker

docker build -t ruvocal -f Dockerfile .
docker run -p 5173:5173 -e RVF_DB_PATH=/data/ruvocal ruvocal

Environment Variables

RVF_DB_PATH=/data/ruvocal          # RVF store path (empty = in-memory only)
PUBLIC_APP_NAME=RuVocal             # Branding
PUBLIC_ORIGIN=https://chat.example.com
OPENAI_BASE_URL=https://openrouter.ai/api/v1
MONGODB_URL=mongodb://localhost:27017/  # Legacy compat (CI)

Test Infrastructure

SvelteKit + Vitest with three workspaces:

• client -- Svelte component tests (Playwright browser, opt-in)
• ssr -- Server-side rendering tests (Node.js)
• server -- Node.js utility tests (30s timeout)

47 tests across 9 suites covering CRUD, query operators, update operators, cursor, aggregation, GridFS, multi-tenant, persistence, and ObjectId.

Key Differences from Upstream HF Chat UI

Key Files