ugly-app 0.1.0

package/README.md

@@ -0,0 +1,709 @@
+# website-core
+
+A full-stack TypeScript framework for building production-ready web applications. Provides an opinionated architecture combining an Express backend, React frontend, and MongoDB database with built-in authentication, real-time communication, storage, AI integration, and audio streaming.
+
+## What's Included
+
+- **Server**: Express with type-safe RPC routing and Zod schema validation
+- **WebSockets**: Bidirectional socket server/client with RPC calls, document tracking, and file uploads
+- **Database**: MongoDB with typed collections, cascade delete, indexes, migrations, and NATS-based real-time document tracking
+- **Auth**: JWT + HttpOnly cookie sessions, OAuth (ugly.bot by default, extensible via `AuthProvider` interface)
+- **Storage**: AWS S3 / Cloudflare R2 with presigned URLs and file promotion
+- **AI**: 7 text generation providers (Together, Claude, OpenAI, Google, Groq, Fireworks, Kie) + 5 image providers (Together, FAL, Google, Kie, Wavespeed)
+- **Audio**: Text-to-speech and speech-to-text streaming with React hooks (`useTTS`, `useSTT`), optional viseme data for lip sync, and word-level timestamps
+- **Logging**: Multi-channel logging to MongoDB (error, console, perf, feedback) with server error capture, deduplication, and classification
+- **Queues**: NATS JetStream worker queues, Redis pub/sub with in-memory fallback
+- **Billing**: AI spend tracking with global/provider/per-user rolling limits (hourly/daily/weekly), threshold callbacks, profit margin markup, pre-paid user credits, full audit history, and 5-minute DB reconciliation
+- **Email**: Transactional email via Mailgun with Handlebars template support
+- **Rate Limiting**: Per-user/per-operation token-bucket limiting with queue management
+- **Push Notifications**: Real-time delivery via WebSocket + Redis, with FCM support
+- **Feedback**: Built-in user feedback collection with screenshot capture
+- **CLI**: `web` command for dev, build, deploy, migrations, log queries, and auth utilities
+
+## Installation
+
+```bash
+npm install website-core
+```
+
+Peer dependencies:
+
+```bash
+npm install react react-dom html2canvas
+```
+
+## Quick Start
+
+### Scaffold a new project
+
+```bash
+npx web init my-app
+```
+
+### Start development
+
+```bash
+yarn dev
+# Starts Docker services, Express server, Vite, TypeScript watcher, and ESLint concurrently
+```
+
+## Usage
+
+### Server
+
+```typescript
+import { createApp, createUserHelper, registerFeedbackHandlers } from 'website-core';
+import { dbDefaults } from 'website-core/shared';
+import { functions, requests } from '../shared/api.js';
+import { collections } from '../shared/collections.js';
+import { pages } from '../shared/pages.js';
+import type { User } from '../shared/types.js';
+
+export const userHelper = createUserHelper(collections.user);
+
+const app = createApp({ functions, requests }, collections, (config) => {
+  config.setPages({ pages });
+
+  config.setUserHelper(userHelper);           // required
+
+  config.setOnUserCreate(async (userId, info, db) => {   // required
+    await userHelper.set(db, {
+      ...dbDefaults(),
+      id: userId,
+      email: info.email,
+      phone: info.phone,
+    });
+  });
+
+  // Optional
+  // config.setAuth(myAuthProvider);
+  // config.setContextExtensions(async (base) => ({ nats: await connectNats() }));
+});
+
+app.registerRequest('getMe', async (ctx) => {
+  const user = await userHelper.get(ctx.db, ctx.userId);
+  return { userId: ctx.userId, email: user?.email };
+});
+
+registerFeedbackHandlers(app, process.env.MAINTAIN_BOT_USER_ID ?? '');
+
+const port = parseInt(process.env['PORT'] ?? '3000');
+await app.start(port);
+```
+
+> Both `setUserHelper` and `setOnUserCreate` are **required** — `createApp` throws at startup if either is missing.
+
+### Shared types and API definitions
+
+```typescript
+import { fn, req, defineFunctions, defineRequests } from 'website-core/shared';
+import { z } from 'website-core/shared';
+
+export const functions = defineFunctions({
+  greet: fn(
+    z.object({ name: z.string() }),
+    z.object({ message: z.string() })
+  ),
+});
+```
+
+### React client
+
+```typescript
+import { AppProvider, useApp, createRouter, createSocket } from 'website-core/client';
+```
+
+## Key APIs
+
+### Server — `createApp()`
+
+```typescript
+createApp(registry, appDefs, configure?)
+```
+
+- `registry` — `{ functions, requests }` from your shared API definitions
+- `appDefs` — collection defs from `defineCollections()`
+- `configure` — optional callback receiving an `AppConfigurator`:
+
+```typescript
+interface AppConfigurator {
+  setUserHelper(helper: UserHelper<any>): void;       // required
+  setOnUserCreate(handler: OnUserCreate): void;        // required
+  setAuth(provider: AuthProvider): void;
+  setPages(options: PageServerOptions): void;
+  setOnSocketMessage(handler: (ws, userId, msg) => boolean): void;
+  setContextExtensions<E>(fn: (base: HandlerContext) => Promise<E>): void;
+  setWorkerQueue(queue: WorkerQueue): void;
+  registerRoutes(fn: (router: express.Router) => void): void;
+}
+```
+
+Registers handlers with full context (`userId`, `db`, `storage`, `textGen`, `imageGen`, `log`, `rateLimit`):
+
+```typescript
+app.registerFunction('greet', async (ctx, input) => {
+  ctx.log.info('Greeting user', { userId: ctx.userId });
+  return { message: `Hello, ${input.name}` };
+});
+
+app.registerRequest('stream', async (ctx, input) => {
+  // streaming HTTP handler — ctx.res available for request handlers
+});
+```
+
+Built-in routes: `GET /health`, `POST /auth/verify`, `GET /auth/token`, `POST /auth/logout`, `GET /auth/url`, `POST /logs/client`, `GET /my_feedback`
+
+### Auth — Cookie Sessions
+
+After login, the server sets an `auth_token` HttpOnly cookie. On every page load the server refreshes it and injects the token into the HTML:
+
+```html
+<script>window.__AUTH_TOKEN__ = "eyJ..."</script>
+```
+
+The client reads `window.__AUTH_TOKEN__` synchronously — no localStorage, no extra HTTP round-trip. To log out:
+
+```typescript
+await fetch('/auth/logout', { method: 'POST' });
+window.location.reload();
+```
+
+### Database — `TypedDB`
+
+Define collections in `shared/collections.ts`. The `defineCollections` call injects the collection name into each def, making the def itself the collection reference:
+
+```typescript
+import { defineCollections } from 'website-core/shared';
+
+export const collections = defineCollections({
+  notes: {
+    type: {} as Note,
+    meta: { cache: true, trackable: true, public: false, parent: null },
+    onDelete: async (doc, db) => { /* cleanup child docs */ },
+  },
+  comments: {
+    type: {} as Comment,
+    meta: { cache: false, trackable: true, public: false, parent: 'notes' },
+  },
+});
+```
+
+Inside handlers, use `ctx.db` — a `TypedDB` instance pre-created by `createApp`. All methods take the collection def as the first argument (not a string name):
+
+```typescript
+// Insert / replace
+await ctx.db.setDoc(collections.notes, doc);
+await ctx.db.setDoc(collections.notes, doc, { skipIfExists: true }); // INSERT only
+
+// Partial updates (dot-notation, sets `updated` automatically)
+await ctx.db.setDocFields(collections.notes, id, { title: 'New title' });
+const doc = await ctx.db.setDocFieldsOrIgnore(collections.notes, id, { title });  // null if missing
+const doc = await ctx.db.setDocFieldsOrCreate(collections.notes, id, fields, fullObj);
+
+// MongoDB update operators ($inc, $addToSet, $pull, $unset, $set)
+await ctx.db.setDocOp(collections.notes, id, { $inc: { viewCount: 1 } });
+const doc = await ctx.db.setDocOpOrIgnore(collections.notes, id, { $addToSet: { tags: 'foo' } });
+
+// Reads
+const note = await ctx.db.getDoc(collections.notes, id);
+const notes = await ctx.db.getDocs(collections.notes, { userId }, { sort: { created: -1 }, limit: 20, skip: 0 });
+
+// Aggregate pipeline queries
+const results = await ctx.db.getQuery<MyResult>('notes', pipeline, { skip, limit });
+const count   = await ctx.db.getQueryCount('notes', pipeline);
+const raw     = await ctx.db.getQueryRaw<RawDoc>('notes', pipeline);  // no id remapping
+
+// Delete with cascade
+await ctx.db.deleteDoc(collections.notes, id);
+await ctx.db.deleteQuery(collections.notes, { userId });
+
+// Nested / child collections (parentId compound _id: "parentId:leafId")
+await ctx.db.setDoc(collections.comments, comment, { parentId: noteId });
+await ctx.db.getDocs(collections.comments, {}, { parentId: noteId });
+await ctx.db.deleteDoc(collections.comments, commentId, { parentId: noteId });
+
+// Direct cache access
+const key = ctx.db.cacheKey('notes', id);
+ctx.db.cacheSet(key, value, 60_000);
+const cached = ctx.db.cacheGet<Note>(key);
+ctx.db.cacheDelete(key);
+```
+
+Per-collection `cache: true` enables automatic LRU caching on `getDoc` / `setDoc` / `deleteDoc`. Use `parent: 'collectionName'` to define parent–child relationships for compound `_id`s and cascade deletes.
+
+### WebSocket Client
+
+```typescript
+const socket = createSocket({ functions, requests });
+
+await socket.connect(token);                                  // must call first
+await socket.call('greet', { name: 'world' });               // function RPC
+await socket.request('getMe', {});                            // request RPC
+const doc = await socket.getDoc('notes', id);                 // fetch document
+socket.trackDoc('notes', id, (doc) => { /* live */ });        // live updates
+await socket.uploadFile(file, key);                           // file upload (key is a string)
+```
+
+`trackDocs` accepts optional `sort`, `limit`, and `skip` parameters for server-side ordering and pagination:
+
+```typescript
+// Live-updating query: most recent 20 notes, newest first
+socket.trackDocs('notes', { userId }, (docs) => { /* live */ }, {
+  sort: { created: -1 },
+  limit: 20,
+  skip: 0,
+});
+```
+
+`getDocs` on the server also accepts the same options:
+
+```typescript
+const docs = await ctx.db.getDocs(collections.notes, { userId }, {
+  sort: { created: -1 },
+  limit: 20,
+  skip: 0,
+});
+```
+
+### AI — Text Generation
+
+```typescript
+const text = await ctx.textGen.generate(messages, { model });
+const json = await ctx.textGen.generateJson(schema, messages, { model });
+const result = await ctx.textGen.generateWithTools(messages, tools, { model });
+```
+
+Supported providers: `together`, `claude`, `openai`, `google`, `groq`, `fireworks`, `kie`
+
+### AI — Image Generation
+
+```typescript
+const url = await ctx.imageGen.generate(prompt, { width: 1024, height: 1024 });
+```
+
+Supported providers: `together`, `fal`, `google`, `kie`, `wavespeed`
+
+### Audio — TTS/STT React Hooks
+
+```typescript
+// Text-to-speech
+const { playing, currentWord, play, stop } = useTTS(socket);
+await play('Hello world');
+
+// With viseme data for lip sync (opt-in — adds latency)
+await play('Hello world', { requestVisemes: true });
+// viseme events arrive via onViseme callback in useTTS options
+
+// Speech-to-text
+const { transcript, isFinal, listening, start, stop } = useSTT(socket, {
+  mode: 'realtime', // 'realtime' | 'batch' | 'auto'
+});
+
+// With word-level timestamps (opt-in — uses Groq verbose_json, slower)
+const { transcript, words } = useSTT(socket, {
+  mode: 'batch',
+  requestWords: true,
+});
+// words: STTWord[] — each has { word, startMs, durationMs }
+```
+
+Viseme and word types are exported from `website-core/shared`:
+
+```typescript
+import type { TTSViseme, TTSVisemeName, STTWord } from 'website-core/shared';
+```
+
+### Email
+
+Send transactional email via Mailgun:
+
+```typescript
+import { sendEmail, loadEmailTemplate, sendTemplateEmail } from 'website-core';
+
+// One-off HTML email
+await sendEmail({
+  to: 'user@example.com',
+  subject: 'Welcome!',
+  html: '<p>Thanks for signing up.</p>',
+  from: 'noreply@my-app.com',  // optional — defaults to MAILGUN_FROM env var
+  replyTo: 'support@my-app.com',
+  headers: { 'X-Campaign-Id': 'welcome' },
+});
+
+// Handlebars template email
+interface WelcomeData { name: string; confirmUrl: string }
+const welcomeTemplate = loadEmailTemplate<WelcomeData>('/path/to/welcome.hbs');
+
+await sendTemplateEmail('user@example.com', 'Confirm your email', welcomeTemplate, {
+  name: 'Alice',
+  confirmUrl: 'https://my-app.com/confirm?token=abc',
+});
+```
+
+Required environment variables: `MAILGUN_API_KEY`, `MAILGUN_DOMAIN`, `MAILGUN_FROM`. If `MAILGUN_API_KEY` is not set, sending is silently skipped (dev-friendly).
+
+### Billing
+
+Track AI spend and enforce rate limits across all cost types (`textGen`, `imageGen`, `stt`, `tts`, `embedding`, `service`):
+
+```typescript
+import {
+  initBillingGateway,
+  getBillingGateway,
+  BillingLimitError,
+  BillingValidationError,
+} from 'website-core';
+
+// Initialize once at startup (before serving traffic)
+const billing = initBillingGateway(db, {
+  global: {
+    hourlyUsd: 50,           // hard cap across all providers/users
+    thresholdPct: 0.8,       // fire callback at 80%
+  },
+  providers: {
+    openai: { hourlyUsd: 20, thresholdPct: 0.9 },
+    anthropic: { hourlyUsd: 30 },
+  },
+  profitMarginPct: 0.5,           // optional: 50% markup applied before limit checks
+  reconcileIntervalMs: 300_000,   // flush to DB every 5 min (default)
+  userLimitCacheSize: 10_000,     // LRU entries (default)
+}, creditDb); // optional CreditDB for pre-paid credits
+
+// Supply per-user limits from your database
+billing.setUserLimitHook(async (userId) => {
+  const plan = await db.getDoc(collections.plans, userId);
+  return plan
+    ? { hourlyUsd: plan.hourlyUsd, dailyUsd: plan.dailyUsd, weeklyUsd: plan.weeklyUsd,
+        thresholds: { daily: 0.9 } }
+    : null; // null = no limits
+});
+
+// Alert callbacks (errors swallowed — never block a charge)
+billing.setGlobalThresholdCallback(({ limitType, spent, limit, thresholdPct, provider }) => {
+  console.warn(`[Billing] ${limitType} at ${Math.round(thresholdPct * 100)}%: $${spent}/$${limit}`);
+});
+billing.setUserThresholdCallback(({ userId, limitType, spent, limit }) => {
+  void notifyUser(userId, `You've used ${Math.round(spent / limit * 100)}% of your ${limitType} budget`);
+});
+```
+
+**Recording a charge:**
+
+```typescript
+// Returns BillingRecord on success; throws on limit violation
+try {
+  const record = await getBillingGateway().charge({
+    userId,               // optional — omit for anonymous charges
+    provider: 'openai',
+    model: 'gpt-4o',
+    type: 'textGen',      // 'textGen' | 'imageGen' | 'stt' | 'tts' | 'embedding' | 'service'
+    costUsd: 0.012,
+    inputTokens: 800,
+    outputTokens: 400,
+  });
+} catch (err) {
+  if (err instanceof BillingLimitError) {
+    // err.limitType: 'global-hourly' | 'provider-hourly' | 'user-hourly' | 'user-daily' | 'user-weekly'
+    // err.spent, err.limit
+  }
+}
+```
+
+**Querying spend and history:**
+
+```typescript
+const billing = getBillingGateway();
+
+// Rolling window totals
+const globalHour = await billing.getWindowSpend(3_600_000);
+const userDay    = await billing.getWindowSpend(86_400_000, { userId });
+const openaiHour = await billing.getWindowSpend(3_600_000, { provider: 'openai' });
+
+// Audit history (default limit 100, max 1000)
+const records = await billing.getHistory({ userId, limit: 50, skip: 0 });
+```
+
+**Cache invalidation** (call after a user's plan changes):
+
+```typescript
+billing.invalidateUserLimit(userId);
+billing.invalidateAllUserLimits();
+```
+
+**Pre-paid credits** (optional — requires `creditDb` passed to `initBillingGateway`):
+
+When a user would otherwise be blocked by a rate limit, the gateway automatically deducts from their credit balance as a fallback. Global and provider limits are never bypassed.
+
+```typescript
+import { CreditStore, MongoCreditDB } from 'website-core';
+
+// Set up the credit DB (uses your TypedDB instance)
+const creditDb = new MongoCreditDB(db.userCredits);
+const billing = initBillingGateway(ledgerDb, config, creditDb);
+
+// Grant credits (e.g. after a purchase)
+await billing.grantCredit(userId, 5.00);  // $5.00
+
+// Check balance
+const balance = await billing.getCreditBalance(userId);
+
+// Invalidate cached balance (e.g. after external grant)
+billing.invalidateCreditCache(userId);
+```
+
+Charges are recorded to an `aiSpend` MongoDB collection and reconciled in-memory every 5 minutes with a forced flush on `shutdown()`. Each text and image generation call from `createTextGen`/`createImageGen` is automatically charged through the gateway when initialized.
+
+### Rate Limiting
+
+```typescript
+const rateLimit = createRateLimiter({
+  windowSeconds: 3600,  // 1 hour (default)
+  maxPerWindow: 1.0,    // max units per window (default)
+  maxQueueDepth: 100,   // max queued requests (default)
+  maxWaitMs: 300_000,   // max wait time in queue (default)
+});
+
+await rateLimit.check(userId, 'generate', 0.1);
+await rateLimit.charge(userId, 'generate', actualCost);
+```
+
+### Worker Queues
+
+```typescript
+const queue = createWorkerQueue({
+  streamName: 'JOBS',     // NATS stream name (default: 'JOBS')
+  clockServerOnly: true,  // only process when IS_CLOCK_SERVER=true (default: true)
+  concurrency: 10,        // max concurrent jobs (default: 10)
+  maxRetries: 3,          // max retry attempts (default: 3)
+});
+
+await queue.enqueue('email', { to: 'user@example.com' });
+await queue.enqueue('email', payload, { delay: 5000 }); // delay in ms
+queue.registerHandler('email', async (job) => { /* job.payload, job.working() */ });
+await queue.start();
+```
+
+### Storage
+
+```typescript
+const storage = createStorageClient();
+
+// Server-side upload
+const url = await storage.put('temp', key, buffer, 'image/png');
+const publicUrl = await storage.moveToPublic(tempKey, destKey);
+const url = storage.url('public', destKey);
+
+// Presigned URL for browser direct upload
+const { uploadUrl, resultUrl } = await storage.presignedPut('temp', key);
+```
+
+### Logging
+
+```typescript
+// In handlers, use ctx.log
+ctx.log.info('User signed in', { userId });
+ctx.log.warn('Unexpected state', { context });
+ctx.log.error('Something failed', { error: err.message });
+
+// Performance timing — returns a stop function
+const stop = ctx.log.perf('db-query');
+// ... do work ...
+stop(); // records duration to MongoDB
+```
+
+### Server Error Capture
+
+`captureServerError` persists unexpected errors to a MongoDB `errorLog` collection with automatic deduplication (repeated errors increment a `count` field instead of inserting duplicates). Expected/recoverable errors can be suppressed from persistence by registering patterns.
+
+```typescript
+import {
+  captureServerError,
+  registerExpectedErrorPattern,
+  classifyError,
+} from 'website-core';
+
+// Register known-recoverable patterns at startup — matched errors log to
+// console only and are never written to MongoDB
+registerExpectedErrorPattern('ECONNRESET')
+registerExpectedErrorPattern('[STT] Session ended before audio was received')
+
+// Capture an error in a catch block
+try {
+  await riskyOperation()
+} catch (err) {
+  captureServerError('[MyService] Failed to process request', err, { userId })
+}
+
+// Classify a message manually ('expected' | 'unexpected')
+const classification = classifyError('[STT] Session ended before audio was received')
+```
+
+### Push Notifications
+
+```typescript
+import { sendPush } from 'website-core';
+
+await sendPush(userId, { title: 'New message', body: 'You have a reply' });
+```
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `web init <name>` | Scaffold a new project |
+| `web dev` | Start all dev services (Docker, server, Vite, TS, ESLint) |
+| `web build` | Production build |
+| `web db:init` | Create/update MongoDB indexes |
+| `web db:migrate` | Run pending database migrations (`--status` to preview) |
+| `web publish:assets` | Deploy static assets to CDN (`--dry-run` to preview) |
+| `web purge:assets` | Remove old build artifacts (keeps last 3 by default) |
+| `web logs:local` | Query local dev logs |
+| `web logs:server` | Query server logs from MongoDB |
+| `web error:local` | Query local error logs |
+| `web error:server` | Query server error logs from MongoDB |
+| `web perf:local` | Query local performance metrics |
+| `web perf:server` | Query server performance metrics from MongoDB |
+| `web feedback` | Query user feedback submissions |
+| `web auth:create-account` | Create an account directly in the database |
+| `web auth:create-token` | Generate a JWT for a userId |
+| `web test:e2e` | Run Playwright end-to-end tests (`--headed` for browser UI) |
+
+## React Components
+
+```typescript
+import {
+  Button, Card, Text, Input, Modal, Toast, PageLayout,
+  FeedbackButton,
+} from 'website-core/client';
+```
+
+The `FeedbackButton` captures a screenshot and submits it with user context automatically.
+
+## Routing (Client)
+
+```typescript
+const { useRouter, RouterProvider, RouterView } = createRouter(pages);
+
+function App() {
+  const { push, replace, back } = useRouter();
+  return (
+    <RouterProvider fallback={<NotFound />} loginFallback={<Login />} isAuthenticated={() => !!userId}>
+      <RouterView renderPage={(state) => <PageSwitch route={state.name} params={state.params} />} />
+    </RouterProvider>
+  );
+}
+```
+
+Page transitions are animated by default using `ViewFlipper`. The transition type (`PUSH`, `POP`, `REPLACE`, `NONE`) is inferred automatically from navigation calls.
+
+### Popups
+
+```typescript
+import { useRouter } from './router';
+
+function MyComponent() {
+  const { openPopup } = useRouter();
+
+  function openMenu() {
+    const handle = openPopup(<MyMenu />, {
+      mode: 'contextMenu',   // 'block' | 'transient' | 'contextMenu'
+      slideFrom: 'bottom',   // 'left' | 'right' | 'top' | 'bottom' | 'none'
+    });
+
+    // Dismiss programmatically
+    handle.hide();
+  }
+}
+```
+
+- **`block`** — modal overlay, blocks interaction behind it
+- **`transient`** — tapping the backdrop closes it
+- **`contextMenu`** — same as transient but typically for menus/pickers
+
+### Animation Primitives
+
+```typescript
+import {
+  createAnimatedValue,
+  useAnimatedValue,
+  Animated,
+  easingFunctions,
+} from 'website-core/client';
+import type { EasingFunction } from 'website-core/client';
+
+// Imperative animated value (RAF-driven, no React re-renders)
+const spring = createAnimatedValue(0);
+spring.animateTo(1, { duration: 300, easing: easingFunctions.easeInOut });
+
+// React hook version
+const opacity = useAnimatedValue(0);
+
+// Apply to DOM via ref — zero re-renders
+<Animated value={spring} style={(v) => ({ opacity: v, transform: `scale(${v})` })}>
+  <div>Content</div>
+</Animated>
+```
+
+## Project Structure
+
+Projects built with `website-core` follow this layout:
+
+```
+my-app/
+├── src/
+│   ├── server/      # Express handlers, DB collections, migrations
+│   ├── client/      # React pages and components
+│   └── shared/      # API definitions and shared types
+├── static/          # Build-time static assets
+└── docker-compose.yml
+```
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `MONGODB_URI` | MongoDB connection string |
+| `JWT_SECRET` | Secret for signing JWT tokens |
+| `REDIS_URL` | Redis connection (optional, uses in-memory fallback) |
+| `NATS_URL` | NATS server URL |
+| `NATS_CREDS` | NATS credentials file path (Synadia Cloud) |
+| `STORAGE_ACCOUNT_ID` | Cloudflare R2 account ID (alias: `CLOUDFLARE_ACCOUNT_ID`) |
+| `STORAGE_ACCESS_KEY_ID` | R2 access key (alias: `CLOUDFLARE_R2_ACCESS_KEY_ID`) |
+| `STORAGE_SECRET_ACCESS_KEY` | R2 secret key (alias: `CLOUDFLARE_R2_SECRET_ACCESS_KEY`) |
+| `STORAGE_PUBLIC_BUCKET` | R2 public bucket name (alias: `CLOUDFLARE_R2_PUBLIC_BUCKET`) |
+| `STORAGE_TEMP_BUCKET` | R2 temp bucket name (alias: `CLOUDFLARE_R2_TEMP_BUCKET`) |
+| `STORAGE_PUBLIC_URL` | Base URL for public bucket (alias: `CLOUDFLARE_R2_PUBLIC_URL`) |
+| `STORAGE_TEMP_URL` | Base URL for temp bucket (alias: `CLOUDFLARE_R2_TEMP_URL`) |
+| `TOGETHER_API_KEY` | Together AI API key |
+| `ANTHROPIC_API_KEY` | Anthropic Claude API key |
+| `OPENAI_API_KEY` | OpenAI API key |
+| `GOOGLE_API_KEY` | Google Gemini API key |
+| `IS_CLOCK_SERVER` | Set to `true` on the instance that processes worker queues |
+| `MAILGUN_API_KEY` | Mailgun API key (`key-...`) |
+| `MAILGUN_DOMAIN` | Mailgun sending domain (e.g., `mg.my-app.com`) |
+| `MAILGUN_FROM` | Default from address (e.g., `noreply@my-app.com`) |
+
+Client-side variables must be prefixed with `VITE_`.
+
+## Tech Stack
+
+- **Runtime**: Node.js, TypeScript (ES2022, NodeNext modules)
+- **Server**: Express, ws (WebSockets)
+- **Frontend**: React 19, Vite, Tailwind CSS
+- **Database**: MongoDB
+- **Messaging**: NATS with JetStream
+- **Cache**: Redis (in-memory fallback for dev)
+- **Storage**: AWS S3 / Cloudflare R2
+- **Auth**: JWT (jose), OAuth
+- **AI**: Together AI, Anthropic, OpenAI, Google, Groq, FAL
+- **Audio**: InWorld TTS, Groq Whisper STT
+- **Validation**: Zod
+- **Testing**: Vitest, Playwright, mongodb-memory-server
+
+## Development
+
+```bash
+npm run build       # Compile TypeScript
+npm test            # Run unit tests
+npm run test:watch  # Watch mode
+```