Analysis/docs/LOCAL_SETUP_GUIDE.md

Local Development Setup Guide

This guide provides step-by-step instructions for setting up and running the Data Analysis Platform on your local machine.

---

Table of Contents

1. Prerequisites Installation
2. Backend Setup
3. Frontend Setup
4. Running Both Services
5. Verification
6. Common Issues and Solutions
7. Development Tips

---

1. Prerequisites Installation

Verify Your Installation

Before starting, verify you have the required tools installed:

# Check Python version (must be 3.12+)
python3.12 --version

# Check Node.js version (must be 20+)
node --version

# Check npm (comes with Node.js)
npm --version

# Check UV (Python package manager)
uv --version

Install Missing Prerequisites

Python 3.12

macOS (using Homebrew):

brew install python@3.12

Ubuntu/Debian:

sudo apt update
sudo apt install python3.12 python3.12-venv

Windows: Download from python.org

Node.js 20+

macOS (using Homebrew):

brew install node

Ubuntu/Debian:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

Windows: Download from nodejs.org

UV (Python Package Manager)

pip install uv
# or
pipx install uv

---

2. Backend Setup

Step 1: Navigate to Backend Directory

cd backend

Step 2: Create Virtual Environment

A virtual environment isolates your project dependencies:

# Create virtual environment
python3.12 -m venv .venv

# Activate on macOS/Linux
source .venv/bin/activate

# Activate on Windows
.venv\Scripts\activate

You should see (.venv) appear in your terminal prompt.

Step 3: Install Dependencies with UV

UV is a fast Python package installer that resolves dependencies quickly:

uv sync

This reads pyproject.toml and uv.lock to install exact versions of all dependencies.

Step 4: Verify Installation

python -c "import fastapi; import pandas; import pyarrow; print('All dependencies installed!')"

Step 5: Start the Backend Server

uvicorn main:app --reload --host 0.0.0.0 --port 8000

Command explained:

• uvicorn - ASGI server for FastAPI
• main:app - Points to the FastAPI app instance in main.py
• --reload - Auto-reload on code changes (development mode)
• --host 0.0.0.0 - Listen on all network interfaces
• --port 8000 - Use port 8000

You should see output like:

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using WatchFiles
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Step 6: Access Backend Services

Open your browser and navigate to:

• API Root: http://localhost:8000
• Swagger UI (Interactive API Docs): http://localhost:8000/docs
• ReDoc (Alternative API Docs): http://localhost:8000/redoc

---

3. Frontend Setup

Step 1: Open New Terminal

Keep the backend running in its terminal. Open a new terminal for the frontend.

Step 2: Navigate to Frontend Directory

cd frontend

Step 3: Install Dependencies

npm install

This downloads all packages listed in package.json and package-lock.json.

Expected output includes packages like:

• next (16.1.1)
• react (19.2.3)
• typescript (latest)
• tailwindcss (4+)
• apache-arrow (21+)

Step 4: Configure Environment (Optional)

Check if .env.local exists:

ls -la .env.local

If not present, create it from the example (if available):

cp .env.local.example .env.local

Edit .env.local to configure environment-specific settings like API endpoints.

Step 5: Start the Frontend Development Server

npm run dev

You should see output like:

   ▲ Next.js 16.1.1
   - Local:        http://localhost:3000
   - Network:      http://192.168.1.X:3000

 ✓ Ready in 2.3s

Step 6: Access Frontend Application

Open your browser and navigate to:

Frontend App: http://localhost:3000

---

4. Running Both Services

For full-stack development, run both services simultaneously.

Option 1: Two Terminals (Recommended for Development)

Terminal 1 - Backend:

cd backend
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Terminal 2 - Frontend:

cd frontend
npm run dev

Option 2: Background Processes

Backend:

cd backend
source .venv/bin/activate
uvicorn main:app --reload --host 0.0.0.0 --port 8000 > ../backend.log 2>&1 &

Frontend:

cd frontend
npm run dev > ../frontend.log 2>&1 &

View logs:

tail -f backend.log
tail -f frontend.log

---

5. Verification

Test Backend Health

curl http://localhost:8000/docs

Or open http://localhost:8000/docs in your browser.

Test Frontend

Open http://localhost:3000 in your browser.

Check API Connectivity

From the frontend, you should be able to make requests to the backend at http://localhost:8000.

---

6. Common Issues and Solutions

Port Already in Use

Error: Address already in use

Solution:

# Find process using port 8000 (backend)
lsof -i :8000
# or
netstat -tlnp | grep :8000

# Kill the process
kill -9 <PID>

# Or use a different port
uvicorn main:app --reload --port 8001

Virtual Environment Issues

Error: Python command not found or wrong Python version

Solution:

# Deactivate current environment
deactivate

# Remove and recreate virtual environment
rm -rf .venv
python3.12 -m venv .venv
source .venv/bin/activate
uv sync

Module Import Errors

Error: ModuleNotFoundError: No module named 'fastapi'

Solution:

# Ensure virtual environment is activated
source .venv/bin/activate

# Reinstall dependencies
uv sync

Frontend Build Errors

Error: Cannot find module 'X'

Solution:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

CORS Errors (Frontend Cannot Access Backend)

Error: Browser console shows CORS policy errors

Solution: Ensure the backend has CORS middleware configured. Check backend/main.py for:

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

---

7. Development Tips

Hot Reload

• Backend: UVicorn's --reload flag automatically restarts the server when Python files change
• Frontend: Next.js dev server automatically refreshes the browser when files change

Useful Commands

Backend:

# Run tests
pytest

# Run with verbose output
uvicorn main:app --reload --log-level debug

Frontend:

# Run tests (when configured)
npm test

# Build for production
npm run build

# Run production build
npm start

# Lint code
npm run lint

IDE Recommendations

• VS Code with extensions:
  • Python (Microsoft)
  • Pylance
  • ESLint
  • Tailwind CSS IntelliSense
  • Thunder Client (for API testing)

Debugging

Backend: Use VS Code's debugger with launch configuration:

{
    "name": "Python: FastAPI",
    "type": "debugpy",
    "request": "launch",
    "module": "uvicorn",
    "args": ["main:app", "--reload", "--host", "0.0.0.0", "--port", "8000"],
    "cwd": "${workspaceFolder}/backend"
}

Frontend: Use Chrome DevTools or React DevTools browser extension.

---

Next Steps

Once both services are running:

1. Explore the API documentation at http://localhost:8000/docs
2. Interact with the frontend at http://localhost:3000
3. Review the project context at _bmad-output/project-context.md
4. Check planning artifacts in _bmad-output/planning-artifacts/

For Docker deployment instructions, see the main README.md (coming soon).

---

Last Updated: 2026-01-11