cloud-orchestrator/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Cloudflare Worker-based AI server recommendation service. Uses Workers AI (Llama 3.1 8B), D1 database, and VPS benchmark data to recommend cost-effective servers based on natural language requirements.

Production URL: https://server-recommend.kappa-d8e.workers.dev

Commands

# Development
npm run dev              # Start local development server (wrangler dev)
npm run deploy           # Deploy to Cloudflare Workers
npm run typecheck        # TypeScript type checking

# Database operations (D1)
npx wrangler d1 execute cloud-instances-db --file=schema.sql        # Apply schema
npx wrangler d1 execute cloud-instances-db --file=seed.sql          # Seed data
npx wrangler d1 execute cloud-instances-db --command="SELECT ..."   # Ad-hoc queries

# View logs
npx wrangler tail

Architecture

src/index.ts (single file Worker)
├── handleHealth()           GET /api/health
├── handleGetServers()       GET /api/servers - List servers with filtering
└── handleRecommend()        POST /api/recommend - AI-powered recommendations
    ├── validateRecommendRequest()
    ├── queryCandidateServers()     → D1: instance_types + providers + pricing + regions
    ├── queryBenchmarkData()         → D1: benchmark_results + benchmark_types
    ├── queryVPSBenchmarks()         → D1: vps_benchmarks (Geekbench 6)
    └── getAIRecommendations()       → Workers AI (Llama 3.1 8B)

Key Data Flow

1. User sends natural language request (tech_stack, expected_users, use_case, region_preference)
2. queryCandidateServers() finds matching servers with flexible region matching (supports country codes, names, city names)
3. queryVPSBenchmarks() retrieves Geekbench 6 scores, prioritizing same provider match
4. AI analyzes and returns 3 tiers: Budget, Balanced, Premium

D1 Database Tables (cloud-instances-db)

• providers - Cloud providers (50+)
• instance_types - Server specifications
• pricing - Regional pricing
• regions - Geographic regions
• vps_benchmarks - Geekbench 6 benchmark data (269 records, manually seeded)
• benchmark_results / benchmark_types / processors - Phoronix benchmark data

Key Implementation Details

Flexible Region Matching (queryCandidateServers)

Region matching supports multiple input formats:

LOWER(r.region_code) = ? OR
LOWER(r.region_code) LIKE ? OR
LOWER(r.region_name) LIKE ? OR
LOWER(r.country_code) = ?

Valid inputs: "korea", "KR", "seoul", "ap-northeast-2"

Provider-Priority Benchmark Matching (queryVPSBenchmarks)

1. First tries exact provider match
2. Falls back to similar spec match from any provider
3. Used to attach real benchmark data to recommendations

AI Prompt Strategy

• System prompt emphasizes cost-efficiency and minimum viable specs
• Tech stack → resource guidelines (e.g., "Nginx: 1 vCPU per 1000 users")
• Scoring: Cost efficiency (40%) + Capacity fit (30%) + Scalability (30%)
• Budget option should score highest if viable

Bindings (wrangler.toml)

[ai]
binding = "AI"

[[d1_databases]]
binding = "DB"
database_name = "cloud-instances-db"
database_id = "bbcb472d-b25e-4e48-b6ea-112f9fffb4a8"

# KV Cache (optional, not configured)
# binding = "CACHE"

Testing

# Health check
curl https://server-recommend.kappa-d8e.workers.dev/api/health

# Recommendation
curl -X POST https://server-recommend.kappa-d8e.workers.dev/api/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "tech_stack": ["php", "mysql"],
    "expected_users": 1000,
    "use_case": "community forum",
    "region_preference": ["korea"]
  }'

Known Limitations

• AI recommendations may be inaccurate for specialized workloads (game servers, Minecraft)
• KV cache is not currently configured (CACHE binding commented out in wrangler.toml)
• src/types.ts contains legacy type definitions (not actively used, actual types inline in index.ts)