# Hybrid Development Setup Guide

## Prerequisites

1. **Docker** (for PostgreSQL and Redis)
   - Install: https://docs.docker.com/get-docker/

2. **Python 3.12+** (for backend)
   - Install: https://www.python.org/downloads/

3. **Node.js 18+** (for frontend, Phase 2)
   - Install: https://nodejs.org/

## Setup Steps

### 1. Start Database Services with Docker

```bash
# Navigate to project root
cd /home/user/wall-o/mtgonline-web

# Start PostgreSQL and Redis
docker compose -f docker-compose.dev.yml up -d

# Verify they're running
docker compose -f docker-compose.dev.yml ps
```

**Expected output:**
```
NAME                  STATUS        PORTS
mtgonline-web-postgres-1   Up   0.0.0.0:5432->5432/tcp
mtgonline-web-redis-1      Up   0.0.0.0:6379->6379/tcp
```

### 2. Create Virtual Environment and Install Backend Dependencies

```bash
# Navigate to backend directory
cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Linux/Mac:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

### 3. Configure Environment

```bash
# Copy example environment file
cp .env.example .env

# Edit .env with your configuration
# The defaults in .env.example should work for local development
```

### 4. Verify Database Connection

```bash
# Test database connection
python -c "
import asyncio
from app.core.database import async_engine

async def test_connection():
    async with async_engine.connect() as conn:
        result = await conn.execute('SELECT 1')
        print('Database connection successful!')

asyncio.run(test_connection())
"
```

### 5. Start the Backend Server

```bash
# With hot-reload for development
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Or without reload (faster startup)
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

**Backend will be available at:**
- API: http://localhost:8000
- Swagger Docs: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

### 6. Run Tests (Optional but Recommended)

```bash
# Install test dependencies
pip install pytest pytest-asyncio aiosqlite

# Run tests
pytest

# Run with coverage
pytest --cov=app --cov-report=html
```

### 7. Stop Services When Done

```bash
# Stop Docker services
cd /home/user/wall-o/mtgonline-web
docker compose -f docker-compose.dev.yml down

# Deactivate virtual environment (if in backend directory)
deactivate
```

## Troubleshooting

### Port Already in Use

If port 5432 or 6379 is already in use:

```bash
# Find what's using the port
lsof -i :5432
lsof -i :6379

# Kill the process (be careful!)
kill -9 <PID>

# Or change ports in docker-compose.dev.yml
```

### Database Connection Issues

```bash
# Check if PostgreSQL is running
docker compose -f docker-compose.dev.yml logs postgres

# Restart if needed
docker compose -f docker-compose.dev.yml restart postgres

# Check environment variables
echo $DATABASE_URL
```

### Python Dependencies

```bash
# If you get import errors
pip install -r requirements.txt --upgrade

# Check installed packages
pip list
```

## Development Workflow

### Daily Development

```bash
# 1. Start database services
docker compose -f docker-compose.dev.yml up -d

# 2. Activate backend environment
cd backend
source venv/bin/activate

# 3. Start backend (in one terminal)
uvicorn app.main:app --reload

# 4. Start frontend (in another terminal, Phase 2)
cd frontend
npm run dev
```

### After Code Changes

- **Backend changes**: Hot-reload automatically restarts the server
- **Frontend changes**: Hot-reload automatically refreshes the browser
- **Database changes**: Restart the backend server

### Database Schema Changes

When you modify models in `app/models/models.py`:

1. Update the models
2. Stop and restart the backend server
3. For production, you'll need Alembic migrations (not set up yet)

## Security Notes

⚠️ **Important for Production:**

- Change `JWT_SECRET_KEY` in `.env` to a strong random string
- Use HTTPS in production
- Set `DEBUG=False`
- Configure proper CORS origins
- Use environment variables for secrets (not `.env` file)

## Next Steps

- ✅ Set up hybrid development environment
- ⏳ Run database migration setup (Alembic)
- ⏳ Test all API endpoints
- ⏳ Begin Phase 2: Frontend development

## Useful Commands

```bash
# Check Docker status
docker compose -f docker-compose.dev.yml ps

# View Docker logs
docker compose -f docker-compose.dev.yml logs -f

# Stop and remove containers
docker compose -f docker-compose.dev.yml down

# Restart specific service
docker compose -f docker-compose.dev.yml restart postgres

# Check backend health
curl http://localhost:8000/health

# Check API docs
open http://localhost:8000/docs
```

## Support

If you encounter issues:
1. Check the logs: `docker compose -f docker-compose.dev.yml logs`
2. Verify environment variables: `echo $DATABASE_URL`
3. Test database connection manually
4. Check if ports are available: `lsof -i :5432`

---

**Status:** Hybrid development environment ready for use!