# 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](overview.md)
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](participant-self-management.md)
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](test-plan.md)
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](implementation-guide.md)
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](../../decisions/0006-participant-state-management.md)
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](../../PROJECT_OVERVIEW.md) for product vision
- Check the [Backlog](../../BACKLOG.md) for user stories
- See [v0.2.0 Design](../v0.2.0/overview.md) for foundation architecture
- Consult existing [ADRs](../../decisions/) for architectural context

---

**Phase 3 Design Status**: ✅ Complete and Ready for Implementation