Add Docker Compose setup for full-stack local development

.dockerignore

@@ -0,0 +1,13 @@
+venv
+__pycache__
+*.pyc
+*.pyo
+.env
+.git
+.github
+node_modules
+dist
+build
+.pytest_cache
+*.log
+.DS_Store

.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libgl1
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -e .
+
+      - name: Lint with flake8
+        run: |
+          flake8 src/ --count --select=E9,F63,F7,F82 --show-source --statistics
+          flake8 src/ --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+
+      - name: Test with pytest
+        run: |
+          pytest tests/ -v --tb=short
+
+  frontend:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check and build
+        run: npm run build

.gitignore

@@ -40,8 +40,8 @@ ENV/
 !notebooks/*.ipynb
 
 # Data
-data/
-datasets/
+/data/
+/datasets/
 *.tif
 *.tiff
 *.h5

CONTRIBUTING.md

@@ -31,7 +31,33 @@ We are committed to providing a welcoming and inclusive environment. Please be r
 
 #### First Time Contributors
 
-Look for issues labeled `good first issue` - these are specifically chosen for newcomers.
+Look for issues labeled `good first issue` — these are specifically chosen for newcomers.
+
+**Recommended first issues (ready to pick up):**
+
+| Issue | What You'll Learn | Time Estimate |
+|-------|-----------------|---------------|
+| [#9: Add frontend unit tests](https://github.com/Climate-Vision/ClimateVision/issues/9) | Vitest, React Testing Library, Vite | 2–4 hours |
+| [#13: Add Docker Compose](https://github.com/Climate-Vision/ClimateVision/issues/13) | Docker, multi-service orchestration | 3–6 hours |
+
+**How to claim an issue:**
+1. Read the issue description and acceptance criteria
+2. Comment "I'd like to work on this" — a maintainer will assign you
+3. Fork the repo and create a branch: `git checkout -b feature/issue-9-frontend-tests`
+4. Open a **draft PR** within 48 hours (even if incomplete) so we can give early feedback
+
+**Need help?** Tag `@Climate-Vision/maintainers` in the issue or open a [Discussion](https://github.com/Climate-Vision/ClimateVision/discussions).
+
+#### Intermediate Contributors
+
+Ready for something meatier? These issues close critical gaps in our production pipeline:
+
+| Issue | Area | Skills You'll Build |
+|-------|------|-------------------|
+| [#10: Alert delivery worker](https://github.com/Climate-Vision/ClimateVision/issues/10) | Backend | FastAPI BackgroundTasks, SMTP, webhooks |
+| [#11: WebSocket real-time updates](https://github.com/Climate-Vision/ClimateVision/issues/11) | Full-stack | FastAPI WebSockets, React hooks, graceful degradation |
+| [#12: ONNX Runtime inference](https://github.com/Climate-Vision/ClimateVision/issues/12) | MLOps | ONNX Runtime, PyTorch export, latency benchmarking |
+| [#14: Carbon analytics API](https://github.com/Climate-Vision/ClimateVision/issues/14) | Analytics | Feature flags, API schema design, geospatial math |
 
 #### Development Process
 

Dockerfile

@@ -0,0 +1,29 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy source code
+COPY . .
+
+# Install project in editable mode so climatevision module is available
+RUN pip install -e .
+
+EXPOSE 8000
+
+# Set environment variable to ensure python output is not buffered
+ENV PYTHONUNBUFFERED=1
+ENV OMP_NUM_THREADS=1
+
+# Run the FastAPI server
+CMD ["uvicorn", "climatevision.api.main:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -26,6 +26,25 @@ pip install -r requirements.txt
 
 ## Quickstart
 
+### Docker Compose (Recommended)
+
+The easiest way to run the full stack is using Docker Compose:
+
+1. Copy the environment variables:
+   ```bash
+   cp .env.example .env
+   cp frontend/.env.example frontend/.env
+   ```
+2. Start the environment:
+   ```bash
+   docker-compose up -d --build # or docker compose up -d --build
+   ```
+3. Access the application:
+   - Frontend: [http://localhost:5173](http://localhost:5173) (or `http://localhost:3000`)
+   - Backend API Docs: [http://localhost:8000/docs](http://localhost:8000/docs)
+
+### Manual Setup
+
 **Start the API server:**
 
 ```bash

docker-compose.yml

@@ -0,0 +1,33 @@
+version: "3.8"
+
+services:
+  backend:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8000:8000"
+    volumes:
+      - .:/app
+    environment:
+      - PYTHONUNBUFFERED=1
+    env_file:
+      - .env
+    restart: unless-stopped
+
+  frontend:
+    build:
+      context: ./frontend
+      dockerfile: Dockerfile
+    ports:
+      - "5173:5173"
+      # Expose on 3000 as well in case it's overridden
+      - "3000:3000"
+    volumes:
+      - ./frontend:/app
+      - /app/node_modules
+    environment:
+      - BACKEND_URL=http://backend:8000
+    depends_on:
+      - backend
+    restart: unless-stopped

frontend/.dockerignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+build
+.env
+.DS_Store
+*.log

frontend/Dockerfile

@@ -0,0 +1,17 @@
+FROM node:18-alpine
+
+WORKDIR /app
+
+# Copy package files
+COPY package.json package-lock.json* ./
+
+# Install dependencies
+RUN npm install
+
+# Copy source code
+COPY . .
+
+EXPOSE 5173 3000
+
+# Run dev server and bind to all network interfaces
+CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0"]

frontend/src/pages/NewAnalysis.tsx

@@ -3,7 +3,7 @@ import { useNavigate } from 'react-router-dom'
 import { Loader2 } from 'lucide-react'
 import type { AnalysisType } from '../api'
 import { predictJson } from '../api'
-import { MapBBoxPicker } from '../components/map/MapBBoxPicker'
+import { MapBBoxPicker } from '../components/Map/MapBBoxPicker'
 import { AnalysisTypeSelector } from '../components/ui/AnalysisTypeSelector'
 import { ResultsPanel } from '../components/results/ResultsPanel'
 import { ErrorBoundary } from '../components/ui/ErrorBoundary'

frontend/src/pages/Upload.tsx

@@ -4,7 +4,7 @@ import { CloudUpload, FileText, X, ChevronDown, ChevronUp, Loader2 } from 'lucid
 import type { AnalysisType } from '../api'
 import { predictUpload } from '../api'
 import { AnalysisTypeSelector } from '../components/ui/AnalysisTypeSelector'
-import { MapBBoxPicker } from '../components/map/MapBBoxPicker'
+import { MapBBoxPicker } from '../components/Map/MapBBoxPicker'
 import { ErrorBoundary } from '../components/ui/ErrorBoundary'
 import { useToast } from '../contexts/ToastContext'
 import { useApp } from '../contexts/AppContext'

frontend/vite.config.ts

@@ -8,7 +8,7 @@ export default defineConfig({
     strictPort: true,
     proxy: {
       '/api': {
-        target: 'http://127.0.0.1:8000',
+        target: process.env.BACKEND_URL || 'http://127.0.0.1:8000',
         changeOrigin: true,
       },
     },

requirements.txt

@@ -7,7 +7,6 @@ scikit-learn>=1.0.0
 
 # Geospatial Data Processing
 rasterio>=1.3.0
-gdal>=3.4.0
 geopandas>=0.12.0
 shapely>=2.0.0
 pyproj>=3.4.0
@@ -40,6 +39,7 @@ dask[complete]>=2023.1.0
 fastapi>=0.95.0
 uvicorn[standard]>=0.20.0
 pydantic>=2.0.0
+email-validator>=2.0.0
 python-multipart>=0.0.5
 
 # MLOps (optional)