echoes-of-the-ash/docs/API_REFACTOR_V2.md

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

# 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

# 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:

   # 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

# 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:

   curl https://your-domain.com/health
   

2. Register web user:

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

3. Get location:

   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