sneakyklaus/docs/designs/v0.3.0/README.md

Phase 3 (v0.3.0) Design Documentation

Version: 0.3.0 Date: 2025-12-22 Status: Ready for Implementation

Quick Start

Phase 3 implements participant self-management features, building on the authentication foundation from Phase 2.

Core Features:

• Participant list view (see who else registered)
• Profile updates (name and gift ideas)
• Reminder email preferences
• Participant withdrawal (before registration closes)

Document Index

1. System Overview

High-level architecture, goals, and design decisions for Phase 3.

Read this first to understand:

• What's in scope for v0.3.0
• Key design decisions (profile locks, withdrawal rules)
• Data flow diagrams
• State machine changes

Key sections:

• Phase Goals (page 1)
• Key Design Decisions (page 2)
• State Machine Impact (page 4)

2. Participant Self-Management Component Design

Detailed component specifications for all Phase 3 features.

Use this for:

• Exact function signatures and implementations
• Form definitions
• Route specifications
• Template structures
• Email templates

Key sections:

• Business Logic Functions (page 1)
• Forms (page 6)
• Routes (page 8)
• Templates (page 11)
• Security Checklist (page 19)

3. Test Plan

Comprehensive testing specifications for Phase 3.

Use this for:

• Unit test cases and fixtures
• Integration test scenarios
• Acceptance test procedures
• Manual QA steps
• Coverage requirements

Key sections:

• Unit Tests (page 1)
• Integration Tests (page 4)
• Acceptance Tests (page 9)
• Edge Cases (page 11)

4. Implementation Guide

Step-by-step implementation instructions using TDD.

Follow this to:

• Implement features in correct order
• Write tests first, then code
• Verify each feature before moving on
• Create proper commits and PRs

Key sections:

• Implementation Order (page 1)
• Phase 3.1: Participant List (page 2)
• Phase 3.2: Profile Updates (page 4)
• Phase 3.3: Reminder Preferences (page 7)
• Phase 3.4: Withdrawal (page 9)
• Final Steps (page 14)

Architecture Decision Records

ADR-0006: Participant State Management

Documents key decisions about when participants can update profiles, withdraw, and how withdrawals are implemented.

Key decisions:

• Profile updates allowed until matching
• Withdrawals allowed until registration closes
• Soft delete implementation (withdrawn_at timestamp)
• Withdrawn participants visible only to admin
• No re-registration with same email

User Stories Implemented

Phase 3 completes these backlog items:

Epic 4: Participant Registration

• ✅ Story 4.5: View Participant List (Pre-Matching)

Epic 6: Participant Self-Management

• ✅ Story 6.1: Update Profile
• ✅ Story 6.2: Withdraw from Exchange
• ✅ Story 6.3: Update Reminder Preferences

Dependencies

Prerequisites (from Phase 2)

• ✅ Participant model with withdrawn_at field
• ✅ Participant authentication (@participant_required decorator)
• ✅ Participant dashboard route
• ✅ Email service for sending emails

No New Dependencies

Phase 3 requires no new:

• Python packages
• Database migrations
• Environment variables
• External services

Technical Highlights

New Files Created

src/
  utils/participant.py              # Business logic functions
  services/withdrawal.py            # Withdrawal service

templates/
  participant/
    profile_edit.html               # Profile edit page
    withdraw.html                   # Withdrawal confirmation
  emails/
    participant/
      withdrawal_confirmation.html  # Withdrawal email
      withdrawal_confirmation.txt   # Plain text version

tests/
  unit/
    test_participant_utils.py       # Unit tests for business logic
    test_withdrawal_service.py      # Unit tests for withdrawal
  integration/
    test_profile_update.py          # Profile update integration tests
    test_withdrawal.py              # Withdrawal integration tests
    test_participant_list.py        # Participant list tests
    test_reminder_preferences.py    # Preference update tests

Modified Files

src/
  routes/participant.py             # New routes added
  forms/participant.py              # New forms added
  services/email.py                 # Withdrawal email method added

templates/
  participant/dashboard.html        # Enhanced with participant list

Design Principles Applied

Phase 3 adheres to project principles:

1. Simplicity First

   • No new database tables (uses existing fields)
   • No new external dependencies
   • Soft delete instead of complex cascade handling

2. State-Based Permissions

   • Clear rules about when operations are allowed
   • Based on exchange state (draft, open, closed, matched)
   • Easy to test and reason about

3. TDD Approach

   • Implementation guide follows test-first methodology
   • Every feature has unit and integration tests
   • 80%+ coverage maintained

4. Security by Design

   • All routes require authentication
   • State validation prevents unauthorized operations
   • CSRF protection on all POST operations
   • Input sanitization via WTForms and Jinja2

5. Privacy-Conscious

   • Participant list shows names only (no emails)
   • Withdrawn participants hidden from other participants
   • Gift ideas not revealed until matching

Implementation Checklist

Use this to track progress:

• Phase 3.1: Participant List View

  • Create src/utils/participant.py
  • Write unit tests for utility functions
  • Update dashboard route
  • Update dashboard template
  • Write integration tests
  • Manual QA

• Phase 3.2: Profile Updates

  • Add can_update_profile() function
  • Write unit tests for state validation
  • Create ProfileUpdateForm
  • Create profile edit route
  • Create profile edit template
  • Update dashboard with edit link
  • Write integration tests
  • Manual QA

• Phase 3.3: Reminder Preferences

  • Create ReminderPreferenceForm
  • Create preference update route
  • Update dashboard with preference form
  • Write integration tests
  • Manual QA

• Phase 3.4: Withdrawal

  • Add can_withdraw() function
  • Create src/services/withdrawal.py
  • Write unit tests for withdrawal service
  • Create WithdrawForm
  • Create withdrawal route
  • Create email templates
  • Update email service
  • Create withdrawal template
  • Update dashboard with withdraw link
  • Write integration tests
  • Manual QA

• Final Steps

  • Run all tests (≥ 80% coverage)
  • Run linting and type checking
  • Complete manual QA from test plan
  • Update documentation if needed
  • Create feature branch
  • Commit changes
  • Create pull request

Success Criteria

Phase 3 is complete when:

1. ✅ All user stories have passing acceptance tests
2. ✅ Code coverage ≥ 80%
3. ✅ All linting and type checking passes
4. ✅ Manual QA completed
5. ✅ Security checklist verified
6. ✅ Accessibility tests pass
7. ✅ Browser compatibility verified
8. ✅ Phase 2 regression tests still pass
9. ✅ Documentation updated
10. ✅ Pull request approved and merged

What's Next: Phase 4

After Phase 3 is complete, the next logical phase is:

Phase 4 (v0.4.0): Post-Matching Participant Experience (Epic 11)

• View assigned recipient (match assignment)
• View recipient's gift ideas
• View exchange information post-matching
• Participant list (post-matching version)

This builds on Phase 3's participant dashboard foundation and enables the core Secret Santa experience after admin has matched participants.

Questions?

• Review the Project Overview for product vision
• Check the Backlog for user stories
• See v0.2.0 Design for foundation architecture
• Consult existing ADRs for architectural context

---

Phase 3 Design Status: ✅ Complete and Ready for Implementation