001-reference-board-viewer #1
@@ -1 +0,0 @@
|
|||||||
/nix/store/fw0ymh1b25q3x97wskwkl0n67d73irj1-nix-shell-env
|
|
||||||
File diff suppressed because it is too large
Load Diff
1
.gitignore
vendored
1
.gitignore
vendored
@@ -92,3 +92,4 @@ frontend/dist/
|
|||||||
!.specify/templates/
|
!.specify/templates/
|
||||||
!.specify/memory/
|
!.specify/memory/
|
||||||
|
|
||||||
|
.direnv/
|
||||||
27
README.md
27
README.md
@@ -27,13 +27,38 @@ direnv allow # .envrc already configured
|
|||||||
```
|
```
|
||||||
|
|
||||||
**Included tools:**
|
**Included tools:**
|
||||||
- Python 3.12 with all backend dependencies (FastAPI, SQLAlchemy, pytest, etc.)
|
- Python 3.13 with all backend dependencies (FastAPI, SQLAlchemy, pytest, psycopg2, etc.)
|
||||||
- Node.js + npm for frontend development
|
- Node.js + npm for frontend development
|
||||||
- PostgreSQL client tools
|
- PostgreSQL client tools
|
||||||
- MinIO client
|
- MinIO client
|
||||||
- Ruff (Python linter/formatter)
|
- Ruff (Python linter/formatter)
|
||||||
- All project dependencies from flake.nix
|
- All project dependencies from flake.nix
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Setup (first time only)
|
||||||
|
./scripts/quick-start.sh
|
||||||
|
|
||||||
|
# 2. Start backend (Terminal 1)
|
||||||
|
nix develop
|
||||||
|
cd backend
|
||||||
|
uvicorn app.main:app --reload
|
||||||
|
|
||||||
|
# 3. Start frontend (Terminal 2)
|
||||||
|
cd frontend
|
||||||
|
npm install # first time only
|
||||||
|
npm run dev
|
||||||
|
|
||||||
|
# 4. Test authentication (Terminal 3)
|
||||||
|
./scripts/test-auth.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
**Access:**
|
||||||
|
- Frontend: http://localhost:5173
|
||||||
|
- Backend API Docs: http://localhost:8000/docs
|
||||||
|
- Backend Health: http://localhost:8000/health
|
||||||
|
|
||||||
## Project Structure
|
## Project Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|||||||
@@ -47,7 +47,7 @@ def register_user(user_data: UserCreate, db: Session = Depends(get_db)):
|
|||||||
# Create user
|
# Create user
|
||||||
user = repo.create_user(email=user_data.email, password=user_data.password)
|
user = repo.create_user(email=user_data.email, password=user_data.password)
|
||||||
|
|
||||||
return UserResponse.from_orm(user)
|
return UserResponse.model_validate(user)
|
||||||
|
|
||||||
|
|
||||||
@router.post("/login", response_model=TokenResponse)
|
@router.post("/login", response_model=TokenResponse)
|
||||||
@@ -91,7 +91,7 @@ def login_user(login_data: UserLogin, db: Session = Depends(get_db)):
|
|||||||
return TokenResponse(
|
return TokenResponse(
|
||||||
access_token=access_token,
|
access_token=access_token,
|
||||||
token_type="bearer",
|
token_type="bearer",
|
||||||
user=UserResponse.from_orm(user)
|
user=UserResponse.model_validate(user)
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|
||||||
@@ -106,5 +106,5 @@ def get_current_user_info(current_user: User = Depends(get_current_user)):
|
|||||||
Returns:
|
Returns:
|
||||||
Current user information
|
Current user information
|
||||||
"""
|
"""
|
||||||
return UserResponse.from_orm(current_user)
|
return UserResponse.model_validate(current_user)
|
||||||
|
|
||||||
|
|||||||
@@ -18,9 +18,13 @@
|
|||||||
sqlalchemy
|
sqlalchemy
|
||||||
alembic
|
alembic
|
||||||
pydantic
|
pydantic
|
||||||
|
pydantic-settings # Settings management
|
||||||
|
psycopg2 # PostgreSQL driver
|
||||||
# Auth & Security
|
# Auth & Security
|
||||||
python-jose
|
python-jose
|
||||||
passlib
|
passlib
|
||||||
|
bcrypt # Password hashing backend for passlib
|
||||||
|
email-validator # Email validation for pydantic
|
||||||
# Image processing
|
# Image processing
|
||||||
pillow
|
pillow
|
||||||
# Storage
|
# Storage
|
||||||
|
|||||||
@@ -42,7 +42,7 @@
|
|||||||
}, 1500);
|
}, 1500);
|
||||||
} catch (err) {
|
} catch (err) {
|
||||||
const apiError = err as ApiError;
|
const apiError = err as ApiError;
|
||||||
error = apiError.error || apiError.detail || 'Registration failed. Please try again.';
|
error = apiError.error || (apiError.details as any)?.detail || 'Registration failed. Please try again.';
|
||||||
} finally {
|
} finally {
|
||||||
isLoading = false;
|
isLoading = false;
|
||||||
}
|
}
|
||||||
|
|||||||
144
scripts/quick-start.sh
Executable file
144
scripts/quick-start.sh
Executable file
@@ -0,0 +1,144 @@
|
|||||||
|
#!/usr/bin/env bash
|
||||||
|
# Quick Start Script for Reference Board Viewer
|
||||||
|
# This script sets up and runs the authentication system for testing
|
||||||
|
|
||||||
|
set -e
|
||||||
|
|
||||||
|
GREEN='\033[0;32m'
|
||||||
|
YELLOW='\033[1;33m'
|
||||||
|
RED='\033[0;31m'
|
||||||
|
NC='\033[0m'
|
||||||
|
|
||||||
|
echo "========================================="
|
||||||
|
echo "Reference Board Viewer - Quick Start"
|
||||||
|
echo "========================================="
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Check if we're in the right directory
|
||||||
|
if [ ! -f "flake.nix" ]; then
|
||||||
|
echo -e "${RED}Error: Please run this script from the project root${NC}"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Step 1: Create backend .env if it doesn't exist
|
||||||
|
echo -e "${YELLOW}Step 1: Setting up backend environment...${NC}"
|
||||||
|
if [ ! -f "backend/.env" ]; then
|
||||||
|
echo "Creating backend/.env..."
|
||||||
|
cat > backend/.env << 'EOF'
|
||||||
|
# Database
|
||||||
|
DATABASE_URL=postgresql://localhost/webref
|
||||||
|
|
||||||
|
# JWT Authentication
|
||||||
|
SECRET_KEY=test-secret-key-change-in-production-$(openssl rand -hex 16)
|
||||||
|
ALGORITHM=HS256
|
||||||
|
ACCESS_TOKEN_EXPIRE_MINUTES=30
|
||||||
|
|
||||||
|
# MinIO Storage (for later phases)
|
||||||
|
MINIO_ENDPOINT=localhost:9000
|
||||||
|
MINIO_ACCESS_KEY=minioadmin
|
||||||
|
MINIO_SECRET_KEY=minioadmin
|
||||||
|
MINIO_BUCKET=webref
|
||||||
|
MINIO_SECURE=false
|
||||||
|
|
||||||
|
# CORS
|
||||||
|
CORS_ORIGINS=http://localhost:5173,http://localhost:3000
|
||||||
|
|
||||||
|
# Application
|
||||||
|
DEBUG=true
|
||||||
|
APP_NAME=Reference Board Viewer
|
||||||
|
APP_VERSION=1.0.0
|
||||||
|
API_V1_PREFIX=/api/v1
|
||||||
|
|
||||||
|
# Logging
|
||||||
|
LOG_LEVEL=INFO
|
||||||
|
EOF
|
||||||
|
echo -e "${GREEN}✓ Created backend/.env${NC}"
|
||||||
|
else
|
||||||
|
echo -e "${GREEN}✓ backend/.env already exists${NC}"
|
||||||
|
fi
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Step 2: Create frontend .env if it doesn't exist
|
||||||
|
echo -e "${YELLOW}Step 2: Setting up frontend environment...${NC}"
|
||||||
|
if [ ! -f "frontend/.env" ]; then
|
||||||
|
echo "Creating frontend/.env..."
|
||||||
|
cat > frontend/.env << 'EOF'
|
||||||
|
VITE_API_URL=http://localhost:8000/api/v1
|
||||||
|
EOF
|
||||||
|
echo -e "${GREEN}✓ Created frontend/.env${NC}"
|
||||||
|
else
|
||||||
|
echo -e "${GREEN}✓ frontend/.env already exists${NC}"
|
||||||
|
fi
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Step 3: Check PostgreSQL
|
||||||
|
echo -e "${YELLOW}Step 3: Checking PostgreSQL...${NC}"
|
||||||
|
if ! command -v psql &> /dev/null; then
|
||||||
|
echo -e "${RED}✗ PostgreSQL not found. Please install PostgreSQL.${NC}"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Check if database exists
|
||||||
|
if psql -lqt | cut -d \| -f 1 | grep -qw webref; then
|
||||||
|
echo -e "${GREEN}✓ Database 'webref' exists${NC}"
|
||||||
|
else
|
||||||
|
echo "Creating database 'webref'..."
|
||||||
|
createdb webref || {
|
||||||
|
echo -e "${RED}✗ Failed to create database. Make sure PostgreSQL is running.${NC}"
|
||||||
|
echo "Try: sudo systemctl start postgresql"
|
||||||
|
exit 1
|
||||||
|
}
|
||||||
|
echo -e "${GREEN}✓ Created database 'webref'${NC}"
|
||||||
|
fi
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Step 4: Run migrations
|
||||||
|
echo -e "${YELLOW}Step 4: Running database migrations...${NC}"
|
||||||
|
echo "This requires the Nix development environment..."
|
||||||
|
if command -v nix &> /dev/null; then
|
||||||
|
nix develop -c bash -c "cd backend && alembic upgrade head" || {
|
||||||
|
echo -e "${RED}✗ Migration failed${NC}"
|
||||||
|
echo "You may need to run manually:"
|
||||||
|
echo " nix develop"
|
||||||
|
echo " cd backend"
|
||||||
|
echo " alembic upgrade head"
|
||||||
|
exit 1
|
||||||
|
}
|
||||||
|
echo -e "${GREEN}✓ Migrations complete${NC}"
|
||||||
|
else
|
||||||
|
echo -e "${YELLOW}⚠ Nix not found. Please run migrations manually:${NC}"
|
||||||
|
echo " nix develop"
|
||||||
|
echo " cd backend"
|
||||||
|
echo " alembic upgrade head"
|
||||||
|
fi
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
echo "========================================="
|
||||||
|
echo -e "${GREEN}Setup Complete!${NC}"
|
||||||
|
echo "========================================="
|
||||||
|
echo ""
|
||||||
|
echo "Next steps:"
|
||||||
|
echo ""
|
||||||
|
echo "1. Start the backend server (in one terminal):"
|
||||||
|
echo " $ nix develop"
|
||||||
|
echo " $ cd backend"
|
||||||
|
echo " $ uvicorn app.main:app --reload"
|
||||||
|
echo ""
|
||||||
|
echo "2. Start the frontend server (in another terminal):"
|
||||||
|
echo " $ cd frontend"
|
||||||
|
echo " $ npm install # if not done already"
|
||||||
|
echo " $ npm run dev"
|
||||||
|
echo ""
|
||||||
|
echo "3. Test the API:"
|
||||||
|
echo " $ ./test-auth.sh"
|
||||||
|
echo ""
|
||||||
|
echo "4. Open browser:"
|
||||||
|
echo " Backend API docs: http://localhost:8000/docs"
|
||||||
|
echo " Frontend app: http://localhost:5173"
|
||||||
|
echo ""
|
||||||
|
echo "5. Try registration:"
|
||||||
|
echo " - Navigate to http://localhost:5173/register"
|
||||||
|
echo " - Create an account"
|
||||||
|
echo " - Login and explore!"
|
||||||
|
echo ""
|
||||||
|
|
||||||
145
scripts/test-auth.sh
Executable file
145
scripts/test-auth.sh
Executable file
@@ -0,0 +1,145 @@
|
|||||||
|
#!/usr/bin/env bash
|
||||||
|
# Authentication Testing Script
|
||||||
|
# Run this after starting the backend server
|
||||||
|
|
||||||
|
set -e
|
||||||
|
|
||||||
|
API_BASE="http://localhost:8000"
|
||||||
|
API_V1="${API_BASE}/api/v1"
|
||||||
|
|
||||||
|
GREEN='\033[0;32m'
|
||||||
|
RED='\033[0;31m'
|
||||||
|
YELLOW='\033[1;33m'
|
||||||
|
NC='\033[0m' # No Color
|
||||||
|
|
||||||
|
echo "========================================="
|
||||||
|
echo "Testing Reference Board Viewer Auth API"
|
||||||
|
echo "========================================="
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Test 1: Health Check
|
||||||
|
echo -e "${YELLOW}Test 1: Health Check${NC}"
|
||||||
|
response=$(curl -s "${API_BASE}/health")
|
||||||
|
if echo "$response" | grep -q "healthy"; then
|
||||||
|
echo -e "${GREEN}✓ Health check passed${NC}"
|
||||||
|
else
|
||||||
|
echo -e "${RED}✗ Health check failed${NC}"
|
||||||
|
echo "Response: $response"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Test 2: Register User
|
||||||
|
echo -e "${YELLOW}Test 2: Register New User${NC}"
|
||||||
|
email="test_$(date +%s)@example.com"
|
||||||
|
password="TestPass123"
|
||||||
|
|
||||||
|
register_response=$(curl -s -X POST "${API_V1}/auth/register" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d "{\"email\":\"${email}\",\"password\":\"${password}\"}")
|
||||||
|
|
||||||
|
if echo "$register_response" | grep -q "id"; then
|
||||||
|
echo -e "${GREEN}✓ User registration successful${NC}"
|
||||||
|
echo "Email: $email"
|
||||||
|
else
|
||||||
|
echo -e "${RED}✗ User registration failed${NC}"
|
||||||
|
echo "Response: $register_response"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Test 3: Login User
|
||||||
|
echo -e "${YELLOW}Test 3: Login User${NC}"
|
||||||
|
login_response=$(curl -s -X POST "${API_V1}/auth/login" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d "{\"email\":\"${email}\",\"password\":\"${password}\"}")
|
||||||
|
|
||||||
|
if echo "$login_response" | grep -q "access_token"; then
|
||||||
|
echo -e "${GREEN}✓ Login successful${NC}"
|
||||||
|
token=$(echo "$login_response" | grep -o '"access_token":"[^"]*"' | cut -d'"' -f4)
|
||||||
|
echo "Token: ${token:0:20}..."
|
||||||
|
else
|
||||||
|
echo -e "${RED}✗ Login failed${NC}"
|
||||||
|
echo "Response: $login_response"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Test 4: Get Current User (Protected)
|
||||||
|
echo -e "${YELLOW}Test 4: Get Current User (Protected Endpoint)${NC}"
|
||||||
|
me_response=$(curl -s "${API_V1}/auth/me" \
|
||||||
|
-H "Authorization: Bearer ${token}")
|
||||||
|
|
||||||
|
if echo "$me_response" | grep -q "$email"; then
|
||||||
|
echo -e "${GREEN}✓ Protected endpoint works${NC}"
|
||||||
|
else
|
||||||
|
echo -e "${RED}✗ Protected endpoint failed${NC}"
|
||||||
|
echo "Response: $me_response"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Test 5: Invalid Token
|
||||||
|
echo -e "${YELLOW}Test 5: Test Invalid Token${NC}"
|
||||||
|
invalid_response=$(curl -s "${API_V1}/auth/me" \
|
||||||
|
-H "Authorization: Bearer invalid-token-here")
|
||||||
|
|
||||||
|
if echo "$invalid_response" | grep -q "Invalid\|Unauthorized"; then
|
||||||
|
echo -e "${GREEN}✓ Invalid token correctly rejected${NC}"
|
||||||
|
else
|
||||||
|
echo -e "${RED}✗ Invalid token not rejected properly${NC}"
|
||||||
|
echo "Response: $invalid_response"
|
||||||
|
fi
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Test 6: Duplicate Registration
|
||||||
|
echo -e "${YELLOW}Test 6: Test Duplicate Registration${NC}"
|
||||||
|
duplicate_response=$(curl -s -X POST "${API_V1}/auth/register" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d "{\"email\":\"${email}\",\"password\":\"${password}\"}")
|
||||||
|
|
||||||
|
if echo "$duplicate_response" | grep -q "already registered\|Conflict\|409"; then
|
||||||
|
echo -e "${GREEN}✓ Duplicate registration correctly rejected${NC}"
|
||||||
|
else
|
||||||
|
echo -e "${RED}✗ Duplicate registration should be rejected${NC}"
|
||||||
|
echo "Response: $duplicate_response"
|
||||||
|
fi
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Test 7: Weak Password
|
||||||
|
echo -e "${YELLOW}Test 7: Test Weak Password${NC}"
|
||||||
|
weak_response=$(curl -s -X POST "${API_V1}/auth/register" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d "{\"email\":\"weak_$(date +%s)@example.com\",\"password\":\"weak\"}")
|
||||||
|
|
||||||
|
if echo "$weak_response" | grep -q "Password\|validation\|400"; then
|
||||||
|
echo -e "${GREEN}✓ Weak password correctly rejected${NC}"
|
||||||
|
else
|
||||||
|
echo -e "${RED}✗ Weak password should be rejected${NC}"
|
||||||
|
echo "Response: $weak_response"
|
||||||
|
fi
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Test 8: Wrong Password
|
||||||
|
echo -e "${YELLOW}Test 8: Test Wrong Password${NC}"
|
||||||
|
wrong_pass_response=$(curl -s -X POST "${API_V1}/auth/login" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d "{\"email\":\"${email}\",\"password\":\"WrongPass123\"}")
|
||||||
|
|
||||||
|
if echo "$wrong_pass_response" | grep -q "Incorrect\|Unauthorized\|401"; then
|
||||||
|
echo -e "${GREEN}✓ Wrong password correctly rejected${NC}"
|
||||||
|
else
|
||||||
|
echo -e "${RED}✗ Wrong password should be rejected${NC}"
|
||||||
|
echo "Response: $wrong_pass_response"
|
||||||
|
fi
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
echo "========================================="
|
||||||
|
echo -e "${GREEN}All authentication tests passed!${NC}"
|
||||||
|
echo "========================================="
|
||||||
|
echo ""
|
||||||
|
echo "Test user created:"
|
||||||
|
echo " Email: $email"
|
||||||
|
echo " Password: $password"
|
||||||
|
echo " Token: ${token:0:30}..."
|
||||||
|
|
||||||
@@ -1,391 +0,0 @@
|
|||||||
# ✅ PLANNING COMPLETE: Reference Board Viewer
|
|
||||||
|
|
||||||
**Date:** 2025-11-02
|
|
||||||
**Branch:** 001-reference-board-viewer
|
|
||||||
**Status:** Ready for Implementation (Week 1)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Executive Summary
|
|
||||||
|
|
||||||
Complete implementation plan ready for a web-based reference board application (PureRef-inspired) for artists and creative professionals. All research, design, and planning artifacts have been generated and verified.
|
|
||||||
|
|
||||||
**Technology Stack:** ✅ 100% Verified in Nix
|
|
||||||
**Timeline:** 16 weeks to MVP
|
|
||||||
**Team Size:** 2-3 developers recommended
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Workflow Completion Status
|
|
||||||
|
|
||||||
### Phase 0: Research & Design ✅ COMPLETE
|
|
||||||
|
|
||||||
| Artifact | Status | Description |
|
|
||||||
|----------|--------|-------------|
|
|
||||||
| **tech-research.md** | ✅ Complete (18KB) | Comprehensive technology stack analysis with alternatives |
|
|
||||||
| **nix-package-verification.md** | ✅ Complete | Detailed verification of all packages in nixpkgs |
|
|
||||||
| **VERIFICATION-COMPLETE.md** | ✅ Complete | Proof of 100% Nix compatibility + command outputs |
|
|
||||||
| **Clarifications** | ✅ Resolved | All 3 NEEDS CLARIFICATION items resolved |
|
|
||||||
|
|
||||||
**Key Decisions:**
|
|
||||||
- Frontend: Svelte + SvelteKit + Konva.js
|
|
||||||
- Backend: FastAPI (Python)
|
|
||||||
- Database: PostgreSQL
|
|
||||||
- Storage: MinIO (S3-compatible)
|
|
||||||
- Image Processing: Pillow + ImageMagick
|
|
||||||
- Deployment: Nix Flakes + NixOS modules
|
|
||||||
|
|
||||||
### Phase 1: Design & Contracts ✅ COMPLETE
|
|
||||||
|
|
||||||
| Artifact | Status | Lines | Description |
|
|
||||||
|----------|--------|-------|-------------|
|
|
||||||
| **data-model.md** | ✅ Complete | 650+ | Full database schema with all entities |
|
|
||||||
| **contracts/api.yaml** | ✅ Complete | 900+ | OpenAPI 3.0 spec for REST API |
|
|
||||||
| **plan.md** | ✅ Complete | 750+ | 16-week implementation plan |
|
|
||||||
| **quickstart.md** | ✅ Complete | 400+ | Developer getting-started guide |
|
|
||||||
|
|
||||||
**Agent Context:** ✅ Updated (.cursor/rules/specify-rules.mdc)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Generated Artifacts
|
|
||||||
|
|
||||||
### 📄 Specification Documents
|
|
||||||
|
|
||||||
```
|
|
||||||
specs/001-reference-board-viewer/
|
|
||||||
├── spec.md ✅ 708 lines (Requirements)
|
|
||||||
├── plan.md ✅ 750 lines (Implementation plan)
|
|
||||||
├── data-model.md ✅ 650 lines (Database schema)
|
|
||||||
├── tech-research.md ✅ 661 lines (Technology analysis)
|
|
||||||
├── nix-package-verification.md ✅ 468 lines (Package verification)
|
|
||||||
├── VERIFICATION-COMPLETE.md ✅ Summary + proof
|
|
||||||
├── PLANNING-COMPLETE.md ✅ This file
|
|
||||||
├── quickstart.md ✅ 400 lines (Getting started)
|
|
||||||
├── contracts/
|
|
||||||
│ └── api.yaml ✅ 900 lines (OpenAPI spec)
|
|
||||||
└── checklists/
|
|
||||||
└── requirements.md ✅ 109 lines (Quality validation)
|
|
||||||
|
|
||||||
Total: ~5,100 lines of comprehensive documentation
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🔬 Research Findings
|
|
||||||
|
|
||||||
**Technology Evaluation:**
|
|
||||||
- ✅ 14 different options analyzed
|
|
||||||
- ✅ Frontend: React vs Svelte vs Vue (Svelte chosen)
|
|
||||||
- ✅ Canvas: Konva vs Fabric vs PixiJS (Konva chosen)
|
|
||||||
- ✅ Backend: FastAPI vs Django vs Node vs Rust (FastAPI chosen)
|
|
||||||
- ✅ All decisions documented with rationale
|
|
||||||
|
|
||||||
**Nix Verification:**
|
|
||||||
- ✅ 27 packages checked
|
|
||||||
- ✅ 27 packages verified
|
|
||||||
- ✅ 0 packages missing
|
|
||||||
- ✅ 100% compatibility confirmed
|
|
||||||
|
|
||||||
### 🗄️ Data Model
|
|
||||||
|
|
||||||
**7 Core Entities Defined:**
|
|
||||||
1. User (authentication, account management)
|
|
||||||
2. Board (canvas, viewport state)
|
|
||||||
3. Image (uploaded files, metadata)
|
|
||||||
4. BoardImage (junction: position, transformations)
|
|
||||||
5. Group (annotations, colored labels)
|
|
||||||
6. ShareLink (configurable permissions)
|
|
||||||
7. Comment (viewer feedback)
|
|
||||||
|
|
||||||
**Complete Schema:**
|
|
||||||
- ✅ All fields defined with types and constraints
|
|
||||||
- ✅ Indexes specified for performance
|
|
||||||
- ✅ Relationships mapped
|
|
||||||
- ✅ Validation rules documented
|
|
||||||
- ✅ PostgreSQL CREATE statements provided
|
|
||||||
|
|
||||||
### 🔌 API Contracts
|
|
||||||
|
|
||||||
**28 Endpoints Defined:**
|
|
||||||
|
|
||||||
**Authentication (3):**
|
|
||||||
- POST /auth/register
|
|
||||||
- POST /auth/login
|
|
||||||
- GET /auth/me
|
|
||||||
|
|
||||||
**Boards (5):**
|
|
||||||
- GET /boards
|
|
||||||
- POST /boards
|
|
||||||
- GET /boards/{id}
|
|
||||||
- PATCH /boards/{id}
|
|
||||||
- DELETE /boards/{id}
|
|
||||||
|
|
||||||
**Images (4):**
|
|
||||||
- POST /boards/{id}/images
|
|
||||||
- PATCH /boards/{id}/images/{id}
|
|
||||||
- DELETE /boards/{id}/images/{id}
|
|
||||||
- PATCH /boards/{id}/images/bulk
|
|
||||||
|
|
||||||
**Groups (4):**
|
|
||||||
- GET /boards/{id}/groups
|
|
||||||
- POST /boards/{id}/groups
|
|
||||||
- PATCH /boards/{id}/groups/{id}
|
|
||||||
- DELETE /boards/{id}/groups/{id}
|
|
||||||
|
|
||||||
**Sharing (4):**
|
|
||||||
- GET /boards/{id}/share-links
|
|
||||||
- POST /boards/{id}/share-links
|
|
||||||
- DELETE /boards/{id}/share-links/{id}
|
|
||||||
- GET /shared/{token}
|
|
||||||
|
|
||||||
**Export & Library (3):**
|
|
||||||
- POST /boards/{id}/export
|
|
||||||
- GET /library/images
|
|
||||||
|
|
||||||
**All endpoints include:**
|
|
||||||
- Request/response schemas
|
|
||||||
- Authentication requirements
|
|
||||||
- Error responses
|
|
||||||
- Example payloads
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Implementation Roadmap
|
|
||||||
|
|
||||||
### Timeline: 16 Weeks (4 Months)
|
|
||||||
|
|
||||||
| Phase | Weeks | Focus | Deliverables |
|
|
||||||
|-------|-------|-------|--------------|
|
|
||||||
| **Phase 1** | 1-4 | Foundation | Auth, Boards, Upload, Storage |
|
|
||||||
| **Phase 2** | 5-8 | Canvas | Manipulation, Transforms, Multi-select |
|
|
||||||
| **Phase 3** | 9-12 | Advanced | Groups, Sharing, Export |
|
|
||||||
| **Phase 4** | 13-16 | Polish | Performance, Testing, Deployment |
|
|
||||||
|
|
||||||
### Week-by-Week Breakdown
|
|
||||||
|
|
||||||
**Week 1:** Project setup, Nix config, CI/CD
|
|
||||||
**Week 2:** Authentication system (JWT)
|
|
||||||
**Week 3:** Board CRUD operations
|
|
||||||
**Week 4:** Image upload & MinIO
|
|
||||||
**Week 5:** Canvas foundation (Konva.js)
|
|
||||||
**Week 6:** Image transformations
|
|
||||||
**Week 7:** Multi-selection & bulk ops
|
|
||||||
**Week 8:** Z-order & layering
|
|
||||||
**Week 9:** Grouping & annotations
|
|
||||||
**Week 10:** Alignment & distribution
|
|
||||||
**Week 11:** Board sharing (permissions)
|
|
||||||
**Week 12:** Export (ZIP, composite)
|
|
||||||
**Week 13:** Performance & adaptive quality
|
|
||||||
**Week 14:** Command palette & features
|
|
||||||
**Week 15:** Testing & accessibility
|
|
||||||
**Week 16:** Deployment & documentation
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Success Criteria
|
|
||||||
|
|
||||||
### Functional ✅ Defined
|
|
||||||
- [ ] 18 functional requirements implemented
|
|
||||||
- [ ] All user scenarios work end-to-end
|
|
||||||
- [ ] No critical bugs
|
|
||||||
- [ ] Beta users complete workflows
|
|
||||||
|
|
||||||
### Quality ✅ Defined
|
|
||||||
- [ ] ≥80% test coverage (pytest + Vitest)
|
|
||||||
- [ ] Zero linter errors (Ruff + ESLint)
|
|
||||||
- [ ] All tests passing in CI
|
|
||||||
- [ ] Code reviews approved
|
|
||||||
|
|
||||||
### Performance ✅ Defined
|
|
||||||
- [ ] Canvas 60fps with 500 images
|
|
||||||
- [ ] API <200ms p95
|
|
||||||
- [ ] Page load <3s on 5Mbps
|
|
||||||
- [ ] Board with 100 images loads <2s
|
|
||||||
|
|
||||||
### Accessibility ✅ Defined
|
|
||||||
- [ ] WCAG 2.1 AA compliant
|
|
||||||
- [ ] Keyboard navigation for all features
|
|
||||||
- [ ] User-friendly error messages
|
|
||||||
- [ ] 90%+ "easy to use" rating
|
|
||||||
|
|
||||||
### Deployment ✅ Defined
|
|
||||||
- [ ] `nixos-rebuild` deploys successfully
|
|
||||||
- [ ] All services start correctly
|
|
||||||
- [ ] Rollback works
|
|
||||||
- [ ] Documentation complete
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Constitutional Compliance
|
|
||||||
|
|
||||||
All planning aligns with project constitution:
|
|
||||||
|
|
||||||
✅ **Principle 1 (Code Quality):** Modular architecture, type hints, linting
|
|
||||||
✅ **Principle 2 (Testing):** ≥80% coverage, comprehensive test strategy
|
|
||||||
✅ **Principle 3 (UX):** WCAG 2.1 AA, keyboard nav, clear errors
|
|
||||||
✅ **Principle 4 (Performance):** Specific budgets (60fps, <200ms, etc)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Technology Stack Summary
|
|
||||||
|
|
||||||
### Frontend
|
|
||||||
```javascript
|
|
||||||
- Framework: Svelte + SvelteKit
|
|
||||||
- Canvas: Konva.js
|
|
||||||
- Build: Vite
|
|
||||||
- Package Manager: npm (via Nix buildNpmPackage)
|
|
||||||
- State: Svelte Stores
|
|
||||||
- Testing: Vitest + Testing Library + Playwright
|
|
||||||
```
|
|
||||||
|
|
||||||
### Backend
|
|
||||||
```python
|
|
||||||
- Framework: FastAPI
|
|
||||||
- Server: Uvicorn
|
|
||||||
- ORM: SQLAlchemy
|
|
||||||
- Migrations: Alembic
|
|
||||||
- Validation: Pydantic
|
|
||||||
- Auth: python-jose + passlib
|
|
||||||
- Image Processing: Pillow + ImageMagick
|
|
||||||
- Storage Client: boto3 (S3-compatible)
|
|
||||||
- Testing: pytest + pytest-cov + pytest-asyncio
|
|
||||||
```
|
|
||||||
|
|
||||||
### Infrastructure
|
|
||||||
```nix
|
|
||||||
- Database: PostgreSQL 16
|
|
||||||
- Storage: MinIO (S3-compatible)
|
|
||||||
- Reverse Proxy: Nginx
|
|
||||||
- Deployment: Nix Flakes + NixOS modules
|
|
||||||
- Package Manager: uv (Python) + npm (JS)
|
|
||||||
```
|
|
||||||
|
|
||||||
**All Verified:** See VERIFICATION-COMPLETE.md
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Next Steps
|
|
||||||
|
|
||||||
### Immediate (Week 1)
|
|
||||||
|
|
||||||
1. **Review all documents:**
|
|
||||||
- Read spec.md (requirements)
|
|
||||||
- Read plan.md (implementation strategy)
|
|
||||||
- Read data-model.md (database design)
|
|
||||||
- Review contracts/api.yaml (API design)
|
|
||||||
|
|
||||||
2. **Set up environment:**
|
|
||||||
- Follow quickstart.md
|
|
||||||
- Create flake.nix (based on examples in nix-package-verification.md)
|
|
||||||
- Initialize Git repository structure
|
|
||||||
- Set up CI/CD pipeline
|
|
||||||
|
|
||||||
3. **Create project structure:**
|
|
||||||
```bash
|
|
||||||
mkdir -p backend/{app,tests}
|
|
||||||
mkdir -p frontend/{src,tests}
|
|
||||||
mkdir -p docs
|
|
||||||
```
|
|
||||||
|
|
||||||
4. **Start Week 1 tasks:**
|
|
||||||
- See plan.md, Phase 1, Week 1
|
|
||||||
- Initialize backend (FastAPI + uv)
|
|
||||||
- Initialize frontend (SvelteKit + Vite)
|
|
||||||
- Configure PostgreSQL with Nix
|
|
||||||
- Set up pre-commit hooks
|
|
||||||
|
|
||||||
### This Week (Week 2-4)
|
|
||||||
|
|
||||||
- Complete Phase 1 (Foundation)
|
|
||||||
- Implement authentication
|
|
||||||
- Build board CRUD
|
|
||||||
- Set up image upload & storage
|
|
||||||
|
|
||||||
### This Month (Weeks 1-8)
|
|
||||||
|
|
||||||
- Complete Phases 1 & 2
|
|
||||||
- Working canvas with manipulation
|
|
||||||
- Multi-selection and transformations
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Documentation Map
|
|
||||||
|
|
||||||
| Document | Purpose | When to Use |
|
|
||||||
|----------|---------|-------------|
|
|
||||||
| **spec.md** | Requirements | Understanding WHAT to build |
|
|
||||||
| **plan.md** | Implementation | Knowing HOW to build it |
|
|
||||||
| **data-model.md** | Database | Designing data structures |
|
|
||||||
| **contracts/api.yaml** | API | Implementing endpoints |
|
|
||||||
| **tech-research.md** | Technology | Understanding WHY we chose tech |
|
|
||||||
| **quickstart.md** | Getting Started | First day of development |
|
|
||||||
| **VERIFICATION-COMPLETE.md** | Nix Proof | Confirming package availability |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Key Files Reference
|
|
||||||
|
|
||||||
### Planning Documents
|
|
||||||
```
|
|
||||||
specs/001-reference-board-viewer/
|
|
||||||
├── spec.md Requirements specification
|
|
||||||
├── plan.md Implementation plan (this is the main guide)
|
|
||||||
├── data-model.md Database schema design
|
|
||||||
├── quickstart.md Getting started guide
|
|
||||||
├── tech-research.md Technology evaluation
|
|
||||||
├── nix-package-verification.md Package verification details
|
|
||||||
└── VERIFICATION-COMPLETE.md Verification summary
|
|
||||||
```
|
|
||||||
|
|
||||||
### API & Contracts
|
|
||||||
```
|
|
||||||
specs/001-reference-board-viewer/contracts/
|
|
||||||
└── api.yaml OpenAPI 3.0 specification
|
|
||||||
```
|
|
||||||
|
|
||||||
### Quality Assurance
|
|
||||||
```
|
|
||||||
specs/001-reference-board-viewer/checklists/
|
|
||||||
└── requirements.md Quality validation checklist
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Resources
|
|
||||||
|
|
||||||
### Internal
|
|
||||||
- Main README: ../../README.md
|
|
||||||
- Constitution: ../../.specify/memory/constitution.md
|
|
||||||
- Templates: ../../.specify/templates/
|
|
||||||
|
|
||||||
### External
|
|
||||||
- FastAPI Docs: https://fastapi.tiangolo.com/
|
|
||||||
- Svelte Docs: https://svelte.dev/docs
|
|
||||||
- Konva.js Docs: https://konvajs.org/docs/
|
|
||||||
- Nix Manual: https://nixos.org/manual/nix/stable/
|
|
||||||
- PostgreSQL Docs: https://www.postgresql.org/docs/
|
|
||||||
- MinIO Docs: https://min.io/docs/
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Summary
|
|
||||||
|
|
||||||
✅ **Planning Phase:** COMPLETE
|
|
||||||
✅ **Research:** COMPLETE
|
|
||||||
✅ **Design:** COMPLETE
|
|
||||||
✅ **Contracts:** COMPLETE
|
|
||||||
✅ **Nix Verification:** COMPLETE
|
|
||||||
|
|
||||||
**Status:** ✅ READY FOR WEEK 1 IMPLEMENTATION
|
|
||||||
|
|
||||||
**Next Action:** Follow [quickstart.md](./quickstart.md) to set up development environment and begin Week 1 tasks from [plan.md](./plan.md).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Timeline:** 16 weeks to MVP
|
|
||||||
**Start Date:** Ready now
|
|
||||||
**Team:** 2-3 developers recommended
|
|
||||||
**Deployment:** Self-hosted NixOS with reproducible builds
|
|
||||||
|
|
||||||
🚀 **Let's build this!**
|
|
||||||
|
|
||||||
@@ -1,283 +0,0 @@
|
|||||||
# ✅ TASKS GENERATED: Implementation Ready
|
|
||||||
|
|
||||||
**Date:** 2025-11-02
|
|
||||||
**Feature:** 001-reference-board-viewer
|
|
||||||
**Branch:** 001-reference-board-viewer
|
|
||||||
**Status:** ✅ Ready for Week 1 Execution
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Summary
|
|
||||||
|
|
||||||
Comprehensive task breakdown generated with **331 actionable tasks** organized by user story for independent, parallel implementation.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Generated Artifacts
|
|
||||||
|
|
||||||
### tasks.md Statistics
|
|
||||||
|
|
||||||
- **Total Tasks:** 331
|
|
||||||
- **Phases:** 25 (1 setup + 1 foundational + 18 user stories + 5 cross-cutting)
|
|
||||||
- **User Stories:** 18 (mapped from FR1-FR18 in spec.md)
|
|
||||||
- **Parallelizable Tasks:** 142 tasks marked with [P]
|
|
||||||
- **Average Tasks per User Story:** 18 tasks
|
|
||||||
|
|
||||||
### Task Organization
|
|
||||||
|
|
||||||
**By Priority:**
|
|
||||||
- Critical stories (US1-US6): 126 tasks
|
|
||||||
- High priority stories (US7-US13): 88 tasks
|
|
||||||
- Medium priority stories (US14-US16): 27 tasks
|
|
||||||
- Low priority stories (US17-US18): 14 tasks
|
|
||||||
- Infrastructure/Polish: 76 tasks
|
|
||||||
|
|
||||||
**By Component:**
|
|
||||||
- Backend tasks: ~160 tasks
|
|
||||||
- Frontend tasks: ~145 tasks
|
|
||||||
- Infrastructure: ~26 tasks
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## User Story Mapping
|
|
||||||
|
|
||||||
Each functional requirement from spec.md mapped to user story:
|
|
||||||
|
|
||||||
| Story | Requirement | Priority | Tasks | Week |
|
|
||||||
|-------|-------------|----------|-------|------|
|
|
||||||
| US1 | FR1: Authentication | Critical | 20 | 2 |
|
|
||||||
| US2 | FR2: Board Management | Critical | 20 | 3 |
|
|
||||||
| US3 | FR4: Image Upload | Critical | 24 | 4 |
|
|
||||||
| US4 | FR12: Canvas Navigation | Critical | 11 | 5 |
|
|
||||||
| US5 | FR5: Image Positioning | Critical | 19 | 5-6 |
|
|
||||||
| US6 | FR8: Transformations | Critical | 12 | 6 |
|
|
||||||
| US7 | FR9: Multi-Selection | High | 11 | 7 |
|
|
||||||
| US8 | FR10: Clipboard Operations | High | 10 | 7 |
|
|
||||||
| US9 | FR6: Alignment & Distribution | High | 9 | 10 |
|
|
||||||
| US10 | FR7: Grouping & Annotations | High | 17 | 9 |
|
|
||||||
| US11 | FR3: Board Sharing | High | 19 | 11 |
|
|
||||||
| US12 | FR15: Export & Download | High | 12 | 12 |
|
|
||||||
| US13 | FR16: Adaptive Quality | High | 10 | 13 |
|
|
||||||
| US14 | FR17: Image Library & Reuse | Medium | 12 | 14 |
|
|
||||||
| US15 | FR11: Command Palette | Medium | 7 | 14 |
|
|
||||||
| US16 | FR13: Focus Mode | Medium | 8 | 14 |
|
|
||||||
| US17 | FR14: Slideshow Mode | Low | 7 | 14 |
|
|
||||||
| US18 | FR18: Auto-Arrange | Low | 7 | 14 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task Format Validation ✅
|
|
||||||
|
|
||||||
All 331 tasks follow the required format:
|
|
||||||
|
|
||||||
```
|
|
||||||
- [ ] [T###] [P?] [US#?] Description with file path
|
|
||||||
```
|
|
||||||
|
|
||||||
**Examples:**
|
|
||||||
```
|
|
||||||
✅ - [ ] T036 [P] [US1] Create User model in backend/app/database/models/user.py
|
|
||||||
✅ - [ ] T100 [US4] Initialize Konva.js Stage in frontend/src/lib/canvas/Stage.svelte
|
|
||||||
✅ - [ ] T163 [US9] Implement align top/bottom in frontend/src/lib/canvas/operations/align.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
**Validation Results:**
|
|
||||||
- ✅ All tasks have checkbox `- [ ]`
|
|
||||||
- ✅ All tasks have sequential ID (T001-T331)
|
|
||||||
- ✅ Parallelizable tasks marked with [P]
|
|
||||||
- ✅ User story tasks have [US#] label
|
|
||||||
- ✅ All tasks have specific file paths
|
|
||||||
- ✅ All tasks are actionable (clear description)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Parallel Execution Opportunities
|
|
||||||
|
|
||||||
### Phase 1 (Setup): 13 Parallel Tasks
|
|
||||||
Tasks T002-T020 (excluding sequential dependencies) can run simultaneously.
|
|
||||||
|
|
||||||
**Example Team Split:**
|
|
||||||
- Developer 1: Nix config (T002, T003, T004, T009, T317, T318)
|
|
||||||
- Developer 2: Backend setup (T005, T007, T011, T013, T015, T017, T018)
|
|
||||||
- Developer 3: Frontend setup (T006, T008, T012, T014, T016)
|
|
||||||
|
|
||||||
### Phase 2 (Foundational): 10 Parallel Tasks
|
|
||||||
Tasks T021-T035 - most can run in parallel after T021-T024 complete.
|
|
||||||
|
|
||||||
### Phase 3+ (User Stories): Full Parallelization
|
|
||||||
Each user story is independent after foundational phase:
|
|
||||||
|
|
||||||
**Parallel Story Development (Example Week 9-12):**
|
|
||||||
- Team A: US9 (Alignment) + US12 (Export)
|
|
||||||
- Team B: US10 (Groups) + US13 (Quality)
|
|
||||||
- Team C: US11 (Sharing)
|
|
||||||
|
|
||||||
All teams work simultaneously on different stories!
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## MVP Scope Recommendation
|
|
||||||
|
|
||||||
For fastest time-to-market, implement in this order:
|
|
||||||
|
|
||||||
### MVP Phase 1 (Weeks 1-8) - 120 Tasks
|
|
||||||
**Deliverable:** Functional reference board app
|
|
||||||
|
|
||||||
- Phase 1-2: Setup (35 tasks)
|
|
||||||
- US1: Authentication (20 tasks)
|
|
||||||
- US2: Board Management (20 tasks)
|
|
||||||
- US3: Image Upload (24 tasks)
|
|
||||||
- US4-US5: Canvas basics (22 tasks)
|
|
||||||
- US6: Transformations (12 tasks)
|
|
||||||
|
|
||||||
**Result:** Users can create boards, upload images, position and transform them.
|
|
||||||
|
|
||||||
### MVP Phase 2 (Weeks 9-12) - 88 Tasks
|
|
||||||
**Deliverable:** Collaboration features
|
|
||||||
|
|
||||||
- US7-US10: Multi-select, clipboard, alignment, groups (47 tasks)
|
|
||||||
- US11: Sharing (19 tasks)
|
|
||||||
- US12: Export (12 tasks)
|
|
||||||
- US13: Adaptive quality (10 tasks)
|
|
||||||
|
|
||||||
**Result:** Full collaboration and export capabilities.
|
|
||||||
|
|
||||||
### Polish Phase (Weeks 13-16) - 123 Tasks
|
|
||||||
**Deliverable:** Production-ready
|
|
||||||
|
|
||||||
- US14-US18: Library, palette, focus, slideshow, arrange (41 tasks)
|
|
||||||
- Performance optimization (10 tasks)
|
|
||||||
- Testing (15 tasks)
|
|
||||||
- Accessibility (13 tasks)
|
|
||||||
- Deployment (23 tasks)
|
|
||||||
- Documentation (21 tasks)
|
|
||||||
|
|
||||||
**Result:** Polished, tested, deployed application.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Independent Test Criteria
|
|
||||||
|
|
||||||
Each user story phase includes independent test criteria that can be verified without other features:
|
|
||||||
|
|
||||||
**Example (US1 - Authentication):**
|
|
||||||
- ✅ Users can register with valid email/password
|
|
||||||
- ✅ Users can login and receive JWT token
|
|
||||||
- ✅ Protected endpoints reject unauthenticated requests
|
|
||||||
- ✅ Password validation enforces complexity rules
|
|
||||||
|
|
||||||
This enables:
|
|
||||||
- Feature flag rollouts (deploy incomplete features, hidden behind flags)
|
|
||||||
- A/B testing individual features
|
|
||||||
- Incremental beta releases
|
|
||||||
- Independent QA validation
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Technology Stack Reference
|
|
||||||
|
|
||||||
**All tasks reference this verified stack:**
|
|
||||||
|
|
||||||
**Frontend:**
|
|
||||||
- Svelte + SvelteKit (framework)
|
|
||||||
- Konva.js (canvas library)
|
|
||||||
- Vite (build tool)
|
|
||||||
- Vitest + Testing Library (testing)
|
|
||||||
|
|
||||||
**Backend:**
|
|
||||||
- FastAPI (web framework)
|
|
||||||
- SQLAlchemy + Alembic (database ORM + migrations)
|
|
||||||
- Pydantic (validation)
|
|
||||||
- Pillow + ImageMagick (image processing)
|
|
||||||
- pytest (testing)
|
|
||||||
|
|
||||||
**Infrastructure:**
|
|
||||||
- PostgreSQL (database)
|
|
||||||
- MinIO (S3-compatible storage)
|
|
||||||
- Nginx (reverse proxy)
|
|
||||||
- Nix (deployment)
|
|
||||||
|
|
||||||
**All verified in nixpkgs** - see VERIFICATION-COMPLETE.md
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Next Actions
|
|
||||||
|
|
||||||
### Immediate (Today)
|
|
||||||
|
|
||||||
1. **Review tasks.md:**
|
|
||||||
```bash
|
|
||||||
cat specs/001-reference-board-viewer/tasks.md
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Understand the format:**
|
|
||||||
- [T###] = Task ID
|
|
||||||
- [P] = Parallelizable
|
|
||||||
- [US#] = User Story label
|
|
||||||
|
|
||||||
3. **Choose approach:**
|
|
||||||
- Full MVP (120 tasks, Weeks 1-8)
|
|
||||||
- OR Complete v1.0 (331 tasks, Weeks 1-16)
|
|
||||||
|
|
||||||
### This Week (Week 1)
|
|
||||||
|
|
||||||
Start with Phase 1 (T001-T020):
|
|
||||||
```bash
|
|
||||||
# T001: Initialize Git structure
|
|
||||||
# T002: Create flake.nix
|
|
||||||
# T003: Update shell.nix
|
|
||||||
# ... follow tasks.md sequentially
|
|
||||||
```
|
|
||||||
|
|
||||||
### Team Organization
|
|
||||||
|
|
||||||
If you have a team:
|
|
||||||
- **Backend Developer:** Focus on backend tasks in each phase
|
|
||||||
- **Frontend Developer:** Focus on frontend tasks in each phase
|
|
||||||
- **Full-Stack:** Can work on any tasks marked [P]
|
|
||||||
|
|
||||||
If solo:
|
|
||||||
- Follow tasks sequentially (T001 → T002 → T003...)
|
|
||||||
- Skip tasks marked [P] in same phase to avoid context switching
|
|
||||||
- Complete one user story fully before moving to next
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Files Created
|
|
||||||
|
|
||||||
```
|
|
||||||
specs/001-reference-board-viewer/
|
|
||||||
├── tasks.md ✅ 331 tasks, 25 phases (THIS FILE)
|
|
||||||
├── plan.md ✅ 16-week implementation plan
|
|
||||||
├── spec.md ✅ 18 functional requirements
|
|
||||||
├── data-model.md ✅ Database schema
|
|
||||||
├── tech-research.md ✅ Technology analysis
|
|
||||||
├── nix-package-verification.md ✅ Package verification
|
|
||||||
├── VERIFICATION-COMPLETE.md ✅ Verification summary
|
|
||||||
├── PLANNING-COMPLETE.md ✅ Planning summary
|
|
||||||
├── TASKS-GENERATED.md ✅ This document
|
|
||||||
├── quickstart.md ✅ Developer guide
|
|
||||||
├── contracts/
|
|
||||||
│ └── api.yaml ✅ OpenAPI 3.0 spec
|
|
||||||
└── checklists/
|
|
||||||
└── requirements.md ✅ Quality validation
|
|
||||||
|
|
||||||
Total: ~6,500 lines of comprehensive planning & task breakdown
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Conclusion
|
|
||||||
|
|
||||||
✅ **Task Generation:** COMPLETE
|
|
||||||
✅ **Format Validation:** PASSED
|
|
||||||
✅ **Dependency Analysis:** MAPPED
|
|
||||||
✅ **Parallel Opportunities:** IDENTIFIED
|
|
||||||
✅ **MVP Scope:** DEFINED
|
|
||||||
|
|
||||||
**Status:** ✅ READY TO BEGIN IMPLEMENTATION
|
|
||||||
|
|
||||||
Start with T001 and work through sequentially, or split among team members using the parallel execution examples!
|
|
||||||
|
|
||||||
🚀 **Let's build this!**
|
|
||||||
|
|
||||||
@@ -1,331 +0,0 @@
|
|||||||
# ✅ NIX PACKAGE VERIFICATION COMPLETE
|
|
||||||
|
|
||||||
**Date:** 2025-11-02
|
|
||||||
**Verification Method:** Direct nixpkgs search + nix-instantiate
|
|
||||||
**Result:** **100% VERIFIED - ALL PACKAGES AVAILABLE**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Summary
|
|
||||||
|
|
||||||
Every component in the recommended technology stack has been verified to exist in nixpkgs or can be built with Nix-native tools. **No workarounds, custom derivations, or external package managers required.**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Backend Packages (Python) - ✅ ALL VERIFIED
|
|
||||||
|
|
||||||
Verified via `nix search nixpkgs` and `nix-instantiate`:
|
|
||||||
|
|
||||||
| Package | nixpkgs Attribute | Verified Command | Status |
|
|
||||||
|---------|-------------------|------------------|--------|
|
|
||||||
| **FastAPI** | `python3Packages.fastapi` | `nix search nixpkgs fastapi` | ✅ v0.115.12 |
|
|
||||||
| **Uvicorn** | `python3Packages.uvicorn` | Found in package list | ✅ Available |
|
|
||||||
| **SQLAlchemy** | `python3Packages.sqlalchemy` | Found in package list | ✅ Available |
|
|
||||||
| **Alembic** | `python3Packages.alembic` | Found in package list | ✅ Available |
|
|
||||||
| **Pydantic** | `python3Packages.pydantic` | Found in package list | ✅ Available |
|
|
||||||
| **python-jose** | `python3Packages.python-jose` | `nix search` confirmed | ✅ Available |
|
|
||||||
| **passlib** | `python3Packages.passlib` | `nix search` confirmed | ✅ Available |
|
|
||||||
| **Pillow** | `python3Packages.pillow` | Found in package list | ✅ Available |
|
|
||||||
| **boto3** | `python3Packages.boto3` | `nix search` confirmed | ✅ Available |
|
|
||||||
| **python-multipart** | `python3Packages.python-multipart` | `nix search` confirmed | ✅ Available |
|
|
||||||
| **httpx** | `python3Packages.httpx` | Found in package list | ✅ Available |
|
|
||||||
| **pytest** | `python3Packages.pytest` | Found in package list | ✅ Available |
|
|
||||||
| **pytest-cov** | `python3Packages.pytest-cov` | Found in package list | ✅ Available |
|
|
||||||
| **pytest-asyncio** | `python3Packages.pytest-asyncio` | Found in package list | ✅ Available |
|
|
||||||
|
|
||||||
**Verification Command:**
|
|
||||||
```bash
|
|
||||||
nix-instantiate --eval -E 'with import <nixpkgs> {}; python3Packages.fastapi.pname'
|
|
||||||
# Output: "fastapi" ✅
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## System Packages - ✅ ALL VERIFIED
|
|
||||||
|
|
||||||
| Package | nixpkgs Attribute | Verified Command | Status |
|
|
||||||
|---------|-------------------|------------------|--------|
|
|
||||||
| **PostgreSQL** | `pkgs.postgresql` | `nix search nixpkgs postgresql` | ✅ Multiple versions |
|
|
||||||
| **Nginx** | `pkgs.nginx` | `nix search nixpkgs nginx` | ✅ Available |
|
|
||||||
| **MinIO** | `pkgs.minio` | `nix search nixpkgs '^minio$'` | ✅ Available |
|
|
||||||
| **ImageMagick** | `pkgs.imagemagick` | `nix search nixpkgs imagemagick` | ✅ Available |
|
|
||||||
| **Node.js** | `pkgs.nodejs` | `nix search nixpkgs nodejs` | ✅ Multiple versions |
|
|
||||||
| **uv** | `pkgs.uv` | Already in your shell.nix | ✅ Available |
|
|
||||||
|
|
||||||
**Verification Command:**
|
|
||||||
```bash
|
|
||||||
nix-instantiate --eval -E 'with import <nixpkgs> {}; [ postgresql.pname nginx.pname imagemagick.pname nodejs.pname ]'
|
|
||||||
# Output: [ "postgresql" "nginx" "imagemagick" "nodejs" ] ✅
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Frontend Packages (npm) - ✅ FULLY SUPPORTED
|
|
||||||
|
|
||||||
**Method:** `buildNpmPackage` (standard Nix tool for npm packages)
|
|
||||||
|
|
||||||
| Package | Managed By | Integration Method | Status |
|
|
||||||
|---------|-----------|-------------------|--------|
|
|
||||||
| **Svelte** | npm | `buildNpmPackage` | ✅ Automatic |
|
|
||||||
| **SvelteKit** | npm | `buildNpmPackage` | ✅ Automatic |
|
|
||||||
| **Konva.js** | npm | `buildNpmPackage` | ✅ Automatic |
|
|
||||||
| **Vite** | npm | `buildNpmPackage` | ✅ Automatic |
|
|
||||||
|
|
||||||
**How it works:**
|
|
||||||
```nix
|
|
||||||
pkgs.buildNpmPackage {
|
|
||||||
pname = "webref-frontend";
|
|
||||||
src = ./frontend;
|
|
||||||
npmDepsHash = "sha256-..."; # Nix computes this
|
|
||||||
# Nix automatically:
|
|
||||||
# 1. Reads package.json
|
|
||||||
# 2. Fetches all npm dependencies
|
|
||||||
# 3. Builds reproducibly
|
|
||||||
# 4. Creates store entry
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**No need for individual nixpkgs entries** - This is the **standard and recommended** approach in the Nix ecosystem.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## NixOS Services - ✅ ALL AVAILABLE
|
|
||||||
|
|
||||||
Verified via [search.nixos.org](https://search.nixos.org) and documentation:
|
|
||||||
|
|
||||||
| Service | NixOS Module | Configuration | Status |
|
|
||||||
|---------|-------------|---------------|--------|
|
|
||||||
| **PostgreSQL** | `services.postgresql` | Full module with options | ✅ Available |
|
|
||||||
| **Nginx** | `services.nginx` | Full module with virtualHosts | ✅ Available |
|
|
||||||
| **MinIO** | `services.minio` | Full module with dataDir, etc | ✅ Available |
|
|
||||||
|
|
||||||
**Example Configuration:**
|
|
||||||
```nix
|
|
||||||
{
|
|
||||||
services.postgresql = {
|
|
||||||
enable = true;
|
|
||||||
package = pkgs.postgresql_16;
|
|
||||||
ensureDatabases = [ "webref" ];
|
|
||||||
};
|
|
||||||
|
|
||||||
services.nginx = {
|
|
||||||
enable = true;
|
|
||||||
virtualHosts."webref.local" = { ... };
|
|
||||||
};
|
|
||||||
|
|
||||||
services.minio = {
|
|
||||||
enable = true;
|
|
||||||
dataDir = "/var/lib/minio";
|
|
||||||
};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
These are **pre-built, maintained NixOS modules** - no custom configuration needed!
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Development Tools - ✅ ALL VERIFIED
|
|
||||||
|
|
||||||
| Tool | nixpkgs Attribute | Purpose | Status |
|
|
||||||
|------|-------------------|---------|--------|
|
|
||||||
| **uv** | `pkgs.uv` | Python package manager (fast) | ✅ In your shell.nix |
|
|
||||||
| **ruff** | `pkgs.ruff` | Python linter | ✅ Available |
|
|
||||||
| **git** | `pkgs.git` | Version control | ✅ Standard |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Build Tools - ✅ VERIFIED
|
|
||||||
|
|
||||||
| Tool | Integration | Purpose | Status |
|
|
||||||
|------|-----------|---------|--------|
|
|
||||||
| **buildPythonApplication** | Native Nix | Build Python apps | ✅ Built-in |
|
|
||||||
| **buildNpmPackage** | Native Nix | Build npm projects | ✅ Built-in |
|
|
||||||
| **mkShell** | Native Nix | Dev environments | ✅ Built-in |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Actual Verification Results
|
|
||||||
|
|
||||||
### Python Packages
|
|
||||||
```bash
|
|
||||||
$ nix search nixpkgs 'python.*alembic|python.*passlib|python.*python-jose|python.*python-multipart'
|
|
||||||
"pname":"python3.12-alembic" ✅
|
|
||||||
"pname":"python3.12-passlib" ✅
|
|
||||||
"pname":"python3.12-python-jose" ✅
|
|
||||||
"pname":"python3.12-python-multipart" ✅
|
|
||||||
"pname":"python3.13-alembic" ✅
|
|
||||||
"pname":"python3.13-passlib" ✅
|
|
||||||
"pname":"python3.13-python-jose" ✅
|
|
||||||
"pname":"python3.13-python-multipart" ✅
|
|
||||||
```
|
|
||||||
|
|
||||||
### System Packages
|
|
||||||
```bash
|
|
||||||
$ nix search nixpkgs '^minio$'
|
|
||||||
legacyPackages.x86_64-linux.minio ✅
|
|
||||||
legacyPackages.x86_64-linux.minio_legacy_fs ✅
|
|
||||||
```
|
|
||||||
|
|
||||||
### FastAPI
|
|
||||||
```bash
|
|
||||||
$ nix search nixpkgs fastapi --json | jq '.[] | select(.pname == "python3.12-fastapi")'
|
|
||||||
{
|
|
||||||
"description": "Web framework for building APIs",
|
|
||||||
"pname": "python3.12-fastapi",
|
|
||||||
"version": "0.115.12"
|
|
||||||
} ✅
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Complete Working shell.nix
|
|
||||||
|
|
||||||
Here's a **tested, working configuration** using only verified packages:
|
|
||||||
|
|
||||||
```nix
|
|
||||||
{ pkgs ? import <nixpkgs> { } }:
|
|
||||||
|
|
||||||
pkgs.mkShell {
|
|
||||||
packages = [
|
|
||||||
# Backend: Python with all verified packages
|
|
||||||
(pkgs.python3.withPackages (ps: [
|
|
||||||
ps.fastapi # ✅ Verified
|
|
||||||
ps.uvicorn # ✅ Verified
|
|
||||||
ps.sqlalchemy # ✅ Verified
|
|
||||||
ps.alembic # ✅ Verified
|
|
||||||
ps.pydantic # ✅ Verified
|
|
||||||
ps.python-jose # ✅ Verified
|
|
||||||
ps.passlib # ✅ Verified
|
|
||||||
ps.pillow # ✅ Verified
|
|
||||||
ps.boto3 # ✅ Verified
|
|
||||||
ps.python-multipart # ✅ Verified
|
|
||||||
ps.httpx # ✅ Verified
|
|
||||||
ps.pytest # ✅ Verified
|
|
||||||
ps.pytest-cov # ✅ Verified
|
|
||||||
ps.pytest-asyncio # ✅ Verified
|
|
||||||
]))
|
|
||||||
|
|
||||||
# Python package manager (already in your shell.nix)
|
|
||||||
pkgs.uv # ✅ Verified
|
|
||||||
|
|
||||||
# Image processing
|
|
||||||
pkgs.imagemagick # ✅ Verified
|
|
||||||
|
|
||||||
# Frontend
|
|
||||||
pkgs.nodejs # ✅ Verified (npm included)
|
|
||||||
|
|
||||||
# Database
|
|
||||||
pkgs.postgresql # ✅ Verified
|
|
||||||
|
|
||||||
# Development
|
|
||||||
pkgs.ruff # ✅ Verified
|
|
||||||
pkgs.git # ✅ Standard
|
|
||||||
];
|
|
||||||
|
|
||||||
shellHook = ''
|
|
||||||
echo "✅ All packages verified and loaded!"
|
|
||||||
echo "Python: $(python --version)"
|
|
||||||
echo "Node: $(node --version)"
|
|
||||||
echo "PostgreSQL client: $(psql --version)"
|
|
||||||
'';
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
You can test this **right now**:
|
|
||||||
```bash
|
|
||||||
nix-shell -p 'python3.withPackages (ps: [ ps.fastapi ps.uvicorn ps.sqlalchemy ])' \
|
|
||||||
-p nodejs -p postgresql -p imagemagick -p uv --run 'echo "✅ Success!"'
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Example flake.nix
|
|
||||||
|
|
||||||
A complete, working Nix flake using verified packages:
|
|
||||||
|
|
||||||
```nix
|
|
||||||
{
|
|
||||||
description = "webref - Reference Board Viewer";
|
|
||||||
|
|
||||||
inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.05";
|
|
||||||
|
|
||||||
outputs = { self, nixpkgs }:
|
|
||||||
let
|
|
||||||
system = "x86_64-linux";
|
|
||||||
pkgs = nixpkgs.legacyPackages.${system};
|
|
||||||
|
|
||||||
# Backend Python packages (all verified ✅)
|
|
||||||
pythonEnv = pkgs.python3.withPackages (ps: [
|
|
||||||
ps.fastapi ps.uvicorn ps.sqlalchemy ps.alembic
|
|
||||||
ps.pydantic ps.python-jose ps.passlib ps.pillow
|
|
||||||
ps.boto3 ps.python-multipart ps.httpx
|
|
||||||
]);
|
|
||||||
|
|
||||||
in {
|
|
||||||
# Development shell
|
|
||||||
devShells.${system}.default = pkgs.mkShell {
|
|
||||||
packages = [
|
|
||||||
pythonEnv
|
|
||||||
pkgs.uv
|
|
||||||
pkgs.nodejs
|
|
||||||
pkgs.imagemagick
|
|
||||||
pkgs.postgresql
|
|
||||||
pkgs.ruff
|
|
||||||
];
|
|
||||||
};
|
|
||||||
|
|
||||||
# NixOS module for deployment
|
|
||||||
nixosModules.default = { config, lib, ... }: {
|
|
||||||
options.services.webref.enable = lib.mkEnableOption "webref";
|
|
||||||
|
|
||||||
config = lib.mkIf config.services.webref.enable {
|
|
||||||
# All these services are verified ✅
|
|
||||||
services.postgresql.enable = true;
|
|
||||||
services.minio.enable = true;
|
|
||||||
services.nginx.enable = true;
|
|
||||||
};
|
|
||||||
};
|
|
||||||
};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Conclusion
|
|
||||||
|
|
||||||
### ✅ Verification Status: 100% COMPLETE
|
|
||||||
|
|
||||||
**Every single component** in the recommended stack exists in nixpkgs or is built using standard Nix tools:
|
|
||||||
|
|
||||||
1. ✅ **Backend (Python):** All 14 packages verified in `python3Packages.*`
|
|
||||||
2. ✅ **System Services:** PostgreSQL, Nginx, MinIO all verified
|
|
||||||
3. ✅ **Frontend (npm):** Handled by standard `buildNpmPackage`
|
|
||||||
4. ✅ **Image Processing:** Pillow, ImageMagick verified
|
|
||||||
5. ✅ **Development Tools:** uv, ruff, git all verified
|
|
||||||
6. ✅ **NixOS Modules:** services.postgresql, services.nginx, services.minio all available
|
|
||||||
|
|
||||||
### No Issues Found
|
|
||||||
|
|
||||||
- ❌ No packages missing from nixpkgs
|
|
||||||
- ❌ No custom derivations needed
|
|
||||||
- ❌ No workarounds required
|
|
||||||
- ❌ No external package managers needed (beyond npm via buildNpmPackage)
|
|
||||||
|
|
||||||
### Your Non-Negotiable Requirement: ✅ MET
|
|
||||||
|
|
||||||
**"Must be deployable and compilable by Nix"** → **Fully satisfied.**
|
|
||||||
|
|
||||||
The recommended stack (Svelte + Konva + FastAPI + PostgreSQL + MinIO) is:
|
|
||||||
- **100% reproducible** with Nix
|
|
||||||
- **Battle-tested** in production NixOS environments
|
|
||||||
- **Standard** in the Nix ecosystem
|
|
||||||
- **Well-maintained** by nixpkgs contributors
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Next Action
|
|
||||||
|
|
||||||
You can confidently **proceed with implementation** using the recommended stack. Everything is verified and ready to go!
|
|
||||||
|
|
||||||
See the complete [tech-research.md](./tech-research.md) for detailed analysis and [plan.md](./plan.md) for the 16-week implementation timeline.
|
|
||||||
|
|
||||||
@@ -89,15 +89,15 @@ Implementation tasks for the Reference Board Viewer, organized by user story (fu
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Phase 3: User Authentication (FR1 - Critical) (Week 2)
|
## Phase 3: User Authentication (FR1 - Critical) (Week 2) ✅ COMPLETE
|
||||||
|
|
||||||
**User Story:** Users must be able to create accounts, log in, and manage their profile
|
**User Story:** Users must be able to create accounts, log in, and manage their profile
|
||||||
|
|
||||||
**Independent Test Criteria:**
|
**Independent Test Criteria:**
|
||||||
- [ ] Users can register with valid email/password
|
- [X] Users can register with valid email/password
|
||||||
- [ ] Users can login and receive JWT token
|
- [X] Users can login and receive JWT token
|
||||||
- [ ] Protected endpoints reject unauthenticated requests
|
- [X] Protected endpoints reject unauthenticated requests
|
||||||
- [ ] Password validation enforces complexity rules
|
- [X] Password validation enforces complexity rules
|
||||||
|
|
||||||
**Backend Tasks:**
|
**Backend Tasks:**
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user