cloud-orchestrator/README.md

# Server Recommendation System

AI-powered server recommendation service built on Cloudflare Workers, leveraging Workers AI, D1 Database, and real VPS benchmark data.

## Features

- **AI-Powered Recommendations**: Uses Workers AI (Llama 3.1 8B) to analyze requirements and provide intelligent recommendations
- **Real Benchmark Data**: 269 VPS benchmarks from 110 providers across 26 countries (Geekbench 6)
- **Natural Language Input**: Describe your project in plain language (tech stack, users, use case)
- **Cost-Efficiency Focus**: Budget/Balanced/Premium tiers with performance-per-dollar analysis
- **D1 Database**: Stores 1,119 server specifications with regional availability
- **KV Caching**: Caches recommendations for 1 hour to reduce AI calls

## API URL

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

## Architecture

```
┌─────────────┐
│   Client    │
└──────┬──────┘
       │ HTTP Request (Natural Language)
       ▼
┌─────────────────────────────────────────┐
│   Cloudflare Worker                     │
│  ┌───────────────────────────────────┐  │
│  │  Request Handler                  │  │
│  │  - CORS                           │  │
│  │  - Validation                     │  │
│  │  - Flexible Region Matching       │  │
│  └────┬──────────────────┬───────────┘  │
│       │                  │              │
│  ┌────▼─────┐  ┌─────────▼──────────┐   │
│  │ KV Cache │  │   D1 Database      │   │
│  │ (1h TTL) │  │ - 1,119 Servers    │   │
│  └──────────┘  │ - 269 Benchmarks   │   │
│                │ - 110 Providers    │   │
│                └─────────┬──────────┘   │
│                          │              │
│                ┌─────────▼───────────┐  │
│                │     Workers AI      │  │
│                │  (Llama 3.1 8B)     │  │
│                │ + Benchmark Data    │  │
│                └─────────────────────┘  │
└─────────────────────────────────────────┘
```

## API Endpoints

### GET /api/health

Health check endpoint.

```bash
curl https://server-recommend.kappa-d8e.workers.dev/api/health
```

**Response:**
```json
{
  "status": "ok",
  "timestamp": "2025-01-23T12:00:00.000Z",
  "service": "server-recommend"
}
```

### POST /api/recommend

Get AI-powered server recommendations based on your project requirements.

**Request Body:**
```json
{
  "tech_stack": "gnuboard php mysql",
  "expected_users": 1000,
  "use_case": "community forum website",
  "region_preference": ["korea"],
  "budget_range": "balanced",
  "provider_filter": ["vultr", "aws", "linode"]
}
```

**Fields:**

| Field | Required | Description |
|-------|----------|-------------|
| `tech_stack` | Yes | Technologies used (e.g., "nodejs express mongodb") |
| `expected_users` | Yes | Expected concurrent users |
| `use_case` | Yes | Brief description of the project |
| `region_preference` | No | Array of preferred regions (flexible matching) |
| `budget_range` | No | "budget", "balanced", or "premium" (default: "balanced") |
| `provider_filter` | No | Array of preferred providers |

**Region Matching:**

The system supports flexible region matching:
- Country codes: `kr`, `jp`, `sg`, `us`, `de`
- Country names: `korea`, `japan`, `singapore`
- City names: `seoul`, `tokyo`, `frankfurt`
- Region codes: `ap-northeast-2`, `us-east-1`

**Example Requests:**

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

# Node.js API server in Japan
curl -X POST https://server-recommend.kappa-d8e.workers.dev/api/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "tech_stack": "nodejs express postgresql",
    "expected_users": 500,
    "use_case": "REST API backend",
    "region_preference": ["japan"],
    "budget_range": "budget"
  }'

# High-traffic e-commerce in Singapore
curl -X POST https://server-recommend.kappa-d8e.workers.dev/api/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "tech_stack": "laravel php redis mysql",
    "expected_users": 5000,
    "use_case": "e-commerce platform",
    "region_preference": ["singapore"],
    "budget_range": "premium"
  }'
```

**Response:**
```json
{
  "recommendations": [
    {
      "tier": "Budget",
      "server_id": "vultr-vc2-1c-1gb",
      "server_name": "Vultr vc2-1c-1gb",
      "provider": "Vultr",
      "instance_type": "vc2-1c-1gb",
      "score": 85,
      "reasoning": "Excellent value for small PHP applications...",
      "strengths": [
        "Low monthly cost ($5)",
        "Seoul region for low latency to Korea",
        "High single-core benchmark (2053)"
      ],
      "considerations": [
        "Limited RAM (1GB) for growth",
        "May need upgrade for traffic spikes"
      ],
      "specs": {
        "cpu_cores": 1,
        "memory_gb": 1,
        "storage_gb": 25,
        "network_mbps": 1000
      },
      "benchmark": {
        "single_score": 2053,
        "multi_score": 3685,
        "benchmark_source": "Geekbench 6"
      },
      "price_monthly": 5,
      "available_regions": ["seoul", "tokyo", "singapore"]
    }
  ],
  "total_candidates": 15,
  "cached": false,
  "benchmark_context": {
    "total_benchmarks": 269,
    "matched_benchmarks": 8
  }
}
```

### GET /api/servers

List servers with optional filtering.

**Query Parameters:**
- `provider`: Filter by provider ID
- `minCpu`: Minimum CPU cores
- `minMemory`: Minimum memory in GB
- `region`: Filter by region code

```bash
curl "https://server-recommend.kappa-d8e.workers.dev/api/servers?provider=vultr&region=korea"
```

## Benchmark Data

### Statistics (2025-01-23)

| Metric | Count |
|--------|-------|
| Total Benchmarks | 269 |
| Providers | 110 |
| Countries | 26 |
| Asia Benchmarks | 50+ |

### Regional Reliability

| Region | Benchmarks | Providers | Reliability |
|--------|------------|-----------|-------------|
| US | 80+ | 40+ | 80% |
| DE | 50+ | 30+ | 75% |
| SG | 25+ | 15+ | 75% |
| JP | 13 | 8 | 70% |
| KR | 11 | 6 | 70% |
| NL | 20+ | 15+ | 75% |

### Top Providers by Performance/Dollar (Asia)

| Rank | Provider | Plan | Region | Single | Price | Perf/$ |
|------|----------|------|--------|--------|-------|--------|
| 1 | GreenCloud | 2c 4g AMD | SG | 974 | $2.1 | 1380.8 |
| 2 | Advin Servers | 4c 16gb AMD | SG | 981 | $8 | 517.3 |
| 3 | Vultr HP | 1c 1g AMD | SG | 1174 | $6 | 384.3 |
| 4 | Vultr Dedicated | AMD Seoul | KR | 2053 | $60 | - |
| 5 | ExtraVM | 1c 2g Intel | SG | 1782 | $10 | 357.0 |

## AI Recommendation Strategy

### Budget Tiers

The AI provides recommendations across three tiers:

1. **Budget Tier**: Best performance-per-dollar
   - Focus: Cost efficiency
   - Target: Small projects, development, testing

2. **Balanced Tier**: Optimal price-performance ratio
   - Focus: Value and reliability
   - Target: Production applications, medium traffic

3. **Premium Tier**: Maximum performance
   - Focus: Raw performance and reliability
   - Target: High-traffic, mission-critical applications

### Scoring Formula

- Requirement Match: 40%
- Value for Money: 30%
- Benchmark Performance: 20%
- Reliability/SLA: 10%

## Setup

### Quick Start

1. Install dependencies:
```bash
npm install
```

2. Create Cloudflare resources:
```bash
npx wrangler d1 create server-recommend-db
npx wrangler kv:namespace create CACHE
# Update wrangler.toml with the IDs
```

3. Initialize database:
```bash
npx wrangler d1 execute server-recommend-db --file=schema.sql
npx wrangler d1 execute server-recommend-db --file=seed.sql
```

4. Development:
```bash
npm run dev
```

5. Deploy:
```bash
npm run deploy
```

## Database Schema

**Tables:**
- `providers`: Cloud provider information (50+ providers)
- `servers`: Server specifications and pricing (1,119 servers)
- `regions`: Regional availability (100+ regions)
- `server_regions`: Server-region mapping
- `vps_benchmarks`: Geekbench 6 benchmark scores (269 records)

## Limitations

- **Game Servers**: AI recommendations may not be accurate for specialized workloads like Minecraft, game servers. Manual adjustment recommended.
- **Benchmark Coverage**: Some smaller providers may not have benchmark data.
- **Real-time Pricing**: Prices are updated periodically, not in real-time.

## Data Sources

- **Benchmarks**: Geekbench Browser, VPSBenchmarks.com, LowEndTalk
- **Benchmark Version**: Geekbench 6
- **Server Catalog**: Provider APIs, public documentation

## Performance

| Metric | Value |
|--------|-------|
| Cold Start | < 100ms |
| Warm Response | < 50ms |
| AI Response | 2-5s |
| Cached Response | < 100ms |

## License

ISC