Add comprehensive specifications and planning documents for Reference Board Viewer application. Include detailed data model, API contracts, quickstart guide, and task breakdown for implementation. Ensure all artifacts are aligned with project objectives and constitutional principles.
This commit is contained in:
Danilo Reyes
58
.cursor/rules/specify-rules.mdc
Normal file
58
.cursor/rules/specify-rules.mdc
Normal file
@@ -0,0 +1,58 @@
|
|||||||
|
# webref Development Guidelines
|
||||||
|
|
||||||
|
Auto-generated from all feature plans. Last updated: 2025-11-01
|
||||||
|
|
||||||
|
## Constitutional Principles
|
||||||
|
|
||||||
|
This project follows a formal constitution (`.specify/memory/constitution.md`). All development work MUST align with these principles:
|
||||||
|
|
||||||
|
1. **Code Quality & Maintainability** - Clear, maintainable code with proper typing
|
||||||
|
2. **Testing Discipline** - ≥80% coverage, automated testing required
|
||||||
|
3. **User Experience Consistency** - Intuitive, accessible interfaces
|
||||||
|
4. **Performance & Efficiency** - Performance-first design with bounded resources
|
||||||
|
|
||||||
|
Reference the full constitution for detailed requirements and enforcement mechanisms.
|
||||||
|
|
||||||
|
## Active Technologies
|
||||||
|
|
||||||
|
- (001-reference-board-viewer)
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
```text
|
||||||
|
src/
|
||||||
|
tests/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
|
||||||
|
# Add commands for
|
||||||
|
|
||||||
|
## Code Style
|
||||||
|
|
||||||
|
: Follow standard conventions
|
||||||
|
|
||||||
|
### Constitutional Requirements
|
||||||
|
|
||||||
|
All code MUST meet these standards (per Principle 1):
|
||||||
|
- Linter passing (zero errors/warnings)
|
||||||
|
- Type hints on all public APIs
|
||||||
|
- Clear single responsibilities (SRP)
|
||||||
|
- Explicit constants (no magic numbers)
|
||||||
|
- Comments explaining "why" not "what"
|
||||||
|
|
||||||
|
## Testing Standards
|
||||||
|
|
||||||
|
Per Constitutional Principle 2:
|
||||||
|
- Minimum 80% test coverage required
|
||||||
|
- Unit tests for all public functions
|
||||||
|
- Integration tests for component interactions
|
||||||
|
- Edge cases and error paths explicitly tested
|
||||||
|
- Tests are deterministic, isolated, and fast (<1s unit, <10s integration)
|
||||||
|
|
||||||
|
## Recent Changes
|
||||||
|
|
||||||
|
- 001-reference-board-viewer: Added
|
||||||
|
|
||||||
|
<!-- MANUAL ADDITIONS START -->
|
||||||
|
<!-- MANUAL ADDITIONS END -->
|
||||||
391
specs/001-reference-board-viewer/PLANNING-COMPLETE.md
Normal file
391
specs/001-reference-board-viewer/PLANNING-COMPLETE.md
Normal file
@@ -0,0 +1,391 @@
|
|||||||
|
# ✅ 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!**
|
||||||
|
|
||||||
283
specs/001-reference-board-viewer/TASKS-GENERATED.md
Normal file
283
specs/001-reference-board-viewer/TASKS-GENERATED.md
Normal file
@@ -0,0 +1,283 @@
|
|||||||
|
# ✅ 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!**
|
||||||
|
|
||||||
921
specs/001-reference-board-viewer/contracts/api.yaml
Normal file
921
specs/001-reference-board-viewer/contracts/api.yaml
Normal file
@@ -0,0 +1,921 @@
|
|||||||
|
openapi: 3.0.3
|
||||||
|
info:
|
||||||
|
title: Reference Board Viewer API
|
||||||
|
description: |
|
||||||
|
REST API for the Reference Board Viewer application - a web-based tool for artists
|
||||||
|
to collect, organize, and manipulate visual reference images.
|
||||||
|
version: 1.0.0
|
||||||
|
contact:
|
||||||
|
name: API Support
|
||||||
|
servers:
|
||||||
|
- url: http://localhost:8000/api/v1
|
||||||
|
description: Development server
|
||||||
|
- url: https://webref.example.com/api/v1
|
||||||
|
description: Production server
|
||||||
|
|
||||||
|
tags:
|
||||||
|
- name: Auth
|
||||||
|
description: Authentication and user management
|
||||||
|
- name: Boards
|
||||||
|
description: Board operations
|
||||||
|
- name: Images
|
||||||
|
description: Image upload and management
|
||||||
|
- name: Canvas
|
||||||
|
description: Canvas operations (positioning, transformations)
|
||||||
|
- name: Groups
|
||||||
|
description: Image grouping
|
||||||
|
- name: Sharing
|
||||||
|
description: Board sharing
|
||||||
|
|
||||||
|
security:
|
||||||
|
- BearerAuth: []
|
||||||
|
|
||||||
|
paths:
|
||||||
|
# ==================== Authentication ====================
|
||||||
|
/auth/register:
|
||||||
|
post:
|
||||||
|
tags: [Auth]
|
||||||
|
summary: Register new user
|
||||||
|
security: []
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
required: [email, password]
|
||||||
|
properties:
|
||||||
|
email:
|
||||||
|
type: string
|
||||||
|
format: email
|
||||||
|
example: user@example.com
|
||||||
|
password:
|
||||||
|
type: string
|
||||||
|
minLength: 8
|
||||||
|
example: SecurePass123
|
||||||
|
responses:
|
||||||
|
'201':
|
||||||
|
description: User registered successfully
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/UserResponse'
|
||||||
|
'400':
|
||||||
|
$ref: '#/components/responses/BadRequest'
|
||||||
|
'409':
|
||||||
|
$ref: '#/components/responses/Conflict'
|
||||||
|
|
||||||
|
/auth/login:
|
||||||
|
post:
|
||||||
|
tags: [Auth]
|
||||||
|
summary: Login user
|
||||||
|
security: []
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
required: [email, password]
|
||||||
|
properties:
|
||||||
|
email:
|
||||||
|
type: string
|
||||||
|
format: email
|
||||||
|
password:
|
||||||
|
type: string
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Login successful
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
access_token:
|
||||||
|
type: string
|
||||||
|
example: eyJhbGciOiJIUzI1NiIs...
|
||||||
|
token_type:
|
||||||
|
type: string
|
||||||
|
example: bearer
|
||||||
|
user:
|
||||||
|
$ref: '#/components/schemas/UserResponse'
|
||||||
|
'401':
|
||||||
|
$ref: '#/components/responses/Unauthorized'
|
||||||
|
|
||||||
|
/auth/me:
|
||||||
|
get:
|
||||||
|
tags: [Auth]
|
||||||
|
summary: Get current user
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Current user details
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/UserResponse'
|
||||||
|
'401':
|
||||||
|
$ref: '#/components/responses/Unauthorized'
|
||||||
|
|
||||||
|
# ==================== Boards ====================
|
||||||
|
/boards:
|
||||||
|
get:
|
||||||
|
tags: [Boards]
|
||||||
|
summary: List user's boards
|
||||||
|
parameters:
|
||||||
|
- name: limit
|
||||||
|
in: query
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
default: 50
|
||||||
|
maximum: 100
|
||||||
|
- name: offset
|
||||||
|
in: query
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
default: 0
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: List of boards
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
boards:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/BoardSummary'
|
||||||
|
total:
|
||||||
|
type: integer
|
||||||
|
limit:
|
||||||
|
type: integer
|
||||||
|
offset:
|
||||||
|
type: integer
|
||||||
|
|
||||||
|
post:
|
||||||
|
tags: [Boards]
|
||||||
|
summary: Create new board
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
required: [title]
|
||||||
|
properties:
|
||||||
|
title:
|
||||||
|
type: string
|
||||||
|
minLength: 1
|
||||||
|
maxLength: 255
|
||||||
|
example: Character Design References
|
||||||
|
description:
|
||||||
|
type: string
|
||||||
|
example: References for fantasy knight character
|
||||||
|
responses:
|
||||||
|
'201':
|
||||||
|
description: Board created
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/BoardDetail'
|
||||||
|
'400':
|
||||||
|
$ref: '#/components/responses/BadRequest'
|
||||||
|
|
||||||
|
/boards/{board_id}:
|
||||||
|
parameters:
|
||||||
|
- $ref: '#/components/parameters/BoardId'
|
||||||
|
|
||||||
|
get:
|
||||||
|
tags: [Boards]
|
||||||
|
summary: Get board details
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Board details with all images
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/BoardDetail'
|
||||||
|
'404':
|
||||||
|
$ref: '#/components/responses/NotFound'
|
||||||
|
|
||||||
|
patch:
|
||||||
|
tags: [Boards]
|
||||||
|
summary: Update board
|
||||||
|
requestBody:
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
title:
|
||||||
|
type: string
|
||||||
|
description:
|
||||||
|
type: string
|
||||||
|
viewport_state:
|
||||||
|
$ref: '#/components/schemas/ViewportState'
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Board updated
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/BoardDetail'
|
||||||
|
'404':
|
||||||
|
$ref: '#/components/responses/NotFound'
|
||||||
|
|
||||||
|
delete:
|
||||||
|
tags: [Boards]
|
||||||
|
summary: Delete board
|
||||||
|
responses:
|
||||||
|
'204':
|
||||||
|
description: Board deleted
|
||||||
|
'404':
|
||||||
|
$ref: '#/components/responses/NotFound'
|
||||||
|
|
||||||
|
# ==================== Images ====================
|
||||||
|
/boards/{board_id}/images:
|
||||||
|
parameters:
|
||||||
|
- $ref: '#/components/parameters/BoardId'
|
||||||
|
|
||||||
|
post:
|
||||||
|
tags: [Images]
|
||||||
|
summary: Upload image(s) to board
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
multipart/form-data:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
required: [files]
|
||||||
|
properties:
|
||||||
|
files:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
format: binary
|
||||||
|
maxItems: 50
|
||||||
|
position:
|
||||||
|
type: string
|
||||||
|
description: JSON string of default position
|
||||||
|
example: '{"x": 0, "y": 0}'
|
||||||
|
responses:
|
||||||
|
'201':
|
||||||
|
description: Images uploaded
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
images:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/BoardImage'
|
||||||
|
'400':
|
||||||
|
$ref: '#/components/responses/BadRequest'
|
||||||
|
'413':
|
||||||
|
description: File too large
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Error'
|
||||||
|
|
||||||
|
/boards/{board_id}/images/{image_id}:
|
||||||
|
parameters:
|
||||||
|
- $ref: '#/components/parameters/BoardId'
|
||||||
|
- $ref: '#/components/parameters/ImageId'
|
||||||
|
|
||||||
|
patch:
|
||||||
|
tags: [Canvas]
|
||||||
|
summary: Update image position/transformations
|
||||||
|
requestBody:
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
position:
|
||||||
|
$ref: '#/components/schemas/Position'
|
||||||
|
transformations:
|
||||||
|
$ref: '#/components/schemas/Transformations'
|
||||||
|
z_order:
|
||||||
|
type: integer
|
||||||
|
group_id:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
nullable: true
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Image updated
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/BoardImage'
|
||||||
|
'404':
|
||||||
|
$ref: '#/components/responses/NotFound'
|
||||||
|
|
||||||
|
delete:
|
||||||
|
tags: [Canvas]
|
||||||
|
summary: Remove image from board
|
||||||
|
responses:
|
||||||
|
'204':
|
||||||
|
description: Image removed from board
|
||||||
|
'404':
|
||||||
|
$ref: '#/components/responses/NotFound'
|
||||||
|
|
||||||
|
/boards/{board_id}/images/bulk:
|
||||||
|
parameters:
|
||||||
|
- $ref: '#/components/parameters/BoardId'
|
||||||
|
|
||||||
|
patch:
|
||||||
|
tags: [Canvas]
|
||||||
|
summary: Bulk update multiple images
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
required: [image_ids, updates]
|
||||||
|
properties:
|
||||||
|
image_ids:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
updates:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
position_delta:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
dx:
|
||||||
|
type: number
|
||||||
|
dy:
|
||||||
|
type: number
|
||||||
|
transformations:
|
||||||
|
$ref: '#/components/schemas/Transformations'
|
||||||
|
z_order_delta:
|
||||||
|
type: integer
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Images updated
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
updated_count:
|
||||||
|
type: integer
|
||||||
|
'400':
|
||||||
|
$ref: '#/components/responses/BadRequest'
|
||||||
|
|
||||||
|
# ==================== Groups ====================
|
||||||
|
/boards/{board_id}/groups:
|
||||||
|
parameters:
|
||||||
|
- $ref: '#/components/parameters/BoardId'
|
||||||
|
|
||||||
|
get:
|
||||||
|
tags: [Groups]
|
||||||
|
summary: List board groups
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: List of groups
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/Group'
|
||||||
|
|
||||||
|
post:
|
||||||
|
tags: [Groups]
|
||||||
|
summary: Create group
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
required: [name, color, image_ids]
|
||||||
|
properties:
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
example: Armor References
|
||||||
|
color:
|
||||||
|
type: string
|
||||||
|
pattern: '^#[0-9A-Fa-f]{6}$'
|
||||||
|
example: '#FF5733'
|
||||||
|
annotation:
|
||||||
|
type: string
|
||||||
|
example: Blue plate armor designs
|
||||||
|
image_ids:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
responses:
|
||||||
|
'201':
|
||||||
|
description: Group created
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Group'
|
||||||
|
'400':
|
||||||
|
$ref: '#/components/responses/BadRequest'
|
||||||
|
|
||||||
|
/boards/{board_id}/groups/{group_id}:
|
||||||
|
parameters:
|
||||||
|
- $ref: '#/components/parameters/BoardId'
|
||||||
|
- $ref: '#/components/parameters/GroupId'
|
||||||
|
|
||||||
|
patch:
|
||||||
|
tags: [Groups]
|
||||||
|
summary: Update group
|
||||||
|
requestBody:
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
color:
|
||||||
|
type: string
|
||||||
|
annotation:
|
||||||
|
type: string
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Group updated
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Group'
|
||||||
|
|
||||||
|
delete:
|
||||||
|
tags: [Groups]
|
||||||
|
summary: Delete group (ungroups images)
|
||||||
|
responses:
|
||||||
|
'204':
|
||||||
|
description: Group deleted
|
||||||
|
'404':
|
||||||
|
$ref: '#/components/responses/NotFound'
|
||||||
|
|
||||||
|
# ==================== Sharing ====================
|
||||||
|
/boards/{board_id}/share-links:
|
||||||
|
parameters:
|
||||||
|
- $ref: '#/components/parameters/BoardId'
|
||||||
|
|
||||||
|
get:
|
||||||
|
tags: [Sharing]
|
||||||
|
summary: List board share links
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: List of share links
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/ShareLink'
|
||||||
|
|
||||||
|
post:
|
||||||
|
tags: [Sharing]
|
||||||
|
summary: Create share link
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
required: [permission_level]
|
||||||
|
properties:
|
||||||
|
permission_level:
|
||||||
|
type: string
|
||||||
|
enum: [view-only, view-comment]
|
||||||
|
expires_at:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
nullable: true
|
||||||
|
responses:
|
||||||
|
'201':
|
||||||
|
description: Share link created
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ShareLink'
|
||||||
|
|
||||||
|
/boards/{board_id}/share-links/{link_id}:
|
||||||
|
parameters:
|
||||||
|
- $ref: '#/components/parameters/BoardId'
|
||||||
|
- name: link_id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
|
||||||
|
delete:
|
||||||
|
tags: [Sharing]
|
||||||
|
summary: Revoke share link
|
||||||
|
responses:
|
||||||
|
'204':
|
||||||
|
description: Share link revoked
|
||||||
|
'404':
|
||||||
|
$ref: '#/components/responses/NotFound'
|
||||||
|
|
||||||
|
/shared/{token}:
|
||||||
|
parameters:
|
||||||
|
- name: token
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
|
||||||
|
get:
|
||||||
|
tags: [Sharing]
|
||||||
|
summary: Access shared board
|
||||||
|
security: []
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Shared board details
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
board:
|
||||||
|
$ref: '#/components/schemas/BoardDetail'
|
||||||
|
permission_level:
|
||||||
|
type: string
|
||||||
|
enum: [view-only, view-comment]
|
||||||
|
'404':
|
||||||
|
description: Invalid or expired token
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Error'
|
||||||
|
|
||||||
|
# ==================== Export ====================
|
||||||
|
/boards/{board_id}/export:
|
||||||
|
parameters:
|
||||||
|
- $ref: '#/components/parameters/BoardId'
|
||||||
|
|
||||||
|
post:
|
||||||
|
tags: [Boards]
|
||||||
|
summary: Export board
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
required: [format]
|
||||||
|
properties:
|
||||||
|
format:
|
||||||
|
type: string
|
||||||
|
enum: [zip, composite]
|
||||||
|
resolution:
|
||||||
|
type: integer
|
||||||
|
enum: [1, 2, 4]
|
||||||
|
default: 1
|
||||||
|
description: Resolution multiplier (for composite)
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Export file
|
||||||
|
content:
|
||||||
|
application/zip:
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
format: binary
|
||||||
|
image/png:
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
format: binary
|
||||||
|
'400':
|
||||||
|
$ref: '#/components/responses/BadRequest'
|
||||||
|
|
||||||
|
# ==================== Image Library ====================
|
||||||
|
/library/images:
|
||||||
|
get:
|
||||||
|
tags: [Images]
|
||||||
|
summary: List user's image library
|
||||||
|
parameters:
|
||||||
|
- name: search
|
||||||
|
in: query
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
- name: limit
|
||||||
|
in: query
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
default: 50
|
||||||
|
- name: offset
|
||||||
|
in: query
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
default: 0
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Image library
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
images:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/ImageMetadata'
|
||||||
|
total:
|
||||||
|
type: integer
|
||||||
|
|
||||||
|
# ==================== Components ====================
|
||||||
|
components:
|
||||||
|
securitySchemes:
|
||||||
|
BearerAuth:
|
||||||
|
type: http
|
||||||
|
scheme: bearer
|
||||||
|
bearerFormat: JWT
|
||||||
|
|
||||||
|
parameters:
|
||||||
|
BoardId:
|
||||||
|
name: board_id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
|
||||||
|
ImageId:
|
||||||
|
name: image_id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
|
||||||
|
GroupId:
|
||||||
|
name: group_id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
|
||||||
|
schemas:
|
||||||
|
UserResponse:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
email:
|
||||||
|
type: string
|
||||||
|
format: email
|
||||||
|
created_at:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
|
||||||
|
BoardSummary:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
title:
|
||||||
|
type: string
|
||||||
|
description:
|
||||||
|
type: string
|
||||||
|
nullable: true
|
||||||
|
image_count:
|
||||||
|
type: integer
|
||||||
|
thumbnail_url:
|
||||||
|
type: string
|
||||||
|
nullable: true
|
||||||
|
created_at:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
updated_at:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
|
||||||
|
BoardDetail:
|
||||||
|
allOf:
|
||||||
|
- $ref: '#/components/schemas/BoardSummary'
|
||||||
|
- type: object
|
||||||
|
properties:
|
||||||
|
viewport_state:
|
||||||
|
$ref: '#/components/schemas/ViewportState'
|
||||||
|
images:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/BoardImage'
|
||||||
|
groups:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/Group'
|
||||||
|
|
||||||
|
ViewportState:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
x:
|
||||||
|
type: number
|
||||||
|
example: 0
|
||||||
|
y:
|
||||||
|
type: number
|
||||||
|
example: 0
|
||||||
|
zoom:
|
||||||
|
type: number
|
||||||
|
minimum: 0.1
|
||||||
|
maximum: 5.0
|
||||||
|
example: 1.0
|
||||||
|
rotation:
|
||||||
|
type: number
|
||||||
|
minimum: 0
|
||||||
|
maximum: 360
|
||||||
|
example: 0
|
||||||
|
|
||||||
|
ImageMetadata:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
filename:
|
||||||
|
type: string
|
||||||
|
file_size:
|
||||||
|
type: integer
|
||||||
|
mime_type:
|
||||||
|
type: string
|
||||||
|
width:
|
||||||
|
type: integer
|
||||||
|
height:
|
||||||
|
type: integer
|
||||||
|
thumbnail_urls:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
low:
|
||||||
|
type: string
|
||||||
|
medium:
|
||||||
|
type: string
|
||||||
|
high:
|
||||||
|
type: string
|
||||||
|
created_at:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
reference_count:
|
||||||
|
type: integer
|
||||||
|
|
||||||
|
BoardImage:
|
||||||
|
allOf:
|
||||||
|
- $ref: '#/components/schemas/ImageMetadata'
|
||||||
|
- type: object
|
||||||
|
properties:
|
||||||
|
position:
|
||||||
|
$ref: '#/components/schemas/Position'
|
||||||
|
transformations:
|
||||||
|
$ref: '#/components/schemas/Transformations'
|
||||||
|
z_order:
|
||||||
|
type: integer
|
||||||
|
group_id:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
nullable: true
|
||||||
|
|
||||||
|
Position:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
x:
|
||||||
|
type: number
|
||||||
|
y:
|
||||||
|
type: number
|
||||||
|
|
||||||
|
Transformations:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
scale:
|
||||||
|
type: number
|
||||||
|
minimum: 0.01
|
||||||
|
maximum: 10.0
|
||||||
|
default: 1.0
|
||||||
|
rotation:
|
||||||
|
type: number
|
||||||
|
minimum: 0
|
||||||
|
maximum: 360
|
||||||
|
default: 0
|
||||||
|
opacity:
|
||||||
|
type: number
|
||||||
|
minimum: 0.0
|
||||||
|
maximum: 1.0
|
||||||
|
default: 1.0
|
||||||
|
flipped_h:
|
||||||
|
type: boolean
|
||||||
|
default: false
|
||||||
|
flipped_v:
|
||||||
|
type: boolean
|
||||||
|
default: false
|
||||||
|
crop:
|
||||||
|
type: object
|
||||||
|
nullable: true
|
||||||
|
properties:
|
||||||
|
x:
|
||||||
|
type: number
|
||||||
|
y:
|
||||||
|
type: number
|
||||||
|
width:
|
||||||
|
type: number
|
||||||
|
height:
|
||||||
|
type: number
|
||||||
|
greyscale:
|
||||||
|
type: boolean
|
||||||
|
default: false
|
||||||
|
|
||||||
|
Group:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
color:
|
||||||
|
type: string
|
||||||
|
pattern: '^#[0-9A-Fa-f]{6}$'
|
||||||
|
annotation:
|
||||||
|
type: string
|
||||||
|
nullable: true
|
||||||
|
member_count:
|
||||||
|
type: integer
|
||||||
|
created_at:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
|
||||||
|
ShareLink:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
token:
|
||||||
|
type: string
|
||||||
|
permission_level:
|
||||||
|
type: string
|
||||||
|
enum: [view-only, view-comment]
|
||||||
|
url:
|
||||||
|
type: string
|
||||||
|
example: https://webref.example.com/shared/abc123...
|
||||||
|
created_at:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
expires_at:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
nullable: true
|
||||||
|
access_count:
|
||||||
|
type: integer
|
||||||
|
is_revoked:
|
||||||
|
type: boolean
|
||||||
|
|
||||||
|
Error:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
error:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
message:
|
||||||
|
type: string
|
||||||
|
code:
|
||||||
|
type: string
|
||||||
|
details:
|
||||||
|
type: object
|
||||||
|
nullable: true
|
||||||
|
|
||||||
|
responses:
|
||||||
|
BadRequest:
|
||||||
|
description: Bad request
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Error'
|
||||||
|
|
||||||
|
Unauthorized:
|
||||||
|
description: Unauthorized
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Error'
|
||||||
|
|
||||||
|
NotFound:
|
||||||
|
description: Resource not found
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Error'
|
||||||
|
|
||||||
|
Conflict:
|
||||||
|
description: Resource conflict
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Error'
|
||||||
|
|
||||||
610
specs/001-reference-board-viewer/data-model.md
Normal file
610
specs/001-reference-board-viewer/data-model.md
Normal file
@@ -0,0 +1,610 @@
|
|||||||
|
# Data Model: Reference Board Viewer
|
||||||
|
|
||||||
|
**Created:** 2025-11-02
|
||||||
|
**Status:** Active
|
||||||
|
**Version:** 1.0.0
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
This document defines the data model for the Reference Board Viewer application, including entities, relationships, validation rules, and state transitions.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Entity Relationship Diagram
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────┐ ┌──────────┐ ┌────────────┐
|
||||||
|
│ User │────1:N──│ Board │────M:N──│ Image │
|
||||||
|
└─────────┘ └──────────┘ └────────────┘
|
||||||
|
│ │
|
||||||
|
│ │
|
||||||
|
1:N 1:N
|
||||||
|
│ │
|
||||||
|
┌──────────┐ ┌─────────────┐
|
||||||
|
│ Group │ │ BoardImage │
|
||||||
|
└──────────┘ └─────────────┘
|
||||||
|
│
|
||||||
|
│
|
||||||
|
┌─────────────┐
|
||||||
|
│ ShareLink │
|
||||||
|
└─────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Core Entities
|
||||||
|
|
||||||
|
### User
|
||||||
|
|
||||||
|
**Purpose:** Represents an authenticated user of the system
|
||||||
|
|
||||||
|
**Fields:**
|
||||||
|
| Field | Type | Constraints | Description |
|
||||||
|
|-------|------|-------------|-------------|
|
||||||
|
| id | UUID | PK, NOT NULL | Unique identifier |
|
||||||
|
| email | VARCHAR(255) | UNIQUE, NOT NULL | User email (login) |
|
||||||
|
| password_hash | VARCHAR(255) | NOT NULL | Bcrypt hashed password |
|
||||||
|
| created_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Account creation time |
|
||||||
|
| updated_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Last update time |
|
||||||
|
| is_active | BOOLEAN | NOT NULL, DEFAULT TRUE | Account active status |
|
||||||
|
|
||||||
|
**Validation Rules:**
|
||||||
|
- Email must be valid format (RFC 5322)
|
||||||
|
- Email must be lowercase
|
||||||
|
- Password minimum 8 characters before hashing
|
||||||
|
- Password must contain: 1 uppercase, 1 lowercase, 1 number
|
||||||
|
|
||||||
|
**Indexes:**
|
||||||
|
- PRIMARY KEY (id)
|
||||||
|
- UNIQUE INDEX (email)
|
||||||
|
- INDEX (created_at)
|
||||||
|
|
||||||
|
**Relationships:**
|
||||||
|
- User → Board (1:N)
|
||||||
|
- User → Image (1:N, images they own)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Board
|
||||||
|
|
||||||
|
**Purpose:** Represents a reference board (canvas) containing images
|
||||||
|
|
||||||
|
**Fields:**
|
||||||
|
| Field | Type | Constraints | Description |
|
||||||
|
|-------|------|-------------|-------------|
|
||||||
|
| id | UUID | PK, NOT NULL | Unique identifier |
|
||||||
|
| user_id | UUID | FK(users.id), NOT NULL | Owner reference |
|
||||||
|
| title | VARCHAR(255) | NOT NULL | Board title |
|
||||||
|
| description | TEXT | NULL | Optional description |
|
||||||
|
| viewport_state | JSONB | NOT NULL | Canvas viewport (zoom, pan, rotation) |
|
||||||
|
| created_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Creation time |
|
||||||
|
| updated_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Last modification |
|
||||||
|
| is_deleted | BOOLEAN | NOT NULL, DEFAULT FALSE | Soft delete flag |
|
||||||
|
|
||||||
|
**Validation Rules:**
|
||||||
|
- Title: 1-255 characters, non-empty
|
||||||
|
- viewport_state must contain: `{x: number, y: number, zoom: number, rotation: number}`
|
||||||
|
- Zoom: 0.1 to 5.0
|
||||||
|
- Rotation: 0 to 360 degrees
|
||||||
|
|
||||||
|
**Indexes:**
|
||||||
|
- PRIMARY KEY (id)
|
||||||
|
- INDEX (user_id, created_at)
|
||||||
|
- INDEX (updated_at)
|
||||||
|
- GIN INDEX (viewport_state) - for JSONB queries
|
||||||
|
|
||||||
|
**Relationships:**
|
||||||
|
- Board → User (N:1)
|
||||||
|
- Board → BoardImage (1:N)
|
||||||
|
- Board → Group (1:N)
|
||||||
|
- Board → ShareLink (1:N)
|
||||||
|
|
||||||
|
**Example viewport_state:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"x": 0,
|
||||||
|
"y": 0,
|
||||||
|
"zoom": 1.0,
|
||||||
|
"rotation": 0
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Image
|
||||||
|
|
||||||
|
**Purpose:** Represents an uploaded image file
|
||||||
|
|
||||||
|
**Fields:**
|
||||||
|
| Field | Type | Constraints | Description |
|
||||||
|
|-------|------|-------------|-------------|
|
||||||
|
| id | UUID | PK, NOT NULL | Unique identifier |
|
||||||
|
| user_id | UUID | FK(users.id), NOT NULL | Owner reference |
|
||||||
|
| filename | VARCHAR(255) | NOT NULL | Original filename |
|
||||||
|
| storage_path | VARCHAR(512) | NOT NULL | Path in MinIO |
|
||||||
|
| file_size | BIGINT | NOT NULL | Size in bytes |
|
||||||
|
| mime_type | VARCHAR(100) | NOT NULL | MIME type (image/jpeg, etc) |
|
||||||
|
| width | INTEGER | NOT NULL | Original width in pixels |
|
||||||
|
| height | INTEGER | NOT NULL | Original height in pixels |
|
||||||
|
| metadata | JSONB | NOT NULL | Additional metadata |
|
||||||
|
| created_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Upload time |
|
||||||
|
| reference_count | INTEGER | NOT NULL, DEFAULT 0 | How many boards use this |
|
||||||
|
|
||||||
|
**Validation Rules:**
|
||||||
|
- filename: non-empty, sanitized (no path traversal)
|
||||||
|
- file_size: 1 byte to 50MB (52,428,800 bytes)
|
||||||
|
- mime_type: must be in allowed list (image/jpeg, image/png, image/gif, image/webp, image/svg+xml)
|
||||||
|
- width, height: 1 to 10,000 pixels
|
||||||
|
- metadata must contain: `{format: string, exif?: object, checksum: string}`
|
||||||
|
|
||||||
|
**Indexes:**
|
||||||
|
- PRIMARY KEY (id)
|
||||||
|
- INDEX (user_id, created_at)
|
||||||
|
- INDEX (filename)
|
||||||
|
- GIN INDEX (metadata)
|
||||||
|
|
||||||
|
**Relationships:**
|
||||||
|
- Image → User (N:1)
|
||||||
|
- Image → BoardImage (1:N)
|
||||||
|
|
||||||
|
**Example metadata:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"format": "jpeg",
|
||||||
|
"exif": {
|
||||||
|
"DateTimeOriginal": "2025:11:02 12:00:00",
|
||||||
|
"Model": "Camera Model"
|
||||||
|
},
|
||||||
|
"checksum": "sha256:abc123...",
|
||||||
|
"thumbnails": {
|
||||||
|
"low": "/thumbnails/low/abc123.webp",
|
||||||
|
"medium": "/thumbnails/medium/abc123.webp",
|
||||||
|
"high": "/thumbnails/high/abc123.webp"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### BoardImage
|
||||||
|
|
||||||
|
**Purpose:** Junction table connecting boards and images with position/transformation data
|
||||||
|
|
||||||
|
**Fields:**
|
||||||
|
| Field | Type | Constraints | Description |
|
||||||
|
|-------|------|-------------|-------------|
|
||||||
|
| id | UUID | PK, NOT NULL | Unique identifier |
|
||||||
|
| board_id | UUID | FK(boards.id), NOT NULL | Board reference |
|
||||||
|
| image_id | UUID | FK(images.id), NOT NULL | Image reference |
|
||||||
|
| position | JSONB | NOT NULL | X, Y coordinates |
|
||||||
|
| transformations | JSONB | NOT NULL | Scale, rotation, crop, etc |
|
||||||
|
| z_order | INTEGER | NOT NULL | Layer order (higher = front) |
|
||||||
|
| group_id | UUID | FK(groups.id), NULL | Optional group membership |
|
||||||
|
| created_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Added to board time |
|
||||||
|
| updated_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Last transformation time |
|
||||||
|
|
||||||
|
**Validation Rules:**
|
||||||
|
- position: `{x: number, y: number}` - no bounds (infinite canvas)
|
||||||
|
- transformations must contain: `{scale: number, rotation: number, opacity: number, flipped_h: bool, flipped_v: bool, crop?: object, greyscale: bool}`
|
||||||
|
- scale: 0.01 to 10.0
|
||||||
|
- rotation: 0 to 360 degrees
|
||||||
|
- opacity: 0.0 to 1.0
|
||||||
|
- z_order: 0 to 999999
|
||||||
|
- One image can appear on multiple boards (via different BoardImage records)
|
||||||
|
|
||||||
|
**Indexes:**
|
||||||
|
- PRIMARY KEY (id)
|
||||||
|
- UNIQUE INDEX (board_id, image_id) - prevent duplicates
|
||||||
|
- INDEX (board_id, z_order) - for layer sorting
|
||||||
|
- INDEX (group_id)
|
||||||
|
- GIN INDEX (position, transformations)
|
||||||
|
|
||||||
|
**Relationships:**
|
||||||
|
- BoardImage → Board (N:1)
|
||||||
|
- BoardImage → Image (N:1)
|
||||||
|
- BoardImage → Group (N:1, optional)
|
||||||
|
|
||||||
|
**Example position:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"x": 100,
|
||||||
|
"y": 250
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example transformations:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"scale": 1.5,
|
||||||
|
"rotation": 45,
|
||||||
|
"opacity": 0.8,
|
||||||
|
"flipped_h": false,
|
||||||
|
"flipped_v": false,
|
||||||
|
"crop": {
|
||||||
|
"x": 10,
|
||||||
|
"y": 10,
|
||||||
|
"width": 200,
|
||||||
|
"height": 200
|
||||||
|
},
|
||||||
|
"greyscale": false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Group
|
||||||
|
|
||||||
|
**Purpose:** Groups of images with shared annotation and color label
|
||||||
|
|
||||||
|
**Fields:**
|
||||||
|
| Field | Type | Constraints | Description |
|
||||||
|
|-------|------|-------------|-------------|
|
||||||
|
| id | UUID | PK, NOT NULL | Unique identifier |
|
||||||
|
| board_id | UUID | FK(boards.id), NOT NULL | Board reference |
|
||||||
|
| name | VARCHAR(255) | NOT NULL | Group name |
|
||||||
|
| color | VARCHAR(7) | NOT NULL | Hex color (e.g., #FF5733) |
|
||||||
|
| annotation | TEXT | NULL | Optional text note |
|
||||||
|
| created_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Creation time |
|
||||||
|
| updated_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Last update |
|
||||||
|
|
||||||
|
**Validation Rules:**
|
||||||
|
- name: 1-255 characters, non-empty
|
||||||
|
- color: must be valid hex color (#RRGGBB format)
|
||||||
|
- annotation: max 10,000 characters
|
||||||
|
|
||||||
|
**Indexes:**
|
||||||
|
- PRIMARY KEY (id)
|
||||||
|
- INDEX (board_id, created_at)
|
||||||
|
|
||||||
|
**Relationships:**
|
||||||
|
- Group → Board (N:1)
|
||||||
|
- Group → BoardImage (1:N)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### ShareLink
|
||||||
|
|
||||||
|
**Purpose:** Shareable links to boards with permission control
|
||||||
|
|
||||||
|
**Fields:**
|
||||||
|
| Field | Type | Constraints | Description |
|
||||||
|
|-------|------|-------------|-------------|
|
||||||
|
| id | UUID | PK, NOT NULL | Unique identifier |
|
||||||
|
| board_id | UUID | FK(boards.id), NOT NULL | Board reference |
|
||||||
|
| token | VARCHAR(64) | UNIQUE, NOT NULL | Secure random token |
|
||||||
|
| permission_level | VARCHAR(20) | NOT NULL | 'view-only' or 'view-comment' |
|
||||||
|
| created_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Link creation time |
|
||||||
|
| expires_at | TIMESTAMP | NULL | Optional expiration |
|
||||||
|
| last_accessed_at | TIMESTAMP | NULL | Last time link was used |
|
||||||
|
| access_count | INTEGER | NOT NULL, DEFAULT 0 | Usage counter |
|
||||||
|
| is_revoked | BOOLEAN | NOT NULL, DEFAULT FALSE | Revocation flag |
|
||||||
|
|
||||||
|
**Validation Rules:**
|
||||||
|
- token: 64 character random string (URL-safe base64)
|
||||||
|
- permission_level: must be 'view-only' or 'view-comment'
|
||||||
|
- expires_at: if set, must be future date
|
||||||
|
- Access count incremented on each use
|
||||||
|
|
||||||
|
**Indexes:**
|
||||||
|
- PRIMARY KEY (id)
|
||||||
|
- UNIQUE INDEX (token)
|
||||||
|
- INDEX (board_id, is_revoked)
|
||||||
|
- INDEX (expires_at, is_revoked)
|
||||||
|
|
||||||
|
**Relationships:**
|
||||||
|
- ShareLink → Board (N:1)
|
||||||
|
|
||||||
|
**State Transitions:**
|
||||||
|
```
|
||||||
|
[Created] → [Active] → [Revoked]
|
||||||
|
↓
|
||||||
|
[Expired] (if expires_at set)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Comment (for View+Comment links)
|
||||||
|
|
||||||
|
**Purpose:** Comments from viewers on shared boards
|
||||||
|
|
||||||
|
**Fields:**
|
||||||
|
| Field | Type | Constraints | Description |
|
||||||
|
|-------|------|-------------|-------------|
|
||||||
|
| id | UUID | PK, NOT NULL | Unique identifier |
|
||||||
|
| board_id | UUID | FK(boards.id), NOT NULL | Board reference |
|
||||||
|
| share_link_id | UUID | FK(share_links.id), NULL | Origin link (optional) |
|
||||||
|
| author_name | VARCHAR(100) | NOT NULL | Commenter name |
|
||||||
|
| content | TEXT | NOT NULL | Comment text |
|
||||||
|
| position | JSONB | NULL | Optional canvas position reference |
|
||||||
|
| created_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Comment time |
|
||||||
|
| is_deleted | BOOLEAN | NOT NULL, DEFAULT FALSE | Soft delete |
|
||||||
|
|
||||||
|
**Validation Rules:**
|
||||||
|
- author_name: 1-100 characters, sanitized
|
||||||
|
- content: 1-5,000 characters, non-empty
|
||||||
|
- position: if set, `{x: number, y: number}`
|
||||||
|
|
||||||
|
**Indexes:**
|
||||||
|
- PRIMARY KEY (id)
|
||||||
|
- INDEX (board_id, created_at)
|
||||||
|
- INDEX (share_link_id)
|
||||||
|
|
||||||
|
**Relationships:**
|
||||||
|
- Comment → Board (N:1)
|
||||||
|
- Comment → ShareLink (N:1, optional)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Database Schema SQL
|
||||||
|
|
||||||
|
### PostgreSQL Schema Creation
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- Enable UUID extension
|
||||||
|
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
|
||||||
|
|
||||||
|
-- Users table
|
||||||
|
CREATE TABLE users (
|
||||||
|
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||||||
|
email VARCHAR(255) UNIQUE NOT NULL CHECK (email = LOWER(email)),
|
||||||
|
password_hash VARCHAR(255) NOT NULL,
|
||||||
|
created_at TIMESTAMP NOT NULL DEFAULT NOW(),
|
||||||
|
updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
|
||||||
|
is_active BOOLEAN NOT NULL DEFAULT TRUE
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE INDEX idx_users_created_at ON users(created_at);
|
||||||
|
|
||||||
|
-- Boards table
|
||||||
|
CREATE TABLE boards (
|
||||||
|
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||||||
|
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||||
|
title VARCHAR(255) NOT NULL CHECK (LENGTH(title) > 0),
|
||||||
|
description TEXT,
|
||||||
|
viewport_state JSONB NOT NULL DEFAULT '{"x": 0, "y": 0, "zoom": 1.0, "rotation": 0}',
|
||||||
|
created_at TIMESTAMP NOT NULL DEFAULT NOW(),
|
||||||
|
updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
|
||||||
|
is_deleted BOOLEAN NOT NULL DEFAULT FALSE
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE INDEX idx_boards_user_created ON boards(user_id, created_at);
|
||||||
|
CREATE INDEX idx_boards_updated ON boards(updated_at);
|
||||||
|
CREATE INDEX idx_boards_viewport ON boards USING GIN (viewport_state);
|
||||||
|
|
||||||
|
-- Images table
|
||||||
|
CREATE TABLE images (
|
||||||
|
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||||||
|
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||||
|
filename VARCHAR(255) NOT NULL,
|
||||||
|
storage_path VARCHAR(512) NOT NULL,
|
||||||
|
file_size BIGINT NOT NULL CHECK (file_size > 0 AND file_size <= 52428800),
|
||||||
|
mime_type VARCHAR(100) NOT NULL,
|
||||||
|
width INTEGER NOT NULL CHECK (width > 0 AND width <= 10000),
|
||||||
|
height INTEGER NOT NULL CHECK (height > 0 AND height <= 10000),
|
||||||
|
metadata JSONB NOT NULL,
|
||||||
|
created_at TIMESTAMP NOT NULL DEFAULT NOW(),
|
||||||
|
reference_count INTEGER NOT NULL DEFAULT 0
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE INDEX idx_images_user_created ON images(user_id, created_at);
|
||||||
|
CREATE INDEX idx_images_filename ON images(filename);
|
||||||
|
CREATE INDEX idx_images_metadata ON images USING GIN (metadata);
|
||||||
|
|
||||||
|
-- Groups table
|
||||||
|
CREATE TABLE groups (
|
||||||
|
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||||||
|
board_id UUID NOT NULL REFERENCES boards(id) ON DELETE CASCADE,
|
||||||
|
name VARCHAR(255) NOT NULL CHECK (LENGTH(name) > 0),
|
||||||
|
color VARCHAR(7) NOT NULL CHECK (color ~ '^#[0-9A-Fa-f]{6}$'),
|
||||||
|
annotation TEXT,
|
||||||
|
created_at TIMESTAMP NOT NULL DEFAULT NOW(),
|
||||||
|
updated_at TIMESTAMP NOT NULL DEFAULT NOW()
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE INDEX idx_groups_board_created ON groups(board_id, created_at);
|
||||||
|
|
||||||
|
-- BoardImages junction table
|
||||||
|
CREATE TABLE board_images (
|
||||||
|
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||||||
|
board_id UUID NOT NULL REFERENCES boards(id) ON DELETE CASCADE,
|
||||||
|
image_id UUID NOT NULL REFERENCES images(id) ON DELETE CASCADE,
|
||||||
|
position JSONB NOT NULL,
|
||||||
|
transformations JSONB NOT NULL DEFAULT '{"scale": 1.0, "rotation": 0, "opacity": 1.0, "flipped_h": false, "flipped_v": false, "greyscale": false}',
|
||||||
|
z_order INTEGER NOT NULL DEFAULT 0,
|
||||||
|
group_id UUID REFERENCES groups(id) ON DELETE SET NULL,
|
||||||
|
created_at TIMESTAMP NOT NULL DEFAULT NOW(),
|
||||||
|
updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
|
||||||
|
UNIQUE(board_id, image_id)
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE INDEX idx_board_images_board_z ON board_images(board_id, z_order);
|
||||||
|
CREATE INDEX idx_board_images_group ON board_images(group_id);
|
||||||
|
CREATE INDEX idx_board_images_position ON board_images USING GIN (position);
|
||||||
|
CREATE INDEX idx_board_images_transformations ON board_images USING GIN (transformations);
|
||||||
|
|
||||||
|
-- ShareLinks table
|
||||||
|
CREATE TABLE share_links (
|
||||||
|
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||||||
|
board_id UUID NOT NULL REFERENCES boards(id) ON DELETE CASCADE,
|
||||||
|
token VARCHAR(64) UNIQUE NOT NULL,
|
||||||
|
permission_level VARCHAR(20) NOT NULL CHECK (permission_level IN ('view-only', 'view-comment')),
|
||||||
|
created_at TIMESTAMP NOT NULL DEFAULT NOW(),
|
||||||
|
expires_at TIMESTAMP,
|
||||||
|
last_accessed_at TIMESTAMP,
|
||||||
|
access_count INTEGER NOT NULL DEFAULT 0,
|
||||||
|
is_revoked BOOLEAN NOT NULL DEFAULT FALSE
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE UNIQUE INDEX idx_share_links_token ON share_links(token);
|
||||||
|
CREATE INDEX idx_share_links_board_revoked ON share_links(board_id, is_revoked);
|
||||||
|
CREATE INDEX idx_share_links_expires_revoked ON share_links(expires_at, is_revoked);
|
||||||
|
|
||||||
|
-- Comments table
|
||||||
|
CREATE TABLE comments (
|
||||||
|
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||||||
|
board_id UUID NOT NULL REFERENCES boards(id) ON DELETE CASCADE,
|
||||||
|
share_link_id UUID REFERENCES share_links(id) ON DELETE SET NULL,
|
||||||
|
author_name VARCHAR(100) NOT NULL,
|
||||||
|
content TEXT NOT NULL CHECK (LENGTH(content) > 0 AND LENGTH(content) <= 5000),
|
||||||
|
position JSONB,
|
||||||
|
created_at TIMESTAMP NOT NULL DEFAULT NOW(),
|
||||||
|
is_deleted BOOLEAN NOT NULL DEFAULT FALSE
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE INDEX idx_comments_board_created ON comments(board_id, created_at);
|
||||||
|
CREATE INDEX idx_comments_share_link ON comments(share_link_id);
|
||||||
|
|
||||||
|
-- Triggers for updated_at
|
||||||
|
CREATE OR REPLACE FUNCTION update_updated_at_column()
|
||||||
|
RETURNS TRIGGER AS $$
|
||||||
|
BEGIN
|
||||||
|
NEW.updated_at = NOW();
|
||||||
|
RETURN NEW;
|
||||||
|
END;
|
||||||
|
$$ language 'plpgsql';
|
||||||
|
|
||||||
|
CREATE TRIGGER update_users_updated_at BEFORE UPDATE ON users FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
|
||||||
|
CREATE TRIGGER update_boards_updated_at BEFORE UPDATE ON boards FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
|
||||||
|
CREATE TRIGGER update_groups_updated_at BEFORE UPDATE ON groups FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
|
||||||
|
CREATE TRIGGER update_board_images_updated_at BEFORE UPDATE ON board_images FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Migrations Strategy
|
||||||
|
|
||||||
|
**Tool:** Alembic (SQLAlchemy migration tool)
|
||||||
|
|
||||||
|
**Process:**
|
||||||
|
1. Initial migration creates all tables
|
||||||
|
2. Subsequent migrations track schema changes
|
||||||
|
3. All migrations tested in staging before production
|
||||||
|
4. Rollback scripts maintained for each migration
|
||||||
|
5. Migrations run automatically during deployment
|
||||||
|
|
||||||
|
**Naming Convention:**
|
||||||
|
```
|
||||||
|
YYYYMMDD_HHMMSS_descriptive_name.py
|
||||||
|
```
|
||||||
|
|
||||||
|
Example:
|
||||||
|
```
|
||||||
|
20251102_100000_initial_schema.py
|
||||||
|
20251110_140000_add_comments_table.py
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Data Integrity Rules
|
||||||
|
|
||||||
|
### Referential Integrity
|
||||||
|
- All foreign keys have ON DELETE CASCADE or SET NULL as appropriate
|
||||||
|
- No orphaned records allowed
|
||||||
|
|
||||||
|
### Business Rules
|
||||||
|
1. User must own board to modify it
|
||||||
|
2. Images can only be added to boards by board owner
|
||||||
|
3. Share links can only be created/revoked by board owner
|
||||||
|
4. Comments only allowed on boards with active View+Comment links
|
||||||
|
5. Soft deletes used for boards (is_deleted flag) to preserve history
|
||||||
|
6. Hard deletes for images only when reference_count = 0
|
||||||
|
|
||||||
|
### Validation
|
||||||
|
- All constraints enforced at database level
|
||||||
|
- Additional validation in application layer (Pydantic models)
|
||||||
|
- Client-side validation for UX (pre-submit checks)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Query Patterns
|
||||||
|
|
||||||
|
### Common Queries
|
||||||
|
|
||||||
|
**1. Get user's boards (with image count):**
|
||||||
|
```sql
|
||||||
|
SELECT b.*, COUNT(bi.id) as image_count
|
||||||
|
FROM boards b
|
||||||
|
LEFT JOIN board_images bi ON b.id = bi.board_id
|
||||||
|
WHERE b.user_id = $1 AND b.is_deleted = FALSE
|
||||||
|
GROUP BY b.id
|
||||||
|
ORDER BY b.updated_at DESC;
|
||||||
|
```
|
||||||
|
|
||||||
|
**2. Get board with all images (sorted by Z-order):**
|
||||||
|
```sql
|
||||||
|
SELECT bi.*, i.*, bi.transformations, bi.position
|
||||||
|
FROM board_images bi
|
||||||
|
JOIN images i ON bi.image_id = i.id
|
||||||
|
WHERE bi.board_id = $1
|
||||||
|
ORDER BY bi.z_order ASC;
|
||||||
|
```
|
||||||
|
|
||||||
|
**3. Get groups with member count:**
|
||||||
|
```sql
|
||||||
|
SELECT g.*, COUNT(bi.id) as member_count
|
||||||
|
FROM groups g
|
||||||
|
LEFT JOIN board_images bi ON g.id = bi.group_id
|
||||||
|
WHERE g.board_id = $1
|
||||||
|
GROUP BY g.id
|
||||||
|
ORDER BY g.created_at DESC;
|
||||||
|
```
|
||||||
|
|
||||||
|
**4. Validate share link:**
|
||||||
|
```sql
|
||||||
|
SELECT sl.*, b.user_id as board_owner_id
|
||||||
|
FROM share_links sl
|
||||||
|
JOIN boards b ON sl.board_id = b.id
|
||||||
|
WHERE sl.token = $1
|
||||||
|
AND sl.is_revoked = FALSE
|
||||||
|
AND (sl.expires_at IS NULL OR sl.expires_at > NOW());
|
||||||
|
```
|
||||||
|
|
||||||
|
**5. Search user's image library:**
|
||||||
|
```sql
|
||||||
|
SELECT *
|
||||||
|
FROM images
|
||||||
|
WHERE user_id = $1
|
||||||
|
AND filename ILIKE $2
|
||||||
|
ORDER BY created_at DESC
|
||||||
|
LIMIT 50;
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Performance Considerations
|
||||||
|
|
||||||
|
### Indexes
|
||||||
|
- All foreign keys indexed
|
||||||
|
- JSONB fields use GIN indexes for fast queries
|
||||||
|
- Compound indexes for common query patterns
|
||||||
|
|
||||||
|
### Optimization
|
||||||
|
- Pagination for large result sets (LIMIT/OFFSET)
|
||||||
|
- Connection pooling (SQLAlchemy default: 5-20 connections)
|
||||||
|
- Prepared statements for repeated queries
|
||||||
|
- JSONB queries optimized with proper indexing
|
||||||
|
|
||||||
|
### Monitoring
|
||||||
|
- Slow query log enabled (>100ms)
|
||||||
|
- Query explain plans reviewed regularly
|
||||||
|
- Database statistics collected (pg_stat_statements)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Backup & Recovery
|
||||||
|
|
||||||
|
**Strategy:**
|
||||||
|
- Daily full backups (pg_dump)
|
||||||
|
- Point-in-time recovery enabled (WAL archiving)
|
||||||
|
- Retention: 30 days
|
||||||
|
- Test restores monthly
|
||||||
|
|
||||||
|
**Data Durability:**
|
||||||
|
- Database: PostgreSQL with WAL (99.99% durability)
|
||||||
|
- Images: MinIO with erasure coding (99.999% durability)
|
||||||
|
- Separate backup of both systems
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
This data model supports all 18 functional requirements and ensures data integrity, performance, and scalability.
|
||||||
|
|
||||||
File diff suppressed because it is too large
Load Diff
489
specs/001-reference-board-viewer/quickstart.md
Normal file
489
specs/001-reference-board-viewer/quickstart.md
Normal file
@@ -0,0 +1,489 @@
|
|||||||
|
# Quickstart Guide: Reference Board Viewer
|
||||||
|
|
||||||
|
**Last Updated:** 2025-11-02
|
||||||
|
**For:** Developers starting implementation
|
||||||
|
**Prerequisites:** Nix installed, basic Git knowledge
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
This guide will get you from zero to a running development environment for the Reference Board Viewer in under 10 minutes.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 1: Clone and Enter Development Environment
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Clone repository (if not already)
|
||||||
|
cd /home/jawz/Development/Projects/personal/webref
|
||||||
|
|
||||||
|
# Enter Nix development shell (installs all dependencies)
|
||||||
|
nix develop
|
||||||
|
|
||||||
|
# Verify tools are available
|
||||||
|
python --version # Should show Python 3.12+
|
||||||
|
node --version # Should show Node.js latest
|
||||||
|
psql --version # PostgreSQL client
|
||||||
|
```
|
||||||
|
|
||||||
|
**What this does:** Nix installs all verified dependencies from nixpkgs (see VERIFICATION-COMPLETE.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 2: Initialize Database
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start PostgreSQL (in development)
|
||||||
|
# Option A: Using Nix
|
||||||
|
pg_ctl -D ./pgdata init
|
||||||
|
pg_ctl -D ./pgdata start
|
||||||
|
|
||||||
|
# Option B: Using system PostgreSQL
|
||||||
|
sudo systemctl start postgresql
|
||||||
|
|
||||||
|
# Create database
|
||||||
|
createdb webref
|
||||||
|
|
||||||
|
# Run migrations (after backend setup)
|
||||||
|
cd backend
|
||||||
|
alembic upgrade head
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 3: Set Up Backend (FastAPI)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create backend directory
|
||||||
|
mkdir -p backend
|
||||||
|
cd backend
|
||||||
|
|
||||||
|
# Initialize uv project
|
||||||
|
uv init
|
||||||
|
|
||||||
|
# Install dependencies (all verified in nixpkgs)
|
||||||
|
uv add fastapi uvicorn sqlalchemy alembic pydantic \
|
||||||
|
python-jose passlib pillow boto3 python-multipart \
|
||||||
|
httpx pytest pytest-cov pytest-asyncio
|
||||||
|
|
||||||
|
# Create basic structure
|
||||||
|
mkdir -p app/{auth,boards,images,database,api,core} tests
|
||||||
|
|
||||||
|
# Create main.py
|
||||||
|
cat > app/main.py << 'EOF'
|
||||||
|
from fastapi import FastAPI
|
||||||
|
from fastapi.middleware.cors import CORSMiddleware
|
||||||
|
|
||||||
|
app = FastAPI(title="Reference Board Viewer API")
|
||||||
|
|
||||||
|
app.add_middleware(
|
||||||
|
CORSMiddleware,
|
||||||
|
allow_origins=["http://localhost:5173"], # Vite dev server
|
||||||
|
allow_credentials=True,
|
||||||
|
allow_methods=["*"],
|
||||||
|
allow_headers=["*"],
|
||||||
|
)
|
||||||
|
|
||||||
|
@app.get("/")
|
||||||
|
async def root():
|
||||||
|
return {"message": "Reference Board Viewer API", "version": "1.0.0"}
|
||||||
|
|
||||||
|
@app.get("/health")
|
||||||
|
async def health():
|
||||||
|
return {"status": "healthy"}
|
||||||
|
EOF
|
||||||
|
|
||||||
|
# Run development server
|
||||||
|
uvicorn app.main:app --reload --port 8000
|
||||||
|
|
||||||
|
# Test: curl http://localhost:8000/
|
||||||
|
```
|
||||||
|
|
||||||
|
**Verify:** Navigate to http://localhost:8000/docs to see auto-generated OpenAPI documentation.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 4: Set Up Frontend (Svelte + Konva)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create frontend directory (in new terminal)
|
||||||
|
cd /home/jawz/Development/Projects/personal/webref
|
||||||
|
mkdir -p frontend
|
||||||
|
cd frontend
|
||||||
|
|
||||||
|
# Initialize SvelteKit project
|
||||||
|
npm create svelte@latest .
|
||||||
|
# Choose: Skeleton project, Yes to TypeScript, Yes to ESLint, Yes to Prettier
|
||||||
|
|
||||||
|
# Install dependencies
|
||||||
|
npm install
|
||||||
|
npm install konva
|
||||||
|
|
||||||
|
# Create basic canvas component
|
||||||
|
mkdir -p src/lib/canvas
|
||||||
|
cat > src/lib/canvas/Board.svelte << 'EOF'
|
||||||
|
<script lang="ts">
|
||||||
|
import { onMount } from 'svelte';
|
||||||
|
import Konva from 'konva';
|
||||||
|
|
||||||
|
let container: HTMLDivElement;
|
||||||
|
let stage: Konva.Stage;
|
||||||
|
|
||||||
|
onMount(() => {
|
||||||
|
stage = new Konva.Stage({
|
||||||
|
container: container,
|
||||||
|
width: window.innerWidth,
|
||||||
|
height: window.innerHeight
|
||||||
|
});
|
||||||
|
|
||||||
|
const layer = new Konva.Layer();
|
||||||
|
stage.add(layer);
|
||||||
|
|
||||||
|
const text = new Konva.Text({
|
||||||
|
text: 'Reference Board Canvas',
|
||||||
|
fontSize: 24,
|
||||||
|
fill: 'black',
|
||||||
|
x: 50,
|
||||||
|
y: 50
|
||||||
|
});
|
||||||
|
|
||||||
|
layer.add(text);
|
||||||
|
layer.draw();
|
||||||
|
});
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<div bind:this={container} class="canvas-container"></div>
|
||||||
|
|
||||||
|
<style>
|
||||||
|
.canvas-container {
|
||||||
|
width: 100%;
|
||||||
|
height: 100vh;
|
||||||
|
background: #f0f0f0;
|
||||||
|
}
|
||||||
|
</style>
|
||||||
|
EOF
|
||||||
|
|
||||||
|
# Update home page
|
||||||
|
cat > src/routes/+page.svelte << 'EOF'
|
||||||
|
<script>
|
||||||
|
import Board from '$lib/canvas/Board.svelte';
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<Board />
|
||||||
|
EOF
|
||||||
|
|
||||||
|
# Run development server
|
||||||
|
npm run dev -- --open
|
||||||
|
|
||||||
|
# Verify: Browser opens to http://localhost:5173
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 5: Start MinIO (Image Storage)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# In new terminal
|
||||||
|
mkdir -p ~/minio-data
|
||||||
|
|
||||||
|
# Start MinIO
|
||||||
|
minio server ~/minio-data --console-address :9001
|
||||||
|
|
||||||
|
# Access console: http://localhost:9001
|
||||||
|
# Default credentials: minioadmin / minioadmin
|
||||||
|
|
||||||
|
# Create bucket
|
||||||
|
mc alias set local http://localhost:9000 minioadmin minioadmin
|
||||||
|
mc mb local/webref
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Project Structure After Setup
|
||||||
|
|
||||||
|
```
|
||||||
|
webref/
|
||||||
|
├── backend/
|
||||||
|
│ ├── app/
|
||||||
|
│ │ ├── main.py ✅ Created
|
||||||
|
│ │ ├── auth/
|
||||||
|
│ │ ├── boards/
|
||||||
|
│ │ ├── images/
|
||||||
|
│ │ ├── database/
|
||||||
|
│ │ └── core/
|
||||||
|
│ ├── tests/
|
||||||
|
│ ├── pyproject.toml ✅ Created by uv
|
||||||
|
│ └── alembic.ini
|
||||||
|
├── frontend/
|
||||||
|
│ ├── src/
|
||||||
|
│ │ ├── lib/
|
||||||
|
│ │ │ └── canvas/
|
||||||
|
│ │ │ └── Board.svelte ✅ Created
|
||||||
|
│ │ └── routes/
|
||||||
|
│ │ └── +page.svelte ✅ Created
|
||||||
|
│ ├── package.json ✅ Created
|
||||||
|
│ └── vite.config.js
|
||||||
|
├── specs/
|
||||||
|
│ └── 001-reference-board-viewer/
|
||||||
|
│ ├── spec.md ✅ Complete
|
||||||
|
│ ├── plan.md ✅ Complete
|
||||||
|
│ ├── data-model.md ✅ Complete
|
||||||
|
│ ├── tech-research.md ✅ Complete
|
||||||
|
│ └── contracts/
|
||||||
|
│ └── api.yaml ✅ Complete
|
||||||
|
├── shell.nix ✅ Update needed
|
||||||
|
└── flake.nix (To be created)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Commands Reference
|
||||||
|
|
||||||
|
### Backend
|
||||||
|
```bash
|
||||||
|
# Run API server
|
||||||
|
uvicorn app.main:app --reload
|
||||||
|
|
||||||
|
# Run tests
|
||||||
|
pytest
|
||||||
|
|
||||||
|
# Run with coverage
|
||||||
|
pytest --cov=app --cov-report=html
|
||||||
|
|
||||||
|
# Check linting
|
||||||
|
ruff check app/
|
||||||
|
|
||||||
|
# Format code
|
||||||
|
ruff format app/
|
||||||
|
|
||||||
|
# Run migrations
|
||||||
|
alembic upgrade head
|
||||||
|
|
||||||
|
# Create migration
|
||||||
|
alembic revision --autogenerate -m "description"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Frontend
|
||||||
|
```bash
|
||||||
|
# Run dev server
|
||||||
|
npm run dev
|
||||||
|
|
||||||
|
# Run tests
|
||||||
|
npm test
|
||||||
|
|
||||||
|
# Check types
|
||||||
|
npm run check
|
||||||
|
|
||||||
|
# Lint
|
||||||
|
npm run lint
|
||||||
|
|
||||||
|
# Build for production
|
||||||
|
npm run build
|
||||||
|
|
||||||
|
# Preview production build
|
||||||
|
npm run preview
|
||||||
|
```
|
||||||
|
|
||||||
|
### Database
|
||||||
|
```bash
|
||||||
|
# Connect to database
|
||||||
|
psql webref
|
||||||
|
|
||||||
|
# Backup database
|
||||||
|
pg_dump webref > backup.sql
|
||||||
|
|
||||||
|
# Restore database
|
||||||
|
psql webref < backup.sql
|
||||||
|
|
||||||
|
# Reset database
|
||||||
|
dropdb webref && createdb webref
|
||||||
|
alembic upgrade head
|
||||||
|
```
|
||||||
|
|
||||||
|
### MinIO
|
||||||
|
```bash
|
||||||
|
# List buckets
|
||||||
|
mc ls local/
|
||||||
|
|
||||||
|
# List files in bucket
|
||||||
|
mc ls local/webref/
|
||||||
|
|
||||||
|
# Copy file to bucket
|
||||||
|
mc cp file.jpg local/webref/originals/
|
||||||
|
|
||||||
|
# Remove file
|
||||||
|
mc rm local/webref/originals/file.jpg
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Environment Variables
|
||||||
|
|
||||||
|
Create `.env` file in backend/:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Database
|
||||||
|
DATABASE_URL=postgresql://localhost/webref
|
||||||
|
|
||||||
|
# JWT Secret (generate with: openssl rand -hex 32)
|
||||||
|
SECRET_KEY=your-secret-key-here
|
||||||
|
ALGORITHM=HS256
|
||||||
|
ACCESS_TOKEN_EXPIRE_MINUTES=30
|
||||||
|
|
||||||
|
# MinIO
|
||||||
|
MINIO_ENDPOINT=localhost:9000
|
||||||
|
MINIO_ACCESS_KEY=minioadmin
|
||||||
|
MINIO_SECRET_KEY=minioadmin
|
||||||
|
MINIO_BUCKET=webref
|
||||||
|
MINIO_SECURE=false
|
||||||
|
|
||||||
|
# CORS
|
||||||
|
CORS_ORIGINS=["http://localhost:5173"]
|
||||||
|
|
||||||
|
# File Upload
|
||||||
|
MAX_FILE_SIZE=52428800 # 50MB
|
||||||
|
MAX_BATCH_SIZE=524288000 # 500MB
|
||||||
|
ALLOWED_MIME_TYPES=["image/jpeg","image/png","image/gif","image/webp","image/svg+xml"]
|
||||||
|
```
|
||||||
|
|
||||||
|
Create `.env` in frontend/:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# API endpoint
|
||||||
|
VITE_API_URL=http://localhost:8000/api/v1
|
||||||
|
|
||||||
|
# Feature flags
|
||||||
|
VITE_ENABLE_COMMENTS=true
|
||||||
|
VITE_ENABLE_SLIDESHOW=true
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testing the Setup
|
||||||
|
|
||||||
|
### 1. Backend Health Check
|
||||||
|
```bash
|
||||||
|
curl http://localhost:8000/health
|
||||||
|
# Expected: {"status":"healthy"}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. API Documentation
|
||||||
|
Navigate to: http://localhost:8000/docs
|
||||||
|
|
||||||
|
### 3. Frontend Canvas
|
||||||
|
Navigate to: http://localhost:5173
|
||||||
|
Should see: "Reference Board Canvas" text on grey background
|
||||||
|
|
||||||
|
### 4. Database Connection
|
||||||
|
```bash
|
||||||
|
psql webref -c "SELECT 1;"
|
||||||
|
# Expected: (1 row)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. MinIO Console
|
||||||
|
Navigate to: http://localhost:9001
|
||||||
|
Login with: minioadmin / minioadmin
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### "Nix command not found"
|
||||||
|
```bash
|
||||||
|
# Install Nix
|
||||||
|
curl -L https://nixos.org/nix/install | sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### "Port 8000 already in use"
|
||||||
|
```bash
|
||||||
|
# Find and kill process
|
||||||
|
lsof -i :8000
|
||||||
|
kill -9 <PID>
|
||||||
|
```
|
||||||
|
|
||||||
|
### "PostgreSQL connection refused"
|
||||||
|
```bash
|
||||||
|
# Start PostgreSQL
|
||||||
|
sudo systemctl start postgresql
|
||||||
|
# Or using Nix:
|
||||||
|
pg_ctl -D ./pgdata start
|
||||||
|
```
|
||||||
|
|
||||||
|
### "npm install fails"
|
||||||
|
```bash
|
||||||
|
# Clear npm cache
|
||||||
|
npm cache clean --force
|
||||||
|
rm -rf node_modules package-lock.json
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
### "Python module not found"
|
||||||
|
```bash
|
||||||
|
# Reinstall with uv
|
||||||
|
uv sync
|
||||||
|
# Or exit and re-enter nix shell
|
||||||
|
exit
|
||||||
|
nix develop
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
1. **Follow the plan:** See [plan.md](./plan.md) for 16-week implementation timeline
|
||||||
|
2. **Implement authentication:** Week 2 tasks in plan
|
||||||
|
3. **Set up database schema:** Use [data-model.md](./data-model.md) and Alembic
|
||||||
|
4. **Implement API endpoints:** Use [contracts/api.yaml](./contracts/api.yaml) as reference
|
||||||
|
5. **Build canvas components:** Follow Week 5-8 tasks
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Development Workflow
|
||||||
|
|
||||||
|
### Daily workflow:
|
||||||
|
```bash
|
||||||
|
# Morning
|
||||||
|
cd webref
|
||||||
|
nix develop
|
||||||
|
cd backend && uvicorn app.main:app --reload &
|
||||||
|
cd frontend && npm run dev &
|
||||||
|
|
||||||
|
# Work on features...
|
||||||
|
|
||||||
|
# Before commit
|
||||||
|
cd backend && pytest && ruff check app/
|
||||||
|
cd frontend && npm run check && npm run lint
|
||||||
|
|
||||||
|
# Commit
|
||||||
|
git add .
|
||||||
|
git commit -m "feat: description"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Weekly workflow:
|
||||||
|
- Review plan.md progress
|
||||||
|
- Update tests for new features
|
||||||
|
- Check coverage: `pytest --cov`
|
||||||
|
- Update documentation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Resources
|
||||||
|
|
||||||
|
- **API Spec:** [contracts/api.yaml](./contracts/api.yaml)
|
||||||
|
- **Data Model:** [data-model.md](./data-model.md)
|
||||||
|
- **Tech Stack:** [tech-research.md](./tech-research.md)
|
||||||
|
- **Nix Verification:** [VERIFICATION-COMPLETE.md](./VERIFICATION-COMPLETE.md)
|
||||||
|
- **Full Plan:** [plan.md](./plan.md)
|
||||||
|
|
||||||
|
**External Docs:**
|
||||||
|
- FastAPI: https://fastapi.tiangolo.com/
|
||||||
|
- Svelte: https://svelte.dev/docs
|
||||||
|
- Konva: https://konvajs.org/docs/
|
||||||
|
- Alembic: https://alembic.sqlalchemy.org/
|
||||||
|
- MinIO: https://min.io/docs/minio/linux/index.html
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Questions?** Check the specification in [spec.md](./spec.md) or plan in [plan.md](./plan.md).
|
||||||
|
|
||||||
|
**Ready to start?** Begin with Week 1 tasks in the implementation plan!
|
||||||
|
|
||||||
1183
specs/001-reference-board-viewer/tasks.md
Normal file
1183
specs/001-reference-board-viewer/tasks.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user