Update project configuration and documentation for Reference Board Viewer. Add .direnv support for environment management, enhance README with quick start instructions, and update flake.nix with additional dependencies including pydantic-settings and bcrypt. Introduce quick-start.sh and test-auth.sh scripts for streamlined setup and authentication testing. Remove obsolete planning and task documents to clean up the repository.
This commit is contained in:
Danilo Reyes
@@ -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/memory/
|
||||
|
||||
.direnv/
|
||||
27
README.md
27
README.md
@@ -27,13 +27,38 @@ direnv allow # .envrc already configured
|
||||
```
|
||||
|
||||
**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
|
||||
- PostgreSQL client tools
|
||||
- MinIO client
|
||||
- Ruff (Python linter/formatter)
|
||||
- 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
|
||||
|
||||
```
|
||||
|
||||
@@ -47,7 +47,7 @@ def register_user(user_data: UserCreate, db: Session = Depends(get_db)):
|
||||
# Create user
|
||||
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)
|
||||
@@ -91,7 +91,7 @@ def login_user(login_data: UserLogin, db: Session = Depends(get_db)):
|
||||
return TokenResponse(
|
||||
access_token=access_token,
|
||||
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:
|
||||
Current user information
|
||||
"""
|
||||
return UserResponse.from_orm(current_user)
|
||||
return UserResponse.model_validate(current_user)
|
||||
|
||||
|
||||
@@ -18,9 +18,13 @@
|
||||
sqlalchemy
|
||||
alembic
|
||||
pydantic
|
||||
pydantic-settings # Settings management
|
||||
psycopg2 # PostgreSQL driver
|
||||
# Auth & Security
|
||||
python-jose
|
||||
passlib
|
||||
bcrypt # Password hashing backend for passlib
|
||||
email-validator # Email validation for pydantic
|
||||
# Image processing
|
||||
pillow
|
||||
# Storage
|
||||
|
||||
@@ -42,7 +42,7 @@
|
||||
}, 1500);
|
||||
} catch (err) {
|
||||
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 {
|
||||
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
|
||||
|
||||
**Independent Test Criteria:**
|
||||
- [ ] Users can register with valid email/password
|
||||
- [ ] Users can login and receive JWT token
|
||||
- [ ] Protected endpoints reject unauthenticated requests
|
||||
- [ ] Password validation enforces complexity rules
|
||||
- [X] Users can register with valid email/password
|
||||
- [X] Users can login and receive JWT token
|
||||
- [X] Protected endpoints reject unauthenticated requests
|
||||
- [X] Password validation enforces complexity rules
|
||||
|
||||
**Backend Tasks:**
|
||||
|
||||
|
||||
Reference in New Issue
Block a user