# API Refactor v2.0 - Complete Redesign

## Overview

The API has been completely refactored to be **standalone and independent**. It no longer depends on bot modules and contains all necessary code within the `api/` directory.

## Changes

### ✅ Completed

1. **Cleaned root directory**:
   - Moved all `.md` documentation files to `docs/archive/`
   - Moved migration scripts to `scripts/`
   - Root is now clean with only essential config files

2. **Created standalone API modules**:
   - `api/database.py` - Complete database operations (no bot dependency)
   - `api/world_loader.py` - Game world loader with data models
   - `api/items.py` - Items manager
   - `api/game_logic.py` - All game mechanics
   - `api/main_new.py` - New standalone FastAPI application

3. **New database schema**:
   - `players.id` is now the primary key (auto-increment)
   - `telegram_id` is optional (nullable) for Telegram users
   - `username`/`password_hash` for web users
   - All foreign keys now reference `players.id` instead of `telegram_id`

4. **Simplified deployment**:
   - Removed unnecessary nginx complexity
   - Traefik handles all routing
   - PWA serves static files via nginx (efficient for static content)
   - API is completely standalone

## Migration Path

### Option 1: Fresh Start (Recommended)

**Pros**: Clean database, no migration issues  
**Cons**: Loses existing Telegram user data

```bash
# 1. Stop all containers
docker compose down

# 2. Remove old database
docker volume rm echoes-of-the-ashes-postgres-data

# 3. Update files
mv api/main_new.py api/main.py
mv api/requirements_new.txt api/requirements.txt
mv Dockerfile.api.new Dockerfile.api

# 4. Rebuild and start
docker compose up -d --build
```

### Option 2: Migrate Existing Data

**Pros**: Keeps Telegram user data  
**Cons**: Requires running migration script

```bash
# 1. Create migration script to:
#    - Add `id` column as primary key
#    - Make `telegram_id` nullable
#    - Update all foreign keys
#    - Backfill `id` values

# 2. Run migration
docker exec -it echoes_of_the_ashes_api python scripts/migrate_to_v2.py

# 3. Update files and rebuild
# (same as Option 1 steps 3-4)
```

## New API Structure

```
api/
├── main_new.py          # Standalone FastAPI app
├── database.py          # All database operations  
├── world_loader.py      # World data loading
├── items.py             # Items management
├── game_logic.py        # Game mechanics
├── internal.py          # (deprecated - logic moved to main)
└── requirements_new.txt # Minimal dependencies
```

## Bot Integration

The bot will now call the API for all operations instead of directly accessing the database.

### Bot Changes Needed:

1. **Replace direct database calls** with API calls using `httpx`:
   ```python
   # Old:
   player = await get_player(telegram_id)
   
   # New:
   response = await http_client.get(
       f"{API_URL}/api/internal/player/{telegram_id}",
       headers={"Authorization": f"Bearer {INTERNAL_KEY}"}
   )
   player = response.json()
   ```

2. **Use internal endpoints** (protected by API key):
   - `GET /api/internal/player/{telegram_id}` - Get player
   - `POST /api/internal/player` - Create player
   - All other game operations use public endpoints with JWT

## Environment Variables

```env
# Database
POSTGRES_USER=your_user
POSTGRES_PASSWORD=your_password
POSTGRES_DB=echoes_db
POSTGRES_HOST=echoes_of_the_ashes_db
POSTGRES_PORT=5432

# API
JWT_SECRET_KEY=your-jwt-secret-key
API_INTERNAL_KEY=your-internal-api-key

# Bot (if using)
TELEGRAM_BOT_TOKEN=your-bot-token
```

## Testing the New API

1. **Health check**:
   ```bash
   curl https://your-domain.com/health
   ```

2. **Register web user**:
   ```bash
   curl -X POST https://your-domain.com/api/auth/register \
     -H "Content-Type: application/json" \
     -d '{"username":"testuser","password":"testpass"}'
   ```

3. **Get location**:
   ```bash
   curl https://your-domain.com/api/game/location \
     -H "Authorization: Bearer YOUR_JWT_TOKEN"
   ```

## Benefits

1. **Standalone** - API has zero bot dependencies
2. **Clean** - All logic in one place
3. **Testable** - Easy to test without bot infrastructure
4. **Maintainable** - Clear separation of concerns
5. **Scalable** - API and bot can scale independently
6. **Flexible** - Easy to add new clients (mobile app, etc.)

## Next Steps

1. Choose migration path (fresh start vs migrate)
2. Update and rebuild containers
3. Test web interface
4. Refactor bot to use API endpoints
5. Remove old `api/main.py` and `api/internal.py`