rehearshalhub/IMPLEMENTATION_PLAN.md

Band Invitation System - Implementation Plan

🎯 Summary

The band invitation system already has a basic implementation but lacks key features for proper invite management. Based on my deep dive into the codebase, I've created a comprehensive analysis and implementation plan.

Status: ✅ Branch created: feature/band-invitation-system

---

📊 What Exists Today

Backend (API)

• ✅ Token-based invites with 72h expiry
• ✅ POST /bands/{id}/invites - Generate invite
• ✅ POST /invites/{token}/accept - Accept invite
• ✅ DELETE /bands/{id}/members/{mid} - Remove member

Frontend (Web)

• ✅ /invite/:token - Accept invite page
• ✅ Copy-to-clipboard for invite links
• ✅ Basic invite generation UI

Database

• ✅ band_invites table with proper schema
• ✅ Relationships with bands and members

---

🔧 What's Missing (Gaps)

Critical (Blocker for Requirements)

Gap	Impact	Priority
List pending invites	Admins can't see who they invited	High
Revoke pending invites	No way to cancel sent invites	High
Search users to invite	Can't find specific members	High

Important (Nice to Have)

Gap	Impact	Priority
Custom expiry times	Can't set longer/shorter expiry	Medium
Bulk invites	Invite multiple people at once	Medium
Invite details endpoint	Get info without accepting	Low

---

🏗️ Implementation Strategy

Phase 1: MVP (1-2 weeks) - CRITICAL FOR REQUIREMENTS

Implement the missing critical features to meet the stated requirements.

Backend Tasks:

1. ✅ GET /bands/{band_id}/invites - List pending invites
2. ✅ DELETE /invites/{invite_id} - Revoke invite
3. ✅ GET /invites/{token}/info - Get invite details
4. ✅ Update BandRepository with new methods
5. ✅ Update BandService with new logic
6. ✅ Update schemas for new return types

Frontend Tasks:

1. ✅ Create InviteManagement component (list + revoke)
2. ✅ Update BandPage with invite management section
3. ✅ Update API wrappers (web/src/api/invites.ts)
4. ✅ Add TypeScript interfaces for new endpoints

Tests:

• Unit tests for new repo methods
• Integration tests for new endpoints
• Permission tests (only admins can manage invites)

Phase 2: Enhanced UX (1 week)

Improve user experience based on feedback.

Backend:

• Bulk invite support
• Custom TTL (time-to-live) for invites
• Email notification integration (optional)

Frontend:

• User search component for finding members
• Bulk selection for invites
• Better invite management UI

Phase 3: Optional Features

Based on user feedback.

• Email notifications
• Invite analytics
• QR code generation

---

📋 Detailed Backend Changes

1. New Endpoint: List Invites

# File: api/src/rehearsalhub/routers/bands.py

@router.get("/{band_id}/invites", response_model=BandInviteList)
async def list_invites(
    band_id: uuid.UUID,
    session: AsyncSession = Depends(get_session),
    current_member: Member = Depends(get_current_member),
):
    """List all pending invites for a band (admin only)"""

Returns: 200 OK with list of pending invites

• invites: Array of invite objects
• total: Total count
• pending: Count of pending (not yet used or expired)

2. New Endpoint: Revoke Invite

# File: api/src/rehearsalhub/routers/bands.py

@router.delete("/invites/{invite_id}", status_code=status.HTTP_204_NO_CONTENT)
async def revoke_invite(
    invite_id: uuid.UUID,
    session: AsyncSession = Depends(get_session),
    current_member: Member = Depends(get_current_member),
):
    """Revoke a pending invite (admin only)"""

Returns: 204 No Content on success Checks: Only band admin can revoke Validates: Invite must be pending (not used or expired)

3. New Endpoint: Get Invite Info

# File: api/src/rehearsalhub/routers/bands.py

@router.get("/invites/{token}/info", response_model=BandInviteRead)
async def get_invite_info(
    token: str,
    session: AsyncSession = Depends(get_session),
):
    """Get invite details without accepting"""

Returns: 200 OK with invite info or 404 Not Found Use case: Show invite details before deciding to accept

