[integrations] open-brain-rest — Cloudflare Worker REST gateway for the Next.js dashboard

[tswicegood]

Contribution Type

• Integration (/integrations)

Note

Companion PR: #248 — adds Cloudflare Workers deploy support to open-brain-dashboard-next. Together these two PRs deliver the all-Cloudflare deploy story: this Worker as the REST gateway, the dashboard as another Worker, sharing the same MCP_ACCESS_KEY. Either ships independently — this Worker can back a Vercel-hosted dashboard, and #248 works with any open-brain-rest-shaped backend.

What does this do?

Adds integrations/cloudflare-rest-worker/ — a Cloudflare Worker that implements the open-brain-rest REST API the Next.js dashboard expects.

The dashboard's README references open-brain-rest as a prerequisite, but no implementation ships in the repo. This PR fills that gap so the four core dashboard pages (Dashboard, Browse, Detail, Search) work end-to-end against any Open Brain Supabase project.

Endpoint surface

The Worker reverse-engineers its contract from the dashboard's lib/api.ts and app/api/*/route.ts consumer code — no contract was invented:

Method	Path	Backed by
GET	/health	unauthenticated; used by login validation
GET	/thoughts	paginated list with whitelisted sort + filters
GET	/thought/:id	single-row read
PUT	/thought/:id	partial update of {content, type, importance, status}
DELETE	/thought/:id	hard delete
POST	/search (semantic)	embedding via OpenRouter → existing match_thoughts RPC → re-fetch with sensitivity_tier filter
POST	/search (text)	existing search_thoughts_text RPC from enhanced-thoughts
GET	/stats	reshapes existing brain_stats_aggregate RPC into the dashboard's StatsResponse shape
POST	/capture	metadata extraction + embedding in parallel → existing upsert_thought RPC
GET	/ingestion-jobs	empty stub (smart-ingest is out of scope; see Known Limitations)
POST	/ingest, /ingestion-jobs/:id/execute	501 Not Implemented
GET	/ingestion-jobs/:id	404

Total: 10 functional endpoints + 4 deliberate stubs.

Architecture

Browser
   │
   │ HTTPS, iron-session cookie
   ▼
Cloudflare Pages: open-brain-dashboard-next
   │
   │ HTTPS, server-side, x-brain-key from session cookie
   ▼
Cloudflare Worker: open-brain-rest          ← this PR
   │
   │ HTTPS, service-role JWT
   ▼
Supabase (thoughts table + RPCs)

Auth uses the same MCP_ACCESS_KEY already set for open-brain-mcp — no new shared secret. The browser never sees the key (encrypted in iron-session cookie, decrypted server-side in the dashboard's API routes).

Requirements

Existing:

• Working Open Brain setup (thoughts table + match_thoughts/upsert_thought RPCs from getting-started)
• schemas/enhanced-thoughts/ applied (provides search_thoughts_text, brain_stats_aggregate, and the type/sensitivity_tier/importance/quality_score/source_type columns)

New:

• Cloudflare account (free tier)
• wrangler CLI
• Node.js 20+

Known limitations (documented in the integration README)

These are real impedance mismatches between the dashboard's expectations and the upstream schema. The Worker is correct as-built; resolving them is out of scope for this PR:

1. Thought.id: number vs thoughts.id UUID. The dashboard does parseInt(id, 10) on URL params (app/thoughts/[id]/page.tsx:29). UUIDs parse to NaN. The Worker returns UUIDs as strings — Browse and stats render fine; Detail navigation needs the dashboard's id type widened. A follow-up PR can patch the dashboard types.

2. importance scale. Dashboard's PRIORITY_LEVELS expects 0–100 (Critical = 80+). enhanced-thoughts schema defaults importance to 3. Existing data renders as "Low" priority. Not a Worker bug.

3. No reflections table. Detail page calls /thought/:id/reflection. No schema creates this table; the Worker doesn't implement the endpoint.

4. No smart-ingest integration. /ingest, /ingestion-jobs/:id, /ingestion-jobs/:id/execute return 501. Single-thought capture via /capture works.

These don't block the four core pages.

Out of scope (future PRs)

• Workflow kanban endpoints — needs workflow-status schema active
• Audit + Duplicates bulk operations
• Reflections (needs schema first)
• Smart ingest extract / execute

Checklist

• I've read CONTRIBUTING.md
• My contribution has a README.md with prerequisites, step-by-step instructions, and expected outcome
• My metadata.json has all required fields
• N/A — no new skill/primitive dependencies
• I tested this on my own Open Brain instance
• No credentials, API keys, or secrets are included (wrangler.toml is gitignored; only wrangler.toml.example ships)

Test plan

• wrangler deploy succeeds against a fresh Cloudflare account
• curl ${WORKER_URL}/health → {"status":"ok",…} without auth
• curl ${WORKER_URL}/thoughts without x-brain-key → 401
• curl ${WORKER_URL}/thoughts -H 'x-brain-key: …' → paginated rows
• POST /search semantic mode returns ranked results with similarity scores
• POST /search text mode returns rows with rank scores
• GET /stats?days=7 returns {total_thoughts, window_days, types, top_topics}
• POST /capture creates a row + writes the embedding (verify via SQL Editor)
• Dashboard npm run dev with NEXT_PUBLIC_API_URL pointing at the Worker — login + Browse + Search render real data

🤖 Generated with Claude Code

[tswicegood]

Claude got a little ambitious here and opened this draft PR before I've finished it. Was planning on opening it at some point, but will come back to this once I've verified everything. I'm testing it against the dashboard and decided to deploy to Cloudflare since I'm running #238 in production already.