webref/specs/001-reference-board-viewer/quickstart.md

# Quickstart Guide: Reference Board Viewer

**Last Updated:** 2025-11-02  
**For:** Developers starting implementation  
**Prerequisites:** Nix installed, basic Git knowledge  

## Overview

This guide will get you from zero to a running development environment for the Reference Board Viewer in under 10 minutes.

---

## Step 1: Clone and Enter Development Environment

```bash
# Clone repository (if not already)
cd /home/jawz/Development/Projects/personal/webref

# Enter Nix development shell (from flake.nix)
nix develop

# Verify tools are available
python --version    # Python 3.12
node --version      # Node.js 20+
psql --version      # PostgreSQL client
ruff --version      # Python linter
```

**What this does:** `flake.nix` provides all dependencies (Python, Node.js, PostgreSQL, MinIO, etc.)

---

## Step 2: Initialize Database

```bash
# Start PostgreSQL (in development)
# Option A: Using Nix
pg_ctl -D ./pgdata init
pg_ctl -D ./pgdata start

# Option B: Using system PostgreSQL
sudo systemctl start postgresql

# Create database
createdb webref

# Run migrations (after backend setup)
cd backend
alembic upgrade head
```

---

## Step 3: Set Up Backend (FastAPI)

```bash
# Create backend directory
mkdir -p backend
cd backend

# Initialize uv project
uv init

# Install dependencies (all verified in nixpkgs)
uv add fastapi uvicorn sqlalchemy alembic pydantic \
       python-jose passlib pillow boto3 python-multipart \
       httpx pytest pytest-cov pytest-asyncio

# Create basic structure
mkdir -p app/{auth,boards,images,database,api,core} tests

# Create main.py
cat > app/main.py << 'EOF'
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI(title="Reference Board Viewer API")

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173"],  # Vite dev server
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.get("/")
async def root():
    return {"message": "Reference Board Viewer API", "version": "1.0.0"}

@app.get("/health")
async def health():
    return {"status": "healthy"}
EOF

# Run development server
uvicorn app.main:app --reload --port 8000

# Test: curl http://localhost:8000/
```

**Verify:** Navigate to http://localhost:8000/docs to see auto-generated OpenAPI documentation.

---

## Step 4: Set Up Frontend (Svelte + Konva)

```bash
# Create frontend directory (in new terminal)
cd /home/jawz/Development/Projects/personal/webref
mkdir -p frontend
cd frontend

# Initialize SvelteKit project
npm create svelte@latest .
# Choose: Skeleton project, Yes to TypeScript, Yes to ESLint, Yes to Prettier

# Install dependencies
npm install
npm install konva

# Create basic canvas component
mkdir -p src/lib/canvas
cat > src/lib/canvas/Board.svelte << 'EOF'
<script lang="ts">
  import { onMount } from 'svelte';
  import Konva from 'konva';
  
  let container: HTMLDivElement;
  let stage: Konva.Stage;
  
  onMount(() => {
    stage = new Konva.Stage({
      container: container,
      width: window.innerWidth,
      height: window.innerHeight
    });
    
    const layer = new Konva.Layer();
    stage.add(layer);
    
    const text = new Konva.Text({
      text: 'Reference Board Canvas',
      fontSize: 24,
      fill: 'black',
      x: 50,
      y: 50
    });
    
    layer.add(text);
    layer.draw();
  });
</script>

<div bind:this={container} class="canvas-container"></div>

<style>
  .canvas-container {
    width: 100%;
    height: 100vh;
    background: #f0f0f0;
  }
</style>
EOF

# Update home page
cat > src/routes/+page.svelte << 'EOF'
<script>
  import Board from '$lib/canvas/Board.svelte';
</script>

<Board />
EOF

# Run development server
npm run dev -- --open

# Verify: Browser opens to http://localhost:5173
```

---

## Step 5: Start MinIO (Image Storage)

```bash
# In new terminal
mkdir -p ~/minio-data

# Start MinIO
minio server ~/minio-data --console-address :9001

# Access console: http://localhost:9001
# Default credentials: minioadmin / minioadmin

# Create bucket
mc alias set local http://localhost:9000 minioadmin minioadmin
mc mb local/webref
```

---

## Project Structure After Setup

```
webref/
├── backend/
│   ├── app/
│   │   ├── main.py              ✅ Created
│   │   ├── auth/
│   │   ├── boards/
│   │   ├── images/
│   │   ├── database/
│   │   └── core/
│   ├── tests/
│   ├── pyproject.toml           ✅ Created by uv
│   └── alembic.ini
├── frontend/
│   ├── src/
│   │   ├── lib/
│   │   │   └── canvas/
│   │   │       └── Board.svelte ✅ Created
│   │   └── routes/
│   │       └── +page.svelte     ✅ Created
│   ├── package.json             ✅ Created
│   └── vite.config.js
├── specs/
│   └── 001-reference-board-viewer/
│       ├── spec.md              ✅ Complete
│       ├── plan.md              ✅ Complete
│       ├── data-model.md        ✅ Complete
│       ├── tech-research.md     ✅ Complete
│       └── contracts/
│           └── api.yaml         ✅ Complete
├── shell.nix                    ✅ Update needed
└── flake.nix                    (To be created)
```

---

## Quick Commands Reference

### Backend
```bash
# All commands run inside nix develop shell

# Run API server
cd backend && uvicorn app.main:app --reload

# Run tests
cd backend && pytest

# Run with coverage
cd backend && pytest --cov=app --cov-report=html

# Check linting
cd backend && ruff check app/

# Format code
cd backend && ruff format app/

# Run migrations
cd backend && alembic upgrade head

# Create migration
cd backend && alembic revision --autogenerate -m "description"
```

### NixOS VM Integration Tests
```bash
# Run all tests (backend, full-stack, performance, security)
nix flake check

# Run specific test
nix build .#checks.backend-integration -L
nix build .#checks.full-stack -L

# Interactive debugging
nix build .#checks.backend-integration.driverInteractive
./result/bin/nixos-test-driver
```

### Frontend
```bash
# Run dev server
npm run dev

# Run tests
npm test

# Check types
npm run check

# Lint
npm run lint

# Build for production
npm run build

# Preview production build
npm run preview
```

### Database
```bash
# Connect to database
psql webref

# Backup database
pg_dump webref > backup.sql

# Restore database
psql webref < backup.sql

# Reset database
dropdb webref && createdb webref
alembic upgrade head
```

### MinIO
```bash
# List buckets
mc ls local/

# List files in bucket
mc ls local/webref/

# Copy file to bucket
mc cp file.jpg local/webref/originals/

# Remove file
mc rm local/webref/originals/file.jpg
```

---

## Environment Variables

Create `.env` file in backend/:

```bash
# Database
DATABASE_URL=postgresql://localhost/webref

# JWT Secret (generate with: openssl rand -hex 32)
SECRET_KEY=your-secret-key-here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# MinIO
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=webref
MINIO_SECURE=false

# CORS
CORS_ORIGINS=["http://localhost:5173"]

# File Upload
MAX_FILE_SIZE=52428800  # 50MB
MAX_BATCH_SIZE=524288000  # 500MB
ALLOWED_MIME_TYPES=["image/jpeg","image/png","image/gif","image/webp","image/svg+xml"]
```

Create `.env` in frontend/:

```bash
# API endpoint
VITE_API_URL=http://localhost:8000/api/v1

# Feature flags
VITE_ENABLE_COMMENTS=true
VITE_ENABLE_SLIDESHOW=true
```

---

## Testing the Setup

### 1. Backend Health Check
```bash
curl http://localhost:8000/health
# Expected: {"status":"healthy"}
```

### 2. API Documentation
Navigate to: http://localhost:8000/docs

### 3. Frontend Canvas
Navigate to: http://localhost:5173
Should see: "Reference Board Canvas" text on grey background

### 4. Database Connection
```bash
psql webref -c "SELECT 1;"
# Expected: (1 row)
```

### 5. MinIO Console
Navigate to: http://localhost:9001
Login with: minioadmin / minioadmin

---

## Troubleshooting

### "Nix command not found"
```bash
# Install Nix
curl -L https://nixos.org/nix/install | sh
```

### "Port 8000 already in use"
```bash
# Find and kill process
lsof -i :8000
kill -9 <PID>
```

### "PostgreSQL connection refused"
```bash
# Start PostgreSQL
sudo systemctl start postgresql
# Or using Nix:
pg_ctl -D ./pgdata start
```

### "npm install fails"
```bash
# Clear npm cache
npm cache clean --force
rm -rf node_modules package-lock.json
npm install
```

### "Python module not found"
```bash
# Reinstall with uv
uv sync
# Or exit and re-enter nix shell
exit
nix develop
```

---

## Next Steps

1. **Follow the plan:** See [plan.md](./plan.md) for 16-week implementation timeline
2. **Implement authentication:** Week 2 tasks in plan
3. **Set up database schema:** Use [data-model.md](./data-model.md) and Alembic
4. **Implement API endpoints:** Use [contracts/api.yaml](./contracts/api.yaml) as reference
5. **Build canvas components:** Follow Week 5-8 tasks

---

## Development Workflow

### Daily workflow:
```bash
# Morning
cd webref
nix develop
cd backend && uvicorn app.main:app --reload &
cd frontend && npm run dev &

# Work on features...

# Before commit
cd backend && pytest && ruff check app/
cd frontend && npm run check && npm run lint

# Commit
git add .
git commit -m "feat: description"
```

### Weekly workflow:
- Review plan.md progress
- Update tests for new features
- Check coverage: `pytest --cov`
- Update documentation

---

## Resources

- **API Spec:** [contracts/api.yaml](./contracts/api.yaml)
- **Data Model:** [data-model.md](./data-model.md)
- **Tech Stack:** [tech-research.md](./tech-research.md)
- **Nix Verification:** [VERIFICATION-COMPLETE.md](./VERIFICATION-COMPLETE.md)
- **Full Plan:** [plan.md](./plan.md)

**External Docs:**
- FastAPI: https://fastapi.tiangolo.com/
- Svelte: https://svelte.dev/docs
- Konva: https://konvajs.org/docs/
- Alembic: https://alembic.sqlalchemy.org/
- MinIO: https://min.io/docs/minio/linux/index.html

---

**Questions?** Check the specification in [spec.md](./spec.md) or plan in [plan.md](./plan.md).

**Ready to start?** Begin with Week 1 tasks in the implementation plan!