cloud-orchestrator/REFACTOR_SUMMARY.md

Modularization Summary

New File Structure

src/
├── index.ts                  # Main worker entry point (clean, ~90 lines)
├── types.ts                  # All TypeScript interfaces (complete)
├── config.ts                 # USE_CASE_CONFIGS and i18n messages (complete)
├── utils.ts                  # Utility functions (~650 lines, complete)
├── handlers/
│   ├── health.ts            # GET /api/health (complete)
│   ├── servers.ts           # GET /api/servers (complete)
│   └── recommend.ts         # POST /api/recommend (~1100 lines)

Functions by Module

index.ts (NEW)

• Main fetch handler
• Route handling
• CORS setup
• Rate limit checking

types.ts (COMPLETE)

All interfaces extracted from original index.ts

config.ts (COMPLETE)

• USE_CASE_CONFIGS
• i18n messages

utils.ts (COMPLETE)

• jsonResponse()
• hashString()
• sanitizeCacheValue()
• generateCacheKey()
• escapeLikePattern()
• Type guards: isValidServer(), isValidVPSBenchmark(), etc.
• validateRecommendRequest()
• getAllowedOrigin()
• findUseCaseConfig()
• getDauMultiplier()
• getActiveUserRatio()
• estimateBandwidth()
• getProviderBandwidthAllocation()
• calculateBandwidthInfo()
• checkRateLimit()

handlers/health.ts (COMPLETE)

• handleHealth()

handlers/servers.ts (COMPLETE)

• handleGetServers()

handlers/recommend.ts (TO CREATE)

• handleRecommend() - Main handler
• queryCandidateServers() - D1 query for servers
• queryBenchmarkData() - Phoronix benchmarks
• getBenchmarkReference() - Match benchmarks to servers
• queryVPSBenchmarks() - Geekbench data
• queryVPSBenchmarksBatch() - Batch benchmark query
• formatVPSBenchmarkSummary() - Format for AI prompt
• formatBenchmarkSummary() - Format for AI prompt
• queryTechSpecs() - Tech stack specs
• formatTechSpecsForPrompt() - Format for AI prompt
• getAIRecommendations() - OpenAI GPT-4o-mini call
• parseAIResponse() - Parse AI JSON response

Migration Status

✅ types.ts - DONE ✅ config.ts - DONE ✅ utils.ts - DONE ✅ handlers/health.ts - DONE ✅ handlers/servers.ts - DONE ⏳ handlers/recommend.ts - IN PROGRESS (extracted functions ready) ⏳ index.ts - NEW version created (index.new.ts)

Next Steps

1. Create handlers/recommend.ts with all extracted functions
2. Backup original index.ts
3. Replace index.ts with index.new.ts
4. Run TypeScript typecheck
5. Test with npm run dev

Size Reduction

Original: index.ts (2381 lines) New distribution:

• index.ts: ~90 lines (97% reduction)
• types.ts: ~175 lines
• config.ts: ~140 lines
• utils.ts: ~650 lines
• handlers/: ~1300 lines total

Total: ~2355 lines (modular + maintainable)