Backend

Libraries

• lib/db.ts: Prisma client factory (dynamic import to avoid build‑time dependency), exposes prisma.
• lib/auth.ts: helper stubs for project lookup from auth; dev mode shortcuts.
• lib/crypto.ts: AES‑GCM helpers using RUNFORGE_MASTER_KEY (base64 or 64‑hex).
• lib/config.ts: Zod‑validated env parsing (NODE_ENV, INGEST_API_KEY).
• lib/eval/*: exact, regex, rouge‑L (lightweight), judge stub.

Ingestion flow

• /api/ingest validates and transforms payloads, then calls Convex mutations.
• convex/runs.ts enforces idempotency by runId index and schedules sync.
• convex/runsActions.ts posts to /api/internal/pg-sync with HMAC signature.

Idempotency & retries

• Idempotent insert by runId (skips duplicates).
• Background sync retries are implicit on next write; explicit retry queue TODO.
• Rate limiting per project: in‑memory sliding window in the API route.

Security

• Ingest auth via INGEST_API_KEY with timing‑safe equality.
• HMAC signing for internal sync via RUNFORGE_SYNC_SIGN.
• BYOK encryption through encryptAesGcm/decryptAesGcm.

Batching & limits

• api.runs.ingestRuns supports batch inserts; UI list caps at 500 recent.
• KPI rollup runs every minute via Convex cron (kpis.rollup1m).

TODOs

• Durable worker for sync retries and DLQ.
• Prompt storage: hash‑only toggle wiring. See Run.promptHash vs promptPreview.
• Add runs_live retention/TTL cleanup.

See also: 08-convex-realtime.md and 11-configuration-env.md.