docs: add migration guide for API proxy update

docs/MIGRATION_API_PROXY.md

@@ -0,0 +1,129 @@
+# 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.