Feature: User Character Transfer System with Community Permissions

Character Transfer System Implementation

Background

Currently, the application has a basic mutation that immediately transfers character ownership without proper workflow, community permission validation, or ownership change tracking integration.

Current State Analysis

• ✅ Basic GraphQL mutation exists
• ✅ service exists for logging transfers
• ❌ Transfers are immediate (no send/accept workflow)
• ❌ No community permission validation
• ❌ CharacterOwnershipChange logging not integrated with transfers
• ❌ No frontend UI for character transfers
• ❌ No validation for community membership requirements

Requirements

UI Requirements

1. Character Page Owner Actions

• Location: Character page header actions (next to Edit/Delete buttons)
• Component: Add "Transfer Character" button for character owners
• Behavior: Opens transfer modal when clicked
• Permissions: Only visible to character owners

2. Transfer Initiation Modal

• Purpose: Allow character owners to select a recipient and send transfer request
• Components:
  • User search/selection dropdown with community filtering
  • Preview of character being transferred
  • Optional transfer message/note field
  • "Send Transfer Request" confirmation button
• User Selection Logic:
  • For community characters (with species): Only show users with roles in the same community
  • For non-community characters: Show all active users
  • Search functionality with username/display name matching
  • Show user avatar, display name, and username in dropdown

3. Pending Transfers Management

• Location: New section in user dashboard/profile
• Components:
  • Outgoing Requests Tab:
    • List of sent transfer requests awaiting response
    • Character preview, recipient info, request date
    • "Cancel Request" action
  • Incoming Requests Tab:
    • List of received transfer requests
    • Character preview, sender info, request date, optional message
    • "Accept" and "Decline" actions
    • Character details expansion for review

4. Transfer History/Logs

• Location: Character page sidebar or separate tab
• Purpose: Show ownership history using existing CharacterOwnershipChange data
• Components:
  • Timeline view of ownership changes
  • Previous owner → current owner with timestamps
  • Filter by date range

5. Notifications/Alerts

• Transfer Request Sent: Toast notification confirming request sent
• Transfer Request Received: In-app notification + optional email
• Transfer Completed: Toast notification for both parties
• Transfer Declined: Toast notification to sender

Backend Requirements

1. New Database Models

CharacterTransferRequest:

2. GraphQL Schema Changes

New Types:
{ is a shell keyword

New Mutations:

New Queries:

3. Service Layer Changes

CharacterTransferService (new service):

• : Create pending transfer request
• : Complete transfer + log ownership change
• : Mark request as declined
• : Allow sender to cancel pending request

Updated CharactersService:

• Update existing method to integrate with CharacterOwnershipChangesService
• Add community permission validation helper methods

4. Permission Validation Logic

Community Permission Checks:

Transfer Request Permissions:

• Only character owners can send transfer requests
• Users can only send one pending request per character
• Recipients must be active users
• Community characters require recipient community membership

5. Integration Requirements

CharacterOwnershipChange Integration:

• Modify transfer completion to create ownership change records
• Include transfer request ID in ownership change for audit trail

Notification System Integration (if exists):

• Send in-app notifications for new transfer requests
• Send email notifications (optional user preference)

Technical Implementation Notes

Frontend Architecture

• State Management: Use Apollo Client for transfer request caching
• Component Structure: Reusable TransferModal component with user selection
• Routing: Add transfer management to user dashboard routes

Backend Architecture

• Module Structure: Create dedicated TransferRequestsModule
• Validation: Use class-validator DTOs for input validation
• Error Handling: Specific error types for permission/validation failures

Database Considerations

• Indexes: Add indexes on characterId, fromUserId, toUserId for transfer requests
• Constraints: Ensure data integrity with proper foreign key relationships
• Migration: Create migration to add new transfer request table

Acceptance Criteria

MVP Requirements

• Character owners can initiate transfer requests through UI
• Recipients can accept/decline requests through dashboard
• Community permission validation enforced
• Ownership change logging integrated
• Basic notification system (toast notifications)

Future Enhancements

• Email notifications for transfer requests
• Batch transfer operations
• Transfer request expiration (auto-decline after X days)
• Transfer request comments/messaging
• Advanced community role-based transfer permissions

Testing Requirements

• Unit tests for permission validation logic
• Integration tests for transfer workflow
• E2E tests for complete UI workflow
• Performance tests for community member queries

Security Considerations

• Validate all user inputs and permissions server-side
• Prevent CSRF attacks on transfer endpoints
• Rate limit transfer request creation to prevent spam
• Audit log all transfer-related actions

Documentation Requirements

• Update API documentation with new endpoints
• Create user guide for character transfer workflow
• Document community permission system for admin users

No concrete files or tests are named. Start by locating the existing GraphQL character-transfer mutation, CharactersService, CharacterOwnershipChangesService, and the character and dashboard entry points; the MVP is complete when the listed initiation, accept/decline, permission, ownership logging, notification, and test requirements are covered.