Skip to main content

Battle.net Character Sync - Feature Complete ✅

Completed: February 2, 2026

Summary​

Implemented a full-featured Battle.net character synchronization system with real-time WebSocket progress tracking, background job processing, and comprehensive error handling.

What Was Built​

Backend​

  1. SyncCharactersFromBattleNetUseCase

    • Fetches user's WoW characters from Battle.net API
    • Creates/updates characters in database
    • Deduplicates by (battleNetId, realm)
    • Queues background enrichment jobs
    • Returns sync session ID for tracking

  2. CharacterEnrichmentProcessor

    • Background Bull queue processor
    • Fetches character avatars and profile data
    • Emits real-time WebSocket progress updates
    • Handles failures gracefully with retries
    • Character-by-character status tracking

  3. CharacterSyncGateway

    • WebSocket gateway for real-time updates
    • Events: sync-progress, sync-complete, sync-error
    • Room-based subscriptions per session
    • Sends current character being processed

  4. CharacterSyncSession Model

    • Tracks sync progress in database
    • Fields: status, totalCharacters, processedCharacters, failedCharacters
    • User-specific sessions
    • Used for resume/recovery

Frontend​

  1. useCharacterSync Hook

    • WebSocket client integration
    • Auto-connects on active sync detection
    • Methods: startSync(), joinSession(), reset()
    • Returns: progress, error, isConnected, isSyncing, isComplete

  2. CharacterSyncProgress Component

    • Real-time progress bar with percentage
    • Current character display with animated status icons
    • Processing: spinning arrow (blue)
    • Completed: check circle (green)
    • Failed: X circle (red)
    • Smooth fade-in animations

  3. RTK Query Integration

    • syncCharacters mutation
    • enrichCharacter mutation (single character)
    • getActiveSync query
    • Automatic cache invalidation on completion

API Endpoints​

  • POST /api/v1/characters/sync - Batch sync all characters
  • POST /api/v1/characters/:id/enrich - Enrich single character
  • GET /api/v1/characters/sync/active - Get active sync session
  • GET /api/v1/characters/sync/:sessionId - Get session details
  • PATCH /api/v1/characters/sync/:sessionId/complete - Manual completion

Features​

  • ✅ Real-time character-by-character progress tracking
  • ✅ WebSocket-based updates (no polling)
  • ✅ Background avatar fetching
  • ✅ Single character enrichment
  • ✅ Batch character sync
  • ✅ Multi-game version support (retail, classic, SoD, etc.)
  • ✅ Character deduplication
  • ✅ Reactivation of archived characters
  • ✅ Encrypted Battle.net token handling
  • ✅ Retry logic with exponential backoff
  • ✅ Full i18n support
  • ✅ Consistent UX between batch and single sync

Technical Highlights​

External API Integration Pattern​

Created reusable BaseApiAdapter pattern for external APIs:

  • BattleNetAdapter - Battle.net API ACL
  • RaiderIOAdapter - Raider.IO API ACL (future)
  • Standardized error handling
  • Token management
  • Rate limiting support

Real-Time Architecture​

flowchart TD
    A[User] --> B[API]
    B --> C[UseCase]
    C --> D[Create Session]
    C --> E[Queue Jobs]
    E --> F[Processor]
    F --> G[WebSocket]
    G --> H[Frontend]
    F --> I[Update Session]

Performance​

  • Lightweight initial sync (basic data only)
  • Background enrichment (avatars/profile)
  • Bulk job queuing
  • Parallel processing via Bull
  • Database session tracking

Files Modified/Created​

Backend​

  • apps/api/src/domains/character/application/use-cases/sync-characters-from-battlenet.use-case.ts
  • apps/api/src/jobs/character-enrichment.processor.ts
  • apps/api/src/domains/character/gateways/character-sync.gateway.ts
  • apps/api/src/domains/character/character.controller.ts
  • apps/api/src/common/external-api/base-api-adapter.ts
  • apps/api/src/common/external-api/battle-net-adapter.ts
  • apps/api/prisma/schema.prisma (CharacterSyncSession model)

Frontend​

  • apps/web/src/hooks/useCharacterSync.ts
  • apps/web/src/hooks/useWebSocket.ts
  • apps/web/src/components/CharacterSyncProgress.tsx
  • apps/web/src/store/api/charactersApi.ts
  • apps/web/src/routes/characters/index.tsx
  • apps/web/src/routes/characters/-CharacterCard.tsx
  • apps/web/src/locales/en/character.json
  • apps/web/src/locales/en/common.json

Documentation​

  • docs/docs/systems/character-sync.md
  • docs/sidebars.ts

Commits​

Total: ~30 commits Key milestones:

  1. External API adapter pattern
  2. Battle.net character sync use case
  3. WebSocket gateway and progress tracking
  4. Frontend hooks and components
  5. Single-character enrichment
  6. Bug fixes (deduplication, template enum, inactive characters)
  7. i18n translations
  8. Documentation

Testing Notes​

  • Tested with 6-character Battle.net account
  • Tested Classic Season of Discovery (classic_sod)
  • Verified WebSocket real-time updates
  • Confirmed avatar fetching from Battle.net
  • Tested single-character enrichment
  • Verified deduplication logic
  • Confirmed inactive character handling

Manual Notion Update Required​

Action needed: Update the following task(s) in Notion to "Done" status:

  • Battle.net Character Sync implementation
  • Real-time progress tracking with WebSockets
  • Character enrichment background jobs

Next Steps​

See remaining TODOs:

  1. Remove duplicate updateRole endpoint from Guild controller (1 pt)
  2. Migrate findOne to DDD - GetGuildDetailUseCase (1 pt)

Notes​

This feature serves as a template for future external API integrations:

  • Use the BaseApiAdapter pattern
  • Follow the sync session + background job pattern
  • Use WebSocket for real-time progress
  • Keep frontend and backend sync consistent