RUN_PROJECT_GUIDE.md

# IDP Project Runner Guide

## Quick Start

The easiest way to run the entire IDP system (both backend and frontend):

```bash
python run_project.py
```

This will:
1. ✓ Check all prerequisites (Python, Node.js, dependencies)
2. ✓ Start the FastAPI backend server on port 7860
3. ✓ Start the Next.js frontend server on port 3000
4. ✓ Monitor both processes and display their output
5. ✓ Handle graceful shutdown with Ctrl+C

## Usage Options

### Run Both Services (Default)
```bash
python run_project.py
```
- Backend: http://localhost:7860
- Frontend: http://localhost:3000

### Run Backend Only
```bash
python run_project.py --backend-only
```
Useful for API testing or when using a different frontend.

### Run Frontend Only
```bash
python run_project.py --frontend-only
```
Useful when backend is already running or deployed elsewhere.

### Custom Ports
```bash
python run_project.py --port-backend 8000 --port-frontend 3001
```

### Skip Prerequisite Checks
```bash
python run_project.py --no-check
```
Useful for faster startup when you know everything is installed.

### View All Options
```bash
python run_project.py --help
```

## What Gets Checked

The script automatically verifies:
- ✓ Python 3.10+ installed
- ✓ Node.js 18+ installed (if running frontend)
- ✓ npm installed (if running frontend)
- ✓ FastAPI installed
- ✓ PyTorch installed
- ✓ Frontend dependencies (`node_modules`)

## Environment Variables

The script automatically sets these for the backend:
- `KMP_DUPLICATE_LIB_OK=TRUE`
- `OMP_NUM_THREADS=1`
- `OPENBLAS_NUM_THREADS=1`
- `MKL_NUM_THREADS=1`
- `VECLIB_MAXIMUM_THREADS=1`
- `NUMEXPR_NUM_THREADS=1`
- `TF_CPP_MIN_LOG_LEVEL=2`

These prevent threading conflicts and reduce log noise.

## Features

### Color-Coded Output
- 🟦 **Blue** - Backend server logs
- 🟦 **Cyan** - Frontend server logs
- 🟩 **Green** - Success messages
- 🟨 **Yellow** - Warnings
- 🟥 **Red** - Errors

### Automatic Cleanup
- Filters out mutex warnings from backend
- Graceful shutdown of both services on Ctrl+C
- Timeout handling if processes don't respond

### Process Monitoring
- Detects if either service crashes
- Shows real-time output from both services
- Restarts are needed if a service dies

## Troubleshooting

### Backend won't start
```bash
# Check if dependencies are installed
pip install -r requirements.txt

# Check if port is already in use
lsof -i :7860

# Run backend only with verbose output
python run_project.py --backend-only
```

### Frontend won't start
```bash
# Install frontend dependencies
cd frontend
npm install

# Check if port is already in use
lsof -i :3000

# Run frontend only
python run_project.py --frontend-only
```

### Dependencies missing
```bash
# Backend dependencies
pip install -r requirements.txt

# Frontend dependencies
cd frontend && npm install
```

## Alternative Methods

### Using Shell Script (Backend Only)
```bash
./run_api_server.sh
```

### Manual Start
```bash
# Terminal 1 - Backend
python api_server.py

# Terminal 2 - Frontend
cd frontend && npm run dev
```

## Stopping the System

Press **Ctrl+C** once to trigger graceful shutdown. The script will:
1. Terminate backend process
2. Terminate frontend process
3. Wait up to 5 seconds for each
4. Force kill if needed

## Access Points

| Service | URL | Description |
|---------|-----|-------------|
| Frontend App | http://localhost:3000 | Main web interface |
| Backend API | http://localhost:7860 | REST API endpoint |
| API Documentation | http://localhost:7860/docs | Interactive API docs (Swagger) |
| Health Check | http://localhost:7860/health | System status |

## Production Deployment

For production, see:
- `deployment_guide.md` - Hugging Face Spaces deployment
- `PROJECT_DOCUMENTATION.md` - Complete system documentation

## License

MIT