sneakyklaus/docs/ROADMAP.md

# 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