Family Member Management Flow - Business Rules & Test Cases
Flow Overview
The Family Member Management system enables family owners and administrators to manage family membership, send invitations, track invitation status, and handle member permissions within Story Flow family groups.
Flow Types
- Member Management: Adding, removing, and managing existing family members
- Invitation Management: Sending, canceling, and tracking family invitations
- Permission Management: Role-based access control for family features
Core Principles
- Security First: All actions require proper authentication and authorization
- Audit Trail: Complete history of all member management actions
- Clear Status: Transparent invitation states and member permissions
- User-Friendly: Intuitive interface for complex family management tasks
User Journey Mapping
- Access Members Page: Navigate from family overview to member management
- View Current State: See current members and pending invitations
- Manage Invitations: Send new invitations, cancel pending ones
- Manage Members: Update roles, remove members
- Handle Responses: Process invitation acceptance/rejection
Step-by-Step Business Rules
Step 1: Access Member Management
BR-FMM-001: Member Management Access
- Rule: Only family members with appropriate permissions can access member management
- Implementation: Check user membership and permissions before displaying page
- Test: Verify unauthorized users receive 403 error
- Rationale: Protect family privacy and prevent unauthorized access
BR-FMM-002: Permission Levels
- Rule: Different roles have different management capabilities
- Owner: Full access to all member management features
- Admin: Can invite/remove members, update roles (except owner)
- Contributor: Can view members only
- Viewer: Can view members only
- Implementation: Role-based UI rendering and API enforcement
- Test: Verify each role sees appropriate interface and API permissions
- Rationale: Hierarchical permission model ensures proper governance
Step 2: Current Members Display
BR-FMM-003: Member Information Display
- Rule: Display comprehensive member information including profile, role, join date
- Implementation: Fetch member data with profile information from database
- Test: Verify all member fields display correctly
- Rationale: Transparency in family membership for administrative purposes
BR-FMM-004: Real-time Member Count
- Rule: Display accurate, up-to-date member count including pending invitations
- Implementation: Real-time calculation of active members + pending invitations
- Test: Verify count updates when members join/leave or invitations sent
- Rationale: Accurate information for subscription limit tracking
Step 3: Invitation Management
BR-FMM-005: Send New Invitations
- Rule: Authorized users can send invitations with specific roles
- Implementation: Validate email, check for existing invitations, send email
- Test: Verify invitation creation, email sending, and duplicate prevention
- Rationale: Controlled expansion of family membership
BR-FMM-006: Invitation Status Tracking
- Rule: All invitation states must be clearly visible and accurate
- Pending: Sent but not responded to
- Accepted: User joined the family
- Rejected: User declined the invitation
- Cancelled: Family admin cancelled the invitation
- Expired: Invitation passed expiration date
- Implementation: Status calculation based on database timestamps
- Test: Verify status transitions and display accuracy
- Rationale: Clear visibility into invitation lifecycle
BR-FMM-007: Cancel Pending Invitations
- Rule: Family admins can cancel pending invitations
- Implementation: Update invitation with cancelled_at timestamp and cancelled_by user
- Test: Verify cancellation prevents invitation acceptance
- Rationale: Allow correction of mistakes and revocation of access
BR-FMM-008: Invitation Expiration
- Rule: Invitations expire after 7 days and cannot be accepted
- Implementation: Check expires_at timestamp during invitation validation
- Test: Verify expired invitations show appropriate error message
- Rationale: Security measure to prevent stale invitation links
Step 4: Member Role Management
BR-FMM-009: Role Updates
- Rule: Family admins can update member roles within their permission level
- Implementation: Validate role transition permissions before update
- Test: Verify role updates work correctly and unauthorized changes are blocked
- Rationale: Flexible permission management while maintaining security
BR-FMM-010: Owner Transfer Restrictions
- Rule: Owner role can only be transferred by current owner, and family must have exactly one owner
- Implementation: Special validation for owner role transfers
- Test: Verify owner transfer process and prevention of multiple owners
- Rationale: Maintain clear family leadership and prevent orphaned families
Step 5: Member Removal
BR-FMM-011: Member Removal Authorization
- Rule: Family admins can remove members, but owners cannot be removed (only transferred)
- Implementation: Check removal permissions and handle owner special case
- Test: Verify removal authorization and owner protection
- Rationale: Protect family integrity while allowing member management
BR-FMM-012: Self-Removal (Leave Family)
- Rule: Members can remove themselves from families (except owners)
- Implementation: Allow self-removal with appropriate confirmations
- Test: Verify self-removal works and data cleanup occurs
- Rationale: User autonomy while protecting family structure
Navigation Rules
Page Access
- Navigate from family overview via “Manage Members” button
- Breadcrumb: Families > [Family Name] > Members
- Back button returns to family overview
Tab Navigation
- Members Tab: Current active family members
- Pending Tab: Outstanding invitations
- History Tab: Completed invitation history (optional)
Error Handling
- Invalid family ID: Redirect to families list
- Insufficient permissions: Show error message with explanation
- Network errors: Retry mechanism with user feedback
Data Persistence
Database Tables
- family_members: Active family membership records
- family_invitations: Invitation lifecycle tracking
- family_member_audit: Complete action history
State Management
- React Query for server state management
- Local state for UI interactions
- Real-time updates for invitation status changes
Caching Strategy
- Cache member data with React Query
- Invalidate cache on member changes
- Optimistic updates for better UX
API Integration
Member Management Endpoints
GET /api/families/[familyId]/members // Get family members
PUT /api/families/[familyId]/members/[id] // Update member role
DELETE /api/families/[familyId]/members/[id] // Remove member
``` -->
### Invitation Management Endpoints
```typescript
GET /api/families/[familyId]/invitations // Get pending invitations
POST /api/families/[familyId]/invitations // Send invitation
DELETE /api/families/[familyId]/invitations/[id] // Cancel invitation
POST /api/families/[familyId]/invitations/[id]/resend // Resend invitation
``` -->
### Error Handling
- **401 Unauthorized**: User not authenticated
- **403 Forbidden**: Insufficient permissions
- **404 Not Found**: Family or member not found
- **409 Conflict**: Duplicate invitation or constraint violation
- **422 Unprocessable**: Validation errors
## Test Case Categories
### Critical Path Testing
- **TC-FMM-001**: Complete invitation flow (send → accept → join)
- **TC-FMM-002**: Cancel invitation before acceptance
- **TC-FMM-003**: Update member role successfully
- **TC-FMM-004**: Remove family member
### Integration Testing
- **TC-FMM-005**: Member management with subscription limits
- **TC-FMM-006**: Email notification integration
- **TC-FMM-007**: Timeline event logging
- **TC-FMM-008**: Real-time updates across sessions
### Error Scenarios
- **TC-FMM-009**: Expired invitation acceptance attempt
- **TC-FMM-010**: Cancelled invitation acceptance attempt
- **TC-FMM-011**: Unauthorized role update attempt
- **TC-FMM-012**: Duplicate invitation prevention
### Edge Cases
- **TC-FMM-013**: Invitation to existing family member
- **TC-FMM-014**: Owner attempting to remove themselves
- **TC-FMM-015**: Multiple simultaneous role updates
- **TC-FMM-016**: Network failure during invitation send
## Business Metrics
### Success Metrics
- Invitation acceptance rate
- Time from invitation to acceptance
- Member engagement after joining
- Family growth rate
### Error Metrics
- Failed invitation sends
- Cancelled invitation rate
- Permission violation attempts
- User confusion incidents
### Performance Metrics
- Page load time
- API response time
- Real-time update latency
- Search/filter performance
## Security Considerations
### Access Control
- JWT token validation for all requests
- Role-based authorization enforcement
- Family membership verification
### Data Protection
- Email address validation and sanitization
- Audit trail for all sensitive actions
- Secure token generation for invitations
### Rate Limiting
- Invitation sending rate limits
- API request throttling
- Abuse prevention measures
## User Experience Requirements
### Loading States
- Skeleton screens for member lists
- Progress indicators for actions
- Optimistic updates where possible
### Error States
- Clear error messages for each failure type
- Recovery suggestions for users
- Retry mechanisms for transient failures
### Empty States
- Guidance for families with no members
- Call-to-action for sending first invitation
- Helpful tips for new family administrators
## Future Enhancements
### Planned Features
- Bulk invitation management
- Member role templates
- Advanced permission customization
- Integration with external contact systems
### Scalability Considerations
- Pagination for large families
- Search and filtering improvements
- Real-time collaboration features
- Mobile-responsive design