chore: initial project setup
Initialize Sneaky Klaus project with: - uv package management and pyproject.toml - Flask application structure (app.py, config.py) - SQLAlchemy models for Admin and Exchange - Alembic database migrations - Pre-commit hooks configuration - Development tooling (pytest, ruff, mypy) Initial structure follows design documents in docs/: - src/app.py: Application factory with Flask extensions - src/config.py: Environment-based configuration - src/models/: Admin and Exchange models - migrations/: Alembic migration setup 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
321
docs/ROADMAP.md
Normal file
321
docs/ROADMAP.md
Normal file
@@ -0,0 +1,321 @@
|
||||
# Sneaky Klaus - Implementation Roadmap
|
||||
|
||||
## Overview
|
||||
|
||||
This roadmap defines the phased implementation approach for Sneaky Klaus, a self-hosted Secret Santa organization application. The roadmap progresses from foundational infrastructure through core features to enhancement and polish.
|
||||
|
||||
## Key Architectural Decisions
|
||||
|
||||
The following decisions have been approved and are fixed:
|
||||
|
||||
- **Frontend**: Pure server-side rendering with Jinja2 templates (no JavaScript framework)
|
||||
- **Background Jobs**: APScheduler (in-process, no separate job queue)
|
||||
- **Password Requirements**: Minimum 12 characters, no complexity requirements
|
||||
- **Magic Link Expiration**: 1 hour for links, 7-day sliding window for sessions
|
||||
- **Reminder Defaults**: 7 days and 1 day before exchange date (configurable per exchange)
|
||||
- **Minimum Participants**: Hard requirement of 3 participants per exchange
|
||||
|
||||
## Phase Definitions
|
||||
|
||||
### Phase 0: Foundation and Architecture
|
||||
|
||||
**Goal**: Establish technical foundation and architectural design
|
||||
|
||||
**Deliverables**:
|
||||
- Architecture Decision Records (ADRs) for core technology choices
|
||||
- System design documentation (v0.1.0)
|
||||
- Database schema design
|
||||
- API/route specifications
|
||||
- Component design documentation
|
||||
- Development environment setup
|
||||
|
||||
**Stories**: None (pre-implementation architectural work)
|
||||
|
||||
**Dependencies**: None
|
||||
|
||||
**MVP Status**: Prerequisite for MVP
|
||||
|
||||
---
|
||||
|
||||
### Phase 1: Core Admin & Exchange Management (MVP)
|
||||
|
||||
**Goal**: Enable admin to create and manage gift exchanges
|
||||
|
||||
**Stories**:
|
||||
- 1.1 Initial Admin Setup
|
||||
- 1.2 Admin Login
|
||||
- 1.4 Admin Logout
|
||||
- 2.1 Create Exchange
|
||||
- 2.2 View Exchange List
|
||||
- 2.3 View Exchange Details
|
||||
- 2.6 Generate Registration Link
|
||||
- 3.1 Open Registration
|
||||
|
||||
**Dependencies**: Phase 0 complete
|
||||
|
||||
**MVP Status**: **This is the MVP**
|
||||
|
||||
**Exit Criteria**:
|
||||
- Admin can create account, log in, and log out
|
||||
- Admin can create exchanges with all required fields
|
||||
- Admin can view list of exchanges
|
||||
- Admin can generate and copy registration links
|
||||
- Admin can open registration for exchanges
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Participant Registration & Authentication
|
||||
|
||||
**Goal**: Enable participants to join exchanges and authenticate
|
||||
|
||||
**Stories**:
|
||||
- 4.1 Access Registration Page
|
||||
- 4.2 New Participant Registration
|
||||
- 4.3 Returning Participant Detection
|
||||
- 5.1 Magic Link Request
|
||||
- 5.2 Magic Link Login
|
||||
- 5.3 Participant Session
|
||||
- 10.1 Registration Confirmation Email
|
||||
|
||||
**Dependencies**: Phase 1 complete
|
||||
|
||||
**Exit Criteria**:
|
||||
- Participants can access registration page via link
|
||||
- Participants can register with name, email, and gift ideas
|
||||
- Returning participants are detected and can request magic link
|
||||
- Magic links authenticate participants correctly
|
||||
- Participant sessions persist appropriately
|
||||
- Confirmation emails sent successfully
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Exchange State Management & Matching
|
||||
|
||||
**Goal**: Enable complete exchange lifecycle from registration to matching
|
||||
|
||||
**Stories**:
|
||||
- 2.4 Edit Exchange
|
||||
- 3.2 Close Registration
|
||||
- 3.3 Reopen Registration (Pre-Matching)
|
||||
- 7.1 View Participants for Exclusions
|
||||
- 7.2 Add Exclusion Rule
|
||||
- 7.3 Remove Exclusion Rule
|
||||
- 7.4 Exclusion Validation
|
||||
- 8.1 Trigger Matching
|
||||
- 8.2 Matching Algorithm
|
||||
- 8.3 Matching Failure Handling
|
||||
- 8.4 View Matches (Admin)
|
||||
- 10.2 Match Notification Email
|
||||
|
||||
**Dependencies**: Phase 2 complete
|
||||
|
||||
**Exit Criteria**:
|
||||
- Admin can edit exchange details
|
||||
- Admin can close and reopen registration
|
||||
- Admin can configure exclusion rules
|
||||
- Matching algorithm successfully creates valid assignments
|
||||
- Match notification emails sent to all participants
|
||||
- Admin can view all matches for troubleshooting
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Participant Dashboard & Self-Management
|
||||
|
||||
**Goal**: Enable participants to view assignments and manage profiles
|
||||
|
||||
**Stories**:
|
||||
- 4.5 View Participant List (Pre-Matching)
|
||||
- 6.1 Update Profile
|
||||
- 6.2 Withdraw from Exchange
|
||||
- 6.3 Update Reminder Preferences
|
||||
- 11.1 View My Assignment
|
||||
- 11.2 View Exchange Information
|
||||
- 11.3 View Participant List (Post-Matching)
|
||||
|
||||
**Dependencies**: Phase 3 complete
|
||||
|
||||
**Exit Criteria**:
|
||||
- Participants can view and update their profiles
|
||||
- Participants can withdraw before registration closes
|
||||
- Participants can view their assignment after matching
|
||||
- Participants can view exchange information and participant lists
|
||||
- Participants can manage reminder preferences
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Advanced Matching & Admin Features
|
||||
|
||||
**Goal**: Handle edge cases and provide advanced administrative control
|
||||
|
||||
**Stories**:
|
||||
- 2.5 Delete Exchange
|
||||
- 3.4 Reopen Registration (Post-Matching)
|
||||
- 4.4 Admin Self-Registration
|
||||
- 8.5 Re-Match Participants
|
||||
- 8.6 Manual Match Override
|
||||
- 9.1 Remove Participant (Admin)
|
||||
- 9.2 Handle Post-Match Participant Removal
|
||||
|
||||
**Dependencies**: Phase 4 complete
|
||||
|
||||
**Exit Criteria**:
|
||||
- Admin can delete exchanges
|
||||
- Admin can reopen registration after matching (with match clearing)
|
||||
- Admin can participate in their own exchanges
|
||||
- Admin can trigger re-matching
|
||||
- Admin can manually override individual matches
|
||||
- Admin can remove participants with appropriate re-matching
|
||||
|
||||
---
|
||||
|
||||
### Phase 6: Notifications & Reminders
|
||||
|
||||
**Goal**: Complete notification system with reminders and admin notifications
|
||||
|
||||
**Stories**:
|
||||
- 10.3 Reminder Emails
|
||||
- 10.4 Admin Notification: New Registration
|
||||
- 10.5 Admin Notification: Participant Withdrawal
|
||||
- 10.6 Admin Notification: Matching Complete
|
||||
- 10.7 Configure Admin Notifications
|
||||
- 14.1 Configure Reminder Schedule
|
||||
|
||||
**Dependencies**: Phase 4 complete (can run parallel to Phase 5)
|
||||
|
||||
**Exit Criteria**:
|
||||
- Reminder emails sent according to configured schedule
|
||||
- Admin receives opt-in notifications for key events
|
||||
- Admin can configure notification preferences globally and per-exchange
|
||||
- Admin can configure reminder schedule per exchange
|
||||
|
||||
---
|
||||
|
||||
### Phase 7: Data Management & Lifecycle
|
||||
|
||||
**Goal**: Implement data retention and exchange lifecycle completion
|
||||
|
||||
**Stories**:
|
||||
- 1.3 Admin Password Recovery
|
||||
- 3.5 Mark Exchange Complete
|
||||
- 3.6 Automatic Exchange Completion
|
||||
- 12.1 Automatic Data Purge
|
||||
- 12.2 View Data Retention Status
|
||||
|
||||
**Dependencies**: Phase 5 complete
|
||||
|
||||
**Exit Criteria**:
|
||||
- Admin can recover password via email
|
||||
- Exchanges automatically complete after exchange date
|
||||
- Exchange data purged 30 days after completion
|
||||
- Admin can view retention status and purge timeline
|
||||
- Admin receives warning before data purge
|
||||
|
||||
---
|
||||
|
||||
### Phase 8: Polish & Responsive Design
|
||||
|
||||
**Goal**: Ensure excellent user experience across all devices
|
||||
|
||||
**Stories**:
|
||||
- 13.1 Mobile-Friendly Participant Experience
|
||||
- 13.2 Mobile-Friendly Admin Experience
|
||||
|
||||
**Dependencies**: Phase 7 complete
|
||||
|
||||
**Exit Criteria**:
|
||||
- All participant flows work well on mobile devices
|
||||
- All admin flows work well on mobile devices
|
||||
- Touch targets appropriately sized
|
||||
- No horizontal scrolling required
|
||||
- Tested across common mobile browsers
|
||||
|
||||
---
|
||||
|
||||
## Phase Dependencies Graph
|
||||
|
||||
```
|
||||
Phase 0 (Foundation)
|
||||
↓
|
||||
Phase 1 (MVP: Core Admin & Exchange Management)
|
||||
↓
|
||||
Phase 2 (Participant Registration & Authentication)
|
||||
↓
|
||||
Phase 3 (Exchange State Management & Matching)
|
||||
↓
|
||||
Phase 4 (Participant Dashboard & Self-Management)
|
||||
↓
|
||||
├── Phase 5 (Advanced Matching & Admin Features)
|
||||
└── Phase 6 (Notifications & Reminders) [parallel]
|
||||
↓
|
||||
Phase 7 (Data Management & Lifecycle)
|
||||
↓
|
||||
Phase 8 (Polish & Responsive Design)
|
||||
```
|
||||
|
||||
## MVP Definition
|
||||
|
||||
**The MVP is Phase 1**: Core Admin & Exchange Management
|
||||
|
||||
An implementation reaches MVP when:
|
||||
1. An admin can create an account
|
||||
2. An admin can log in and out securely
|
||||
3. An admin can create gift exchanges with all required fields
|
||||
4. An admin can view a list of their exchanges
|
||||
5. An admin can generate shareable registration links
|
||||
6. The application is deployable via Docker
|
||||
|
||||
This represents the minimum foundation for a functional Secret Santa application, even though it doesn't yet support participant registration or matching.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### Story Prioritization Within Phases
|
||||
|
||||
Stories listed within each phase are roughly prioritized, but developers should:
|
||||
- Implement database models and schemas before UI
|
||||
- Implement authentication before protected routes
|
||||
- Consider natural groupings (e.g., all CRUD operations for a feature together)
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
Each phase should include:
|
||||
- Unit tests for business logic
|
||||
- Integration tests for database operations
|
||||
- End-to-end tests for critical user flows
|
||||
- Tests written before or alongside implementation (TDD encouraged)
|
||||
|
||||
### Documentation Updates
|
||||
|
||||
As each phase completes:
|
||||
- Update design docs if implementation reveals necessary changes
|
||||
- Document any deviations from original design with rationale
|
||||
- Update ADRs if architectural decisions change
|
||||
|
||||
### Deployment Considerations
|
||||
|
||||
- Docker image should be buildable and runnable from Phase 1 onward
|
||||
- Each phase should result in a deployable, functional (if limited) application
|
||||
- Database migrations should be reversible where possible
|
||||
|
||||
## Success Criteria
|
||||
|
||||
The implementation is complete when:
|
||||
1. All 8 phases are delivered
|
||||
2. All acceptance criteria for all stories are met
|
||||
3. Application passes end-to-end testing
|
||||
4. Documentation is complete and accurate
|
||||
5. Application is production-ready for self-hosting
|
||||
|
||||
## Timeline Estimates
|
||||
|
||||
Actual timeline depends on development velocity. Rough estimates:
|
||||
- Phase 0: 2-3 days (design work)
|
||||
- Phase 1: 3-5 days (MVP)
|
||||
- Phase 2: 3-4 days
|
||||
- Phase 3: 5-7 days (complex matching logic)
|
||||
- Phase 4: 2-3 days
|
||||
- Phase 5: 3-4 days
|
||||
- Phase 6: 2-3 days
|
||||
- Phase 7: 2-3 days
|
||||
- Phase 8: 2-3 days
|
||||
|
||||
**Total estimate**: 24-37 days of development time
|
||||
Reference in New Issue
Block a user