mantimon-tcg/.claude/skills/dev-server/SKILL.md

Dev Server Skill

Start the complete Mantimon TCG development environment including all services.

Usage

/dev-server [command]

Commands:

• start (default) - Start all services (Docker infra + backend + frontend)
• stop - Stop all running services
• status - Check status of all services

Instructions

When this skill is invoked, follow these steps:

1. Pre-flight Checks

Run checks to understand current state:

# Check Docker services
cd /mnt/NV2/Development/mantimon-tcg/backend
docker compose ps 2>/dev/null | grep -E "mantimon-(postgres|redis|adminer)" || echo "Docker services: not running"

# Check application servers
curl -s http://localhost:8001/health 2>/dev/null && echo "Backend: running" || echo "Backend: not running"
curl -s http://localhost:3001 >/dev/null 2>&1 && echo "Frontend: running" || echo "Frontend: not running"

# Check environment files
[ -f "/mnt/NV2/Development/mantimon-tcg/frontend/.env.development" ] && echo "Frontend .env: OK" || echo "Frontend .env: MISSING"
[ -f "/mnt/NV2/Development/mantimon-tcg/backend/.env" ] && echo "Backend .env: OK" || echo "Backend .env: MISSING"

# Check dependencies
[ -d "/mnt/NV2/Development/mantimon-tcg/frontend/node_modules" ] && echo "node_modules: OK" || echo "node_modules: MISSING"
[ -d "/mnt/NV2/Development/mantimon-tcg/backend/.venv" ] && echo "Backend venv: OK" || echo "Backend venv: MISSING"

2. Start Infrastructure Services (Docker Compose)

Start PostgreSQL, Redis, and Adminer using the existing docker compose file:

cd /mnt/NV2/Development/mantimon-tcg/backend
docker compose up -d

# Wait for services to be healthy
echo "Waiting for services to be ready..."
sleep 5

# Verify services are up
docker compose ps

3. Install Dependencies (if needed)

# Frontend
if [ ! -d "/mnt/NV2/Development/mantimon-tcg/frontend/node_modules" ]; then
    echo "Installing frontend dependencies..."
    cd /mnt/NV2/Development/mantimon-tcg/frontend && npm install
fi

# Backend
if [ ! -d "/mnt/NV2/Development/mantimon-tcg/backend/.venv" ]; then
    echo "Installing backend dependencies..."
    cd /mnt/NV2/Development/mantimon-tcg/backend && uv sync
fi

4. Run Database Migrations

cd /mnt/NV2/Development/mantimon-tcg/backend && uv run alembic upgrade head

5. Start Application Servers

Start both servers in the background:

# Start backend (port 8001)
cd /mnt/NV2/Development/mantimon-tcg/backend && uv run uvicorn app.main:app --reload --port 8001 2>&1 &

# Wait for backend to be ready
for i in {1..15}; do
    curl -s http://localhost:8001/health 2>/dev/null && break
    sleep 1
done

# Start frontend (port 3001)
cd /mnt/NV2/Development/mantimon-tcg/frontend && npm run dev 2>&1 &

# Wait for frontend to be ready
for i in {1..15}; do
    curl -s http://localhost:3001 >/dev/null 2>&1 && break
    sleep 1
done

6. Display Status

After starting, display the status table:

## Dev Environment Status

| Service | URL/Port | Status |
|---------|----------|--------|
| Frontend | http://localhost:3001 | Running |
| Backend API | http://localhost:8001 | Running |
| API Docs | http://localhost:8001/docs | Running |
| PostgreSQL | localhost:5433 | Running |
| Redis | localhost:6380 | Running |
| Adminer | http://localhost:8090 | Running |

**Quick Links:**
- App: http://localhost:3001
- API Docs: http://localhost:8001/docs
- Health Check: http://localhost:8001/health
- Database Admin: http://localhost:8090 (System: PostgreSQL, Server: mantimon-postgres, User: mantimon, Pass: mantimon)

**OAuth Status:**
- Discord: [Configured/Not configured]
- Google: [Configured/Not configured]

Check OAuth configuration:

# Check if Discord is configured (has actual values, not placeholder)
grep -E "^DISCORD_CLIENT_ID=.+" /mnt/NV2/Development/mantimon-tcg/backend/.env 2>/dev/null | grep -v "your-client-id" && \
    echo "Discord OAuth: Configured" || echo "Discord OAuth: Not configured"

# Check if Google is configured
grep -E "^GOOGLE_CLIENT_ID=.+" /mnt/NV2/Development/mantimon-tcg/backend/.env 2>/dev/null | grep -v "your-client-id" && \
    echo "Google OAuth: Configured" || echo "Google OAuth: Not configured"

7. Stop Command

When stop is requested:

# Stop application servers
pkill -f "uvicorn app.main:app" 2>/dev/null
pkill -f "vite" 2>/dev/null

echo "Application servers stopped."

Then ask: "Stop Docker containers (PostgreSQL/Redis/Adminer) too? They can be left running for faster restarts."

If yes:

cd /mnt/NV2/Development/mantimon-tcg/backend && docker compose down

8. Status Command

When status is requested, check and display all services without starting anything:

cd /mnt/NV2/Development/mantimon-tcg/backend

echo "=== Docker Services ==="
docker compose ps

echo ""
echo "=== Application Servers ==="
curl -s http://localhost:8001/health 2>/dev/null && echo "Backend: healthy" || echo "Backend: not running"
curl -s http://localhost:3001 >/dev/null 2>&1 && echo "Frontend: running" || echo "Frontend: not running"

Port Configuration

Service	Port	Notes
Frontend	3001	Vite dev server
Backend	8001	FastAPI with uvicorn
PostgreSQL	5433	Non-standard to avoid conflicts
Redis	6380	Non-standard to avoid conflicts
Adminer	8090	Database admin UI

Environment Files

Frontend (frontend/.env.development)

VITE_API_BASE_URL=http://localhost:8001
VITE_WS_URL=http://localhost:8001
VITE_OAUTH_REDIRECT_URI=http://localhost:3001/auth/callback

Backend (backend/.env)

# Database
DATABASE_URL=postgresql+asyncpg://mantimon:mantimon@localhost:5433/mantimon

# Redis
REDIS_URL=redis://localhost:6380/0

# Security
SECRET_KEY=dev-secret-key-change-in-production

# OAuth (optional for dev)
DISCORD_CLIENT_ID=your-client-id
DISCORD_CLIENT_SECRET=your-client-secret
# GOOGLE_CLIENT_ID=your-client-id
# GOOGLE_CLIENT_SECRET=your-client-secret

# Base URL for OAuth callbacks
BASE_URL=http://localhost:8001

Troubleshooting

Port already in use

lsof -i :8001  # Find process
kill -9 <PID>  # Kill it

Docker services not starting

cd backend
docker compose logs  # Check what went wrong
docker compose down && docker compose up -d  # Restart

Database migrations failed

cd backend && uv run alembic downgrade -1 && uv run alembic upgrade head

Clear all and start fresh

cd backend
docker compose down -v  # Remove volumes too
docker compose up -d
uv run alembic upgrade head