Add comprehensive specifications and planning documents for Reference Board Viewer application. Include detailed data model, API contracts, quickstart guide, and task breakdown for implementation. Ensure all artifacts are aligned with project objectives and constitutional principles.
This commit is contained in:
Danilo Reyes
489
specs/001-reference-board-viewer/quickstart.md
Normal file
489
specs/001-reference-board-viewer/quickstart.md
Normal file
@@ -0,0 +1,489 @@
|
||||
# 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 (installs all dependencies)
|
||||
nix develop
|
||||
|
||||
# Verify tools are available
|
||||
python --version # Should show Python 3.12+
|
||||
node --version # Should show Node.js latest
|
||||
psql --version # PostgreSQL client
|
||||
```
|
||||
|
||||
**What this does:** Nix installs all verified dependencies from nixpkgs (see VERIFICATION-COMPLETE.md)
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
# Run API server
|
||||
uvicorn app.main:app --reload
|
||||
|
||||
# Run tests
|
||||
pytest
|
||||
|
||||
# Run with coverage
|
||||
pytest --cov=app --cov-report=html
|
||||
|
||||
# Check linting
|
||||
ruff check app/
|
||||
|
||||
# Format code
|
||||
ruff format app/
|
||||
|
||||
# Run migrations
|
||||
alembic upgrade head
|
||||
|
||||
# Create migration
|
||||
alembic revision --autogenerate -m "description"
|
||||
```
|
||||
|
||||
### 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!
|
||||
|
||||
Reference in New Issue
Block a user