# Migration Guide: API Proxy Update

## What Changed

The web application now uses a Next.js API proxy by default instead of direct client-to-API connections. This provides better security and enables remote access.

## Benefits

- **Remote Access**: Access the web UI from anywhere - it will automatically connect to the API through the proxy
- **Security**: Only port 3000 needs to be exposed; API port 3001 stays internal
- **No CORS Issues**: Single-origin requests eliminate cross-origin problems
- **Simpler Deployment**: One port to expose and configure

## How to Update

### For Local Development

1. **Update your `.env.local` file**:

   ```bash
   cd apps/web
   # Remove or comment out the old direct API URL
   # NEXT_PUBLIC_WATCH_FINISHED_API=http://localhost:3001

   # Add the backend API URL for the Next.js server
   API_URL=http://localhost:3001
   ```

2. **Restart the development servers**:

   ```bash
   # From project root
   pnpm run dev
   ```

3. **Access the web UI**:
   - Open http://localhost:3000
   - The web UI will automatically proxy requests to the API at http://localhost:3001

### For Docker Deployment

1. **Rebuild your Docker images**:

   ```bash
   docker-compose build
   ```

2. **Update port mappings** (if you customized docker-compose.yml):
   - Only expose port 3000 externally
   - Port 3001 is now internal only

3. **Run the containers**:
   ```bash
   docker-compose up
   ```

### For Remote Access

**Before** (didn't work remotely):

- Web UI at `http://192.168.1.100:3000`
- Tried to connect to API at `http://localhost:3001` (failed from remote)

**After** (works remotely):

- Web UI at `http://192.168.1.100:3000`
- API requests automatically proxied through the web server
- WebSocket connections also proxied

### Advanced: Direct API Connection (Optional)

If you need the old behavior (direct client-to-API), you can bypass the proxy:

```bash
# In apps/web/.env.local
NEXT_PUBLIC_WATCH_FINISHED_API=http://your-api-server:3001
API_URL=http://localhost:3001
```

This is useful for:

- Development across multiple machines
- Custom API server locations
- Debugging proxy issues

## Architecture Changes

### Before

```
Browser → http://localhost:3001/api/* (direct)
Browser → ws://localhost:3001/socket.io (direct)
```

### After (Default)

```
Browser → http://localhost:3000/api/* → Next.js Proxy → http://localhost:3001/*
Browser → ws://localhost:3000/socket.io → Next.js Proxy → ws://localhost:3001/socket.io
```

### After (With NEXT_PUBLIC_WATCH_FINISHED_API set)

```
Browser → http://localhost:3001/api/* (direct, bypasses proxy)
Browser → ws://localhost:3001/socket.io (direct, bypasses proxy)
```

## Troubleshooting

### Web UI shows "Connection Error"

1. Check that the API service is running on port 3001
2. Verify `API_URL` in your environment matches where the API is running
3. Check the browser console for specific error messages

### WebSocket not connecting

1. Make sure both web and service are running
2. Check browser console for WebSocket connection errors
3. Verify the proxy is configured in `next.config.ts`

### Remote access still not working

1. Ensure firewall allows port 3000
2. Use the machine's IP address or hostname, not "localhost"
3. Check that API_URL points to the correct internal API location

## Rollback

To revert to the old behavior temporarily:

```bash
# In apps/web/.env.local
NEXT_PUBLIC_WATCH_FINISHED_API=http://localhost:3001
```

This will bypass the proxy and connect directly to the API.