chore: add production deployment config and upgrade path requirements
- Add docker-compose.yml and docker-compose.example.yml for production deployment - Add .env.example with all required environment variables - Update architect agent with upgrade path requirements - Update developer agent with migration best practices - Add Phase 3 design documents (v0.3.0) - Add ADR-0006 for participant state management 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
278
docs/designs/v0.3.0/README.md
Normal file
278
docs/designs/v0.3.0/README.md
Normal file
@@ -0,0 +1,278 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user