cloud-orchestrator/test-new-api.md

# Server Recommendation API - New Input Format

## Change Summary

The server recommendation system now accepts **tech stack + user scale** instead of hardware specifications.

## API Changes

### Old Format (Hardware-based)
```json
POST /api/recommend
{
  "cpu_cores": 4,
  "memory_gb": 16,
  "storage_gb": 200
}
```

### New Format (Tech Stack-based)
```json
POST /api/recommend
{
  "tech_stack": ["Node.js", "MongoDB", "Redis", "Docker"],
  "expected_users": 5000,
  "use_case": "실시간 채팅 서비스",
  "traffic_pattern": "steady",
  "region_preference": ["asia", "us"],
  "budget_limit": 300
}
```

## Request Fields

### Required Fields

| Field | Type | Description | Example |
|-------|------|-------------|---------|
| `tech_stack` | string[] | Technologies used (min 1) | `["Node.js", "MongoDB"]` |
| `expected_users` | number | Expected user count | `5000` |
| `use_case` | string | Service description | `"실시간 채팅 서비스"` |

### Optional Fields

| Field | Type | Options | Default | Description |
|-------|------|---------|---------|-------------|
| `traffic_pattern` | string | `steady`, `spiky`, `growing` | `steady` | Traffic characteristics |
| `region_preference` | string[] | Region codes | - | Preferred regions |
| `budget_limit` | number | USD/month | - | Maximum monthly budget |

## Response Format

### New Response Structure
```json
{
  "recommendations": [
    {
      "server": {
        "id": "aws-t3-medium",
        "provider_name": "AWS",
        "name": "t3.medium",
        "instance_type": "t3.medium",
        "cpu_cores": 2,
        "memory_size": 4,
        "storage_size": 50,
        "storage_type": "SSD",
        "network_bandwidth": 5000,
        "sla_percentage": 99.95,
        "price_monthly": 30.36,
        "available_regions": ["us-east-1", "ap-northeast-1"]
      },
      "score": 95,
      "analysis": {
        "tech_fit": "Node.js와 MongoDB에 적합한 메모리와 SSD 스토리지 제공",
        "capacity": "5000 동시 사용자 처리 가능 (예상 부하의 150%)",
        "cost_efficiency": "가격 대비 성능 우수, 월 $30로 안정적 운영 가능",
        "scalability": "수평 확장 용이, Auto Scaling 지원으로 트래픽 변동 대응"
      },
      "estimated_capacity": {
        "max_concurrent_users": 7500,
        "requests_per_second": 1000
      }
    }
  ],
  "infrastructure_tips": [
    "Redis 캐싱으로 DB 부하 50% 감소 예상",
    "CDN 추가로 정적 자산 응답 속도 개선 권장",
    "MongoDB 인덱스 최적화로 쿼리 성능 향상"
  ],
  "total_candidates": 25,
  "cached": false
}
```

## Example Requests

### Example 1: Real-time Chat Service
```bash
curl -X POST https://your-worker.workers.dev/api/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "tech_stack": ["Node.js", "Socket.io", "MongoDB", "Redis"],
    "expected_users": 5000,
    "use_case": "실시간 채팅 서비스",
    "traffic_pattern": "spiky",
    "region_preference": ["asia"],
    "budget_limit": 300
  }'
```

### Example 2: REST API Server
```bash
curl -X POST https://your-worker.workers.dev/api/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "tech_stack": ["Python", "FastAPI", "PostgreSQL", "Docker"],
    "expected_users": 10000,
    "use_case": "REST API 서버",
    "traffic_pattern": "steady"
  }'
```

### Example 3: E-commerce Platform
```bash
curl -X POST https://your-worker.workers.dev/api/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "tech_stack": ["Java", "Spring Boot", "MySQL", "Redis", "Elasticsearch"],
    "expected_users": 50000,
    "use_case": "전자상거래 플랫폼",
    "traffic_pattern": "growing",
    "region_preference": ["asia", "us"],
    "budget_limit": 1000
  }'
```

## Validation Rules

### Tech Stack
- Must be a non-empty array
- At least 1 technology required
- Examples: Node.js, Python, Java, MongoDB, PostgreSQL, Redis, Docker

### Expected Users
- Must be a positive number
- Represents concurrent users or daily active users
- Used to calculate capacity requirements

### Use Case
- Must be a non-empty string
- Describes the service type
- Helps AI understand context and requirements

### Traffic Pattern
- `steady`: Consistent traffic throughout the day
- `spiky`: Sudden traffic bursts (2x capacity buffer)
- `growing`: Gradually increasing users (1.5x capacity buffer)

### Region Preference
- Array of region codes
- Examples: `asia`, `us`, `eu`
- Filters servers by availability

### Budget Limit
- Non-negative number
- In USD per month
- Filters servers by price

## AI Analysis Components

### Tech Fit
Explains why the server specifications match the technology stack requirements.

### Capacity
Describes how the server handles the expected user load and headroom.

### Cost Efficiency
Assesses value for money and operational cost considerations.

### Scalability
Evaluates growth potential and scaling strategies.

### Estimated Capacity
Provides concrete numbers for:
- Maximum concurrent users
- Requests per second

### Infrastructure Tips
Practical recommendations for:
- Performance optimization
- Cost reduction
- Reliability improvement
- Architecture enhancement

## Migration Guide

### From Old Format to New Format

**Old Request:**
```json
{
  "cpu_cores": 4,
  "memory_gb": 16,
  "storage_gb": 200,
  "sla_requirement": 99.9,
  "budget_monthly": 200
}
```

**New Request:**
```json
{
  "tech_stack": ["Node.js", "PostgreSQL"],
  "expected_users": 10000,
  "use_case": "웹 애플리케이션",
  "traffic_pattern": "steady",
  "budget_limit": 200
}
```

### Key Differences

1. **Resource Calculation**: Now automatic based on tech stack and user scale
2. **Context-Aware**: AI understands technology-specific requirements
3. **Capacity Estimation**: Provides realistic user capacity numbers
4. **Practical Tips**: Includes infrastructure optimization suggestions
5. **Simpler Input**: No need to estimate hardware specifications

## Benefits

1. **User-Friendly**: No need to know hardware requirements
2. **Intelligent**: AI analyzes tech stack characteristics
3. **Accurate**: Better matches based on actual usage patterns
4. **Actionable**: Provides capacity estimates and practical tips
5. **Flexible**: Adapts to different traffic patterns and growth scenarios