Initial commit: Data Analysis application with FastAPI backend and Next.js frontend

2026-01-11 21:54:33 +01:00
commit 7bdafb4fbf
549 changed files with 96211 additions and 0 deletions
--- a/docs/LOCAL_SETUP_GUIDE.md
+++ b/docs/LOCAL_SETUP_GUIDE.md
@@ -0,0 +1,438 @@
+# 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](#1-prerequisites-installation)
+2. [Backend Setup](#2-backend-setup)
+3. [Frontend Setup](#3-frontend-setup)
+4. [Running Both Services](#4-running-both-services)
+5. [Verification](#5-verification)
+6. [Common Issues and Solutions](#6-common-issues-and-solutions)
+7. [Development Tips](#7-development-tips)
+
+---
+
+## 1. Prerequisites Installation
+
+### Verify Your Installation
+
+Before starting, verify you have the required tools installed:
+
+```bash
+# 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):**
+```bash
+brew install python@3.12
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt update
+sudo apt install python3.12 python3.12-venv
+```
+
+**Windows:**
+Download from [python.org](https://www.python.org/downloads/)
+
+#### Node.js 20+
+
+**macOS (using Homebrew):**
+```bash
+brew install node
+```
+
+**Ubuntu/Debian:**
+```bash
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt install -y nodejs
+```
+
+**Windows:**
+Download from [nodejs.org](https://nodejs.org/)
+
+#### UV (Python Package Manager)
+
+```bash
+pip install uv
+# or
+pipx install uv
+```
+
+---
+
+## 2. Backend Setup
+
+### Step 1: Navigate to Backend Directory
+
+```bash
+cd backend
+```
+
+### Step 2: Create Virtual Environment
+
+A virtual environment isolates your project dependencies:
+
+```bash
+# 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:
+
+```bash
+uv sync
+```
+
+This reads `pyproject.toml` and `uv.lock` to install exact versions of all dependencies.
+
+### Step 4: Verify Installation
+
+```bash
+python -c "import fastapi; import pandas; import pyarrow; print('All dependencies installed!')"
+```
+
+### Step 5: Start the Backend Server
+
+```bash
+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
+
+```bash
+cd frontend
+```
+
+### Step 3: Install Dependencies
+
+```bash
+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:
+
+```bash
+ls -la .env.local
+```
+
+If not present, create it from the example (if available):
+
+```bash
+cp .env.local.example .env.local
+```
+
+Edit `.env.local` to configure environment-specific settings like API endpoints.
+
+### Step 5: Start the Frontend Development Server
+
+```bash
+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:**
+```bash
+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:**
+```bash
+cd frontend
+npm run dev
+```
+
+### Option 2: Background Processes
+
+**Backend:**
+```bash
+cd backend
+source .venv/bin/activate
+uvicorn main:app --reload --host 0.0.0.0 --port 8000 > ../backend.log 2>&1 &
+```
+
+**Frontend:**
+```bash
+cd frontend
+npm run dev > ../frontend.log 2>&1 &
+```
+
+View logs:
+```bash
+tail -f backend.log
+tail -f frontend.log
+```
+
+---
+
+## 5. Verification
+
+### Test Backend Health
+
+```bash
+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:**
+```bash
+# 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:**
+```bash
+# 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:**
+```bash
+# Ensure virtual environment is activated
+source .venv/bin/activate
+
+# Reinstall dependencies
+uv sync
+```
+
+### Frontend Build Errors
+
+**Error:** `Cannot find module 'X'`
+
+**Solution:**
+```bash
+# 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:
+
+```python
+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:**
+```bash
+# Run tests
+pytest
+
+# Run with verbose output
+uvicorn main:app --reload --log-level debug
+```
+
+**Frontend:**
+```bash
+# 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:
+```json
+{
+    "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