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

# 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

# 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)

# 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)

# 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)

# 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

# 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

# Run all tests (backend, full-stack, performance, security)
nix flake check

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

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

Frontend

# 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

# 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

# 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/:

# 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/:

# 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

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

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"

# Install Nix
curl -L https://nixos.org/nix/install | sh

"Port 8000 already in use"

# Find and kill process
lsof -i :8000
kill -9 <PID>

"PostgreSQL connection refused"

# Start PostgreSQL
sudo systemctl start postgresql
# Or using Nix:
pg_ctl -D ./pgdata start

"npm install fails"

# Clear npm cache
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

"Python module not found"

# Reinstall with uv
uv sync
# Or exit and re-enter nix shell
exit
nix develop

---

Next Steps

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

---

Development Workflow

Daily workflow:

# 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
• Data Model: data-model.md
• Tech Stack: tech-research.md
• Nix Verification: VERIFICATION-COMPLETE.md
• Full Plan: 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 or plan in plan.md.

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