# Ruvocal

> Voice/audio-enabled AI chat interface forked from HuggingFace Chat UI with RVF document store replacing MongoDB

- Skill: `jrennie99-glitch/ruvocal` (Agent Skill)
- Install (CLI): `npx skillmds add jrennie99-glitch/ruvocal`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jrennie99-glitch/ruvocal/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jrennie99-glitch (https://skillmd.com/u/jrennie99-glitch)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/jrennie99-glitch/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

```json
{
  "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

```typescript
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

| Operation | Dataset | Time | Throughput |
|-----------|---------|------|------------|
| Insert | 10,000 docs | 63ms | ~159k ops/s |
| Find (range) | 10,000 docs | 5ms | 1,000 results |
| UpdateMany | 10,000 docs | 15ms | 5,000 matched |
| Aggregate | 10,000 docs | 28ms | match+sort+limit |
| Concurrent (5 ops) | 1,000 docs | 1.9ms | mixed read/write |
| Multi-tenant insert | 10x1,000 docs | 25ms | 10 tenants |

## 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

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

### Environment Variables

```bash
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

| Aspect | Upstream (MongoDB) | RuVocal (RVF Store) |
|--------|-------------------|---------------------|
| Dependencies | MongoDB server | Zero -- pure TypeScript |
| Container size | +500MB for MongoDB | 0 extra |
| Persistence | Network database | Single JSON file |
| Startup | Seconds (connection) | Instant |
| Multi-tenant | Not built-in | Native isolation |
| Backup | mongodump | cp ruvocal.rvf.json |
| Test speed | MongoMemoryServer (~2s) | In-memory (~300ms) |

## Key Files

| File | Description |
|------|-------------|
| `src/lib/server/database/rvf.ts` | RVF document store (850+ lines) |
| `src/lib/server/database.ts` | Database module using RvfCollection |
| `svelte.config.js` | SvelteKit configuration |
| `chart/` | Helm chart for Kubernetes |
| `Dockerfile` | Container build |