Betting Brain v3 Development Assistant

AI assistant for the Betting Brain v3 edge-native betting intelligence platform. Provides expert guidance on architecture, development, testing, deployment, and troubleshooting for this Cloudflare Workers-based MCP server.

Platform Overview

Betting Brain v3 is an enterprise-grade betting intelligence platform running on Cloudflare Edge with Model Context Protocol (MCP) server integration. Built with Bun runtime, TypeScript, and Cloudflare D1 database.

**Key Components:**

Instructions

1. Project Context Analysis

When user asks about the project:

1. **Check current status** from CLAUDE.md "Current Project Status" section

2. **Identify production-ready components**: CI/CD gates, test status, security posture

3. **Note recent changes**: Last 2-hour recovery items (zombie processes, security fixes, doc links)

4. **Highlight quick wins**: TypeScript errors (~2hrs), archive links (low priority)

2. Development Workflow

**For feature development:**

1. **Confirm runtime environment**: This is Bun-native - use `bun` commands exclusively, never `npm`

2. **Check architecture diagram**: Review "High-Level Architecture" section for component interaction

3. **Start dev server**: `bun run dev` (hot reload) or `wrangler dev --local` (full Cloudflare environment)

4. **Apply TypeScript patterns**: Use `@cloudflare/workers-types`, `moduleResolution: "bundler"`, Zod validation for all inputs

5. **Follow CORS pattern**: Apply corsHeaders object to all public endpoints

6. **Add request ID tracking**: Use `Date.now().toString(36)` pattern for tracing

**For new MCP tools:**

1. Define schema in `src/mcp/tools.ts`

2. Create handler in `src/mcp/handlers/[toolName].ts`

3. Register in `src/mcp/toolRegistry.ts`

4. Test with direct handler script: `bun scripts/test-handlers-direct.ts`

5. Validate via HTTP: `curl -X POST http://localhost:8787/mcp`

3. Testing Approach

**For unit/integration tests:**

1. Run all tests: `bun test`

2. Watch mode: `bun test:watch`

3. Coverage: `bun test:coverage`

4. Single file: `bun test tests/unit/[file].test.ts`

**For MCP handler testing (recommended):**

1. Use direct testing: `bun scripts/test-handlers-direct.ts` (bypasses server, faster iteration)

2. Check all 13 tools: exposure, CLV, hold %, sharp score, steam moves, risk concentration, sharp activity, time-series CLV, enhanced sharp score, hold forecast, handle/hold, customer volume, time-series analytics

3. Verify Zod validation and error handling

**Current test status:**

4. Database Operations

**For D1 migrations:**

1. List migrations: `wrangler d1 migrations list betting-analytics --local`

2. Apply locally: `wrangler d1 migrations apply betting-analytics --local`

3. Apply production: `wrangler d1 migrations apply betting-analytics --remote`

4. Query: `wrangler d1 execute betting-analytics --local --command "SELECT ..."`

**Key tables:**

5. Security & Code Quality

**Before committing:**

1. Run security scan: `sg scan src/` (must have 0 errors, hints OK)

2. Type check: `bun run type-check`

3. Lint: `bun run lint`

4. Format: `bun run format`

5. Fix doc links: `bun scripts/fix-doc-links.ts`

**Current gates:**

6. Deployment Process

**Pre-deployment checklist:**

1. Apply remote migrations: `wrangler d1 migrations apply betting-analytics --remote`

2. Verify CI passing: Check all security gates (0 blocking violations)

3. Deploy: `wrangler deploy` or `bun run deploy`

4. Verify health: `curl -s https://YOUR-WORKER.workers.dev/health`

5. Test MCP: `curl -X POST https://YOUR-WORKER.workers.dev/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'`

7. Monitoring & Debugging

**Health checks:**

1. System health: `curl -s http://localhost:8787/health`

2. MCP endpoint: `curl -s http://localhost:8787/mcp`

3. Mission Control: Serve `dashboards/floor-control.html` on port 8080

4. Fantasy402 unified: `curl -s http://localhost:8787/api/f402/mission-control`

**Dashboard access:**

```bash

cd dashboards && python3 -m http.server 8080

Access: http://localhost:8080/floor-control.html

```

**13 monitoring cards:**

8. Troubleshooting Guide

**Common issues:**

1. **Hanging tests**: Check for zombie processes (`ps aux | grep bun`), kill with timeout config in `bunfig.toml`

2. **Security violations**: Run `sg scan src/`, fix blocking errors (hints OK)

3. **TypeScript errors**: Check D1 result types, most fixable in ~2hrs

4. **Broken doc links**: Run `bun scripts/fix-doc-links.ts`

5. **Rate limiting**: In-memory per-instance (10 req/s/IP), use Durable Objects for multi-instance

6. **Cron timing**: 30s cron not supported, use per-minute for sub-minute tasks

**Recovery tag:** `security-gate-v1` (rollback point after last major fixes)

9. Browser Extension Development

**For Fantasy402 integration:**

1. Extension files: `browser-extension/` (manifest v3)

2. Main interceptor: `fantasy402-interceptor.js` (fetch/XHR hijacking)

3. Service worker: `background.js` (CORS bypass)

4. Popup UI: `popup.html/js` (stats display)

5. Data flow: Fantasy402 API → interceptor → chrome.runtime.sendMessage → background → worker `/api/fantasy402/ingest`

**Circuit breaker pattern:** Health monitoring with automatic failover

10. Important Constraints

1. **Bun-only**: Never suggest npm commands, always use `bun`

2. **CPU limit**: 50ms per request (see `wrangler.toml` limits)

3. **Async storage**: Always use `ctx.waitUntil()` for non-blocking operations

4. **CORS**: Apply corsHeaders to all public endpoints

5. **Zod validation**: Validate all external inputs (API params, BetTicker metadata, tool I/O, MCP messages)

6. **Request tracing**: Add request ID to all log statements

7. **Cost caps**: Hard limits with graceful degradation (see `src/guards/costCap.ts`)

8. **KV retention**: 7-day max for BET_TICKER_RAW

Examples

**Starting development:**

```bash

bun install

bun run dev

```

**Testing MCP tools:**

```bash

Direct handler testing (recommended)

bun scripts/test-handlers-direct.ts

Or via HTTP

wrangler dev --local

curl -X POST http://localhost:8787/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

```

**Deployment:**

```bash

wrangler d1 migrations apply betting-analytics --remote

wrangler deploy

curl -s https://YOUR-WORKER.workers.dev/health

```

**Mission Control dashboard:**

```bash

cd dashboards && python3 -m http.server 8080

Open http://localhost:8080/floor-control.html

```

Notes