Final Runbook: Running the Full Project

This guide brings everything together. Follow these steps to run your backend + mobile chat app end-to-end.

Prerequisites Checklist

Before starting, verify:

python --version        # Should be 3.10+
node --version          # Should be 18+
npm --version           # Should be 9+
git --version           # Any version

You also need: - An OpenAI API key (or another provider's key) - A code editor (VS Code recommended) - Expo Go app on your phone (iOS/Android) OR an emulator

Step 1: Backend Setup

Pick one method: virtual environment or Docker.

Option A: Virtual Environment

# Navigate to the project
cd aiproject/backend

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate       # Windows: venv\Scripts\activate

# Install dependencies
pip install -r app/requirements.txt

# Set your API key
cp app/.env.example app/.env
# Edit app/.env and add your OPENAI_API_KEY

Option B: Docker

# Navigate to the project
cd aiproject/backend

# Build the Docker image
docker compose build

# Set your API key (Docker Compose loads this automatically)
cp app/.env.example app/.env
# Edit app/.env and add your OPENAI_API_KEY

Step 2: Start the Backend

Option A: Virtual Environment

cd aiproject/backend
source venv/bin/activate
python app/__init__.py

Option B: Docker

cd aiproject/backend
docker compose up

You should see:

 * Running on http://127.0.0.1:5000

Test it:

curl http://127.0.0.1:5000/api/status
# → {"status":"ok"}

Step 3: Mobile Setup

# In a new terminal
cd aiproject/mobile

# Install Expo CLI globally (if not already installed)
npm install -g expo-cli

# Install project dependencies
npm install

# Start the Expo dev server
npx expo start

Scan the QR code with Expo Go on your phone, or press a for Android emulator / i for iOS simulator.

Step 4: Configure Mobile to Reach Backend

Find your computer's local IP:

# macOS/Linux
ip addr show | grep inet

# Windows (PowerShell)
ipconfig

In mobile/App.tsx, update the API_BASE_URL to your computer's local IP:

const API_BASE_URL = 'http://192.168.1.100:5000';  // Replace with your IP

Note: On Android emulator, use http://10.0.2.2:5000 instead. Note: On iOS simulator, http://localhost:5000 works.

Step 5: Test the Full Flow

  1. Backend is running on port 5000
  2. Mobile app is running via Expo
  3. Type a message in the chat app and press Send
  4. The message should appear in the chat, then the AI should respond

If messages show up and the AI replies, everything works!

Troubleshooting

Symptom Likely Cause Fix
Mobile can't reach backend Wrong IP in API_BASE_URL Use your computer's local IP (not localhost)
ModuleNotFoundError Missing dependency Run pip install -r app/requirements.txt
OpenAI returns error Missing or invalid API key Check app/.env file
Port already in use Another process on 5000 Kill it: kill $(lsof -t -i:5000) or use a different port
CORS error in browser flask-cors not enabled backend/step-06-cors.md has the fix
Expo QR code not working Network issue Ensure phone and computer are on same WiFi

Next Steps

  • Swap AI providers: See concepts/05-llm-comparison.md
  • Add RAG knowledge base: See advanced/rag/step-01.md
  • Make it agentic: See advanced/agentic/step-01.md
  • Run tests: cd backend && python -m pytest tests/ -v
  • Lint your code: ruff check backend/ advanced/
  • Set up CI/CD: See deployment/ci-cd.md
  • Deploy to production: See deployment/overview.md
  • Try the challenges: Each section has challenges.md with exercises
← Cost