RUN_PROJECT_GUIDE.md

IDP Project Runner Guide

Quick Start

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

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)

python run_project.py

• Backend: http://localhost:7860
• Frontend: http://localhost:3000

Run Backend Only

python run_project.py --backend-only

Useful for API testing or when using a different frontend.

Run Frontend Only

python run_project.py --frontend-only

Useful when backend is already running or deployed elsewhere.

Custom Ports

python run_project.py --port-backend 8000 --port-frontend 3001

Skip Prerequisite Checks

python run_project.py --no-check

Useful for faster startup when you know everything is installed.

View All Options

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

# 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

# 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

# Backend dependencies
pip install -r requirements.txt

# Frontend dependencies
cd frontend && npm install

Alternative Methods

Using Shell Script (Backend Only)

./run_api_server.sh

Manual Start

# 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