4. Enhanced: Create Invite

Update existing endpoint to return full invite info.

---

🎨 Frontend Changes

New Components

1. InviteManagement.tsx

// Location: web/src/components/InviteManagement.tsx
// Purpose: Display and manage pending invites

interface InviteManagementProps {
  bandId: string;
  currentMemberId: string;
}

// Features:
// - List pending invites with details
// - Revoke button for each invite
// - Copy invite link
// - Show expiry timer
// - Refresh list

2. UserSearch.tsx

// Location: web/src/components/UserSearch.tsx
// Purpose: Search for users to invite

interface UserSearchProps {
  onSelect: (user: User) => void;
  excludedIds?: string[];
}

// Features:
// - Search by name/email
// - Show search results
// - Select users to invite

Updated Components

BandPage.tsx

Add two new sections:

1. Invite Management Section (above existing "Members" section)
2. Create Invite Section (above invite link display)

---

🧪 Testing Plan

Unit Tests (Backend)

# test_api_invites.py
test_list_invites_admin_only
test_list_invites_pending_only
test_revoke_invite_admin_only
test_revoke_invite_must_be_pending
test_get_invite_info_valid_token
test_get_invite_info_invalid_token

Integration Tests

# test_band_invites.py
test_create_invite_flow
test_accept_invite_flow
test_invite_expiry
test_invite_revocation
test_multiple_invites_same_band

E2E Tests (Frontend)

// inviteManagement.spec.ts
testInviteListLoadsCorrectly
testRevokeInviteButtonWorks
testCopyInviteLinkWorks
testErrorHandlingForExpiredInvite

---

⚠️ Important Questions

Before proceeding with implementation, I need clarification on:

1. "No link handling needed" requirement

   • Does this mean NO email notifications should be implemented?
   • Or that we should focus on the token-based system first?
   • This affects whether we include email in MVP or Phase 2

2. Expected scale

   • How many members per band?
   • How many invites per band?
   • This affects pagination decisions

3. External invites

   • Should admins be able to invite people who aren't registered yet?
   • Or only registered users?

4. Invite analytics

   • Should we track who invited whom?
   • Should we track invite acceptance rates?

---

🎯 Recommended Next Steps

Option A: Start Implementation (MVP)

If the requirements are clear and we can proceed with a token-based system:

1. Implement Phase 1 backend (2-3 days)
2. Add tests (2 days)
3. Implement frontend (3-4 days)
4. Test and review (2 days)

Total: ~1 week for MVP

Option B: Clarify Requirements First

If we need to decide on email notifications and other optional features:

1. Discuss with stakeholders
2. Finalize MVP scope
3. Then proceed with implementation

---

📝 Files to Create/Modify

Backend (API)

# New/Modified Files:
api/src/rehearsalhub/routers/bands.py          # Add 3 new endpoints
api/src/rehearsalhub/repositories/band.py       # Add list/revoke methods
api/src/rehearsalhub/services/band.py           # Add service methods
api/src/rehearsalhub/schemas/invite.py          # Add new schemas
api/tests/integration/test_api_invites.py       # New test file

Frontend (Web)

# New Files:
web/src/components/InviteManagement.tsx
web/src/components/UserSearch.tsx
web/src/api/invites.ts
web/src/types/invite.ts

# Modified Files:
web/src/pages/BandPage.tsx
web/src/pages/InvitePage.tsx

---

💭 My Recommendation

Based on the analysis:

1. Proceed with MVP implementation (Phase 1) - it addresses the core requirements
2. Start with token-based system (no email) - simpler, fewer dependencies
3. Implement proper permissions - only band admins can manage invites
4. Add comprehensive tests - ensure reliability
5. Get feedback early - test with real users before adding complexity

The current system has a solid foundation. We just need to add the missing management features to make it production-ready.

---

🚀 Ready to Start?

I'm ready to begin implementation. Please clarify:

1. Should we proceed with token-based MVP?
2. Any priority changes to the task list?
3. Are there additional requirements not captured?

Once confirmed, I can start with Phase 1 backend implementation immediately.