Betting Brain Intelligence Assistant

AI assistant skill for working with Betting Brain v3 - an edge-native betting intelligence platform with MCP server, real-time analytics, and AI-assisted development running on Cloudflare Workers with Bun + TypeScript.

Overview

This skill provides comprehensive context for developing and maintaining a production-ready betting intelligence platform featuring:

Architecture Components

Core Systems

1. **Main Worker** (`src/index.ts`) - Central fetch handler routing to health checks, MCP endpoint, intelligence APIs, BetTicker interception, and diagnostics

2. **MCP Server** (`src/mcp/`) - JSON-RPC 2.0 server with 13 tools for betting intelligence, live betting, and analytics

3. **BetTicker Sniffer** - Transparent API interceptor with KV storage and zero client impact

4. **Intelligence Tools** - Auto-generated typed APIs with Zod validation

5. **Queue Consumers** - Line ingestion and steam webhook processing

6. **Scheduled Jobs** - Hourly sharp calculations and per-minute exposure updates

7. **Browser Extension** - Chrome extension v1.0.9 for Fantasy402 API interception

8. **Mission Control Dashboard** - Unified real-time monitoring with 13 cards

Data Layer

Instructions for AI Assistant

When working on this codebase:

1. **Use Bun commands exclusively** - This is a Bun-native project. Never suggest npm commands. Use `bun run dev`, `bun test`, `bun install`, etc.

2. **Understand the MCP architecture** - The `/mcp` endpoint exposes 13 tools via JSON-RPC 2.0:

- Intelligence Tools: getBettingExposure, getCLV, getHoldPercentage, getSharpScore

- Live Betting Tools: getSteamMoves, getRiskConcentration, getSharpActivity

- Analytics Tools: getTimeSeriesCLV, getEnhancedSharpScore, getHoldForecast, getHandleAndHold, getCustomerVolume, getTimeSeriesAnalytics

3. **Test MCP handlers directly** - Use `bun scripts/test-handlers-direct.ts` for fast iteration instead of starting the full server

4. **Follow security patterns**:

- All external inputs must use Zod validation

- Rate limiting is in-memory per-instance (10 req/s per IP)

- Cost caps enforce hard limits with graceful degradation

- ast-grep security scanning must pass (0 errors allowed)

5. **Database operations**:

- Always check migrations in `migrations/` before schema changes

- Use `wrangler d1 migrations list betting-analytics --local` to review

- Apply with `wrangler d1 migrations apply betting-analytics --local|--remote`

- Query with `wrangler d1 execute betting-analytics --local --command "..."`

6. **Development workflow**:

```bash

bun install # Install dependencies

bun run dev # Start dev server with hot reload

wrangler dev --local # Full Cloudflare Workers environment

bun test # Run all tests

bun scripts/test-handlers-direct.ts # Test MCP handlers

sg scan src/ # Security scan (must show 0 errors)

bun run type-check # TypeScript validation

```

7. **Deployment workflow**:

```bash

wrangler d1 migrations apply betting-analytics --remote # Apply migrations first

wrangler deploy # Deploy worker

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

```

8. **Code quality standards**:

- TypeScript with `moduleResolution: "bundler"`

- All API parameters validated with Zod schemas

- Request ID tracking: `const requestId = Date.now().toString(36)`

- CORS headers on all responses

- Use `ctx.waitUntil()` for async storage operations

- No build step for dev (Bun executes TS directly)

9. **Testing patterns**:

- Test runner is Bun Test (NOT Jest/Vitest)

- Unit tests: `tests/unit/*.test.ts`

- Integration tests: `tests/integration/*.test.ts`

- Direct handler tests: `scripts/test-handlers-direct.ts`

- Test timeouts configured in `bunfig.toml` (10s default)

10. **Browser extension integration**:

- Extension intercepts Fantasy402 API calls

- Routes via background service worker (bypasses CORS)

- Forwards to `/api/fantasy402/ingest` endpoint

- Circuit breaker pattern with health monitoring

- Access popup at chrome://extensions

11. **Mission Control dashboard**:

- Unified endpoint: `/api/f402/mission-control`

- Auto-detects localhost vs production

- Real-time updates every 5 seconds

- Serve with: `cd dashboards && python3 -m http.server 8080`

12. **Current project status** (as of 2025-10-07):

- ✅ All security gates passing (0 blocking violations)

- ✅ 103 broken links fixed

- ⚠️ 154 TypeScript errors remaining (non-blocking)

- ⚠️ 1 test skipped temporarily

- Tagged rollback point: `security-gate-v1`

Common Tasks

**Add a new MCP tool:**

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

2. Create handler in `src/mcp/handlers/`

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

4. Add test in `scripts/test-handlers-direct.ts`

**Fix TypeScript errors:**

**Add database table:**

1. Create migration in `migrations/NNNN_description.sql`

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

3. Test with queries

4. Apply to production before deploying worker

**Debug MCP endpoint:**

```bash

curl -X POST http://localhost:8787/mcp \

-H "Content-Type: application/json" \

-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

```

**Monitor production:**

```bash

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

curl -s https://YOUR-WORKER.workers.dev/system-status

```

Key Files Reference

Important Constraints

Success Criteria

When assisting with this codebase, ensure:

1. All commands use `bun` runtime

2. Security patterns (Zod, rate limiting, cost caps) are followed

3. MCP tools are tested with direct handler script

4. Database migrations are applied in correct order

5. CORS headers are included on responses

6. Request IDs are tracked in logs

7. Code passes `sg scan src/` with 0 errors

8. Tests use Bun Test framework

9. Production deployments verify with health checks

10. Mission Control dashboard shows green status