Skip to main content

DDD Bounded Contexts

This document defines the bounded contexts for the Guild Platform, identifying clear domain boundaries for eventual microservice extraction.

Overview​

The Guild Platform is organized into five primary bounded contexts, each with clear responsibilities and boundaries.

1. Guild Management Context​

Responsibility: Managing guild lifecycle, settings, roles, and permissions.

Aggregate Root: Guild - Central aggregate containing guild identity, settings, and configuration

Entities: Guild (root), Role, GuildSettings (value object)

Key Responsibilities:

  • Guild creation (standalone or Blizzard-synced)
  • Guild archival and restoration
  • Role definition and hierarchy management
  • Logo management (synced vs custom)
  • Permission management
  • Guild settings configuration (templates, cross-franchise support)

Business Rules:

  • Blizzard-synced guilds map WoW ranks to roles
  • Standalone guilds use custom roles
  • Founder roles cannot be deleted
  • Guild Master role is required at creation
  • Only standalone guilds can be permanently deleted

Outbound Dependencies: None (this is the core context)

Inbound Dependencies: Member Management (queries guild roles and permissions), Event Scheduling (links events to guilds), Roster Sync (updates guild roster data)

2. Member Management Context​

Responsibility: Managing character memberships within guilds, role assignments, and membership lifecycle.

Aggregate Root: Membership - Links Character to Guild with role and status

Entities: Membership (root), Character (reference to Identity context), MembershipStatus (value object), RoleAssignmentHistory (entity)

Key Responsibilities:

  • Adding/removing members from guilds
  • Assigning roles to members
  • Tracking membership status (trial, active, benched, removed)
  • Role change history tracking
  • Membership lifecycle management (joined, left dates)

Business Rules:

  • Cannot manually add/remove members from Blizzard-synced guilds
  • Role changes are tracked in history with timestamp and actor
  • Soft delete via leftAt timestamp
  • One character can have multiple memberships (different guilds)
  • Character must exist before membership creation

Outbound Dependencies: Guild Management (validates guild exists, checks sync source), Identity Context (validates character ownership)

Inbound Dependencies: Event Scheduling (participations reference users through characters)

3. Roster Sync Context​

Responsibility: Synchronizing guild rosters from external sources (Battle.net API) and managing lightweight roster entries.

Aggregate Root: GuildMember - Lightweight roster entry from external sync

Entities: GuildMember (root), ClaimStatus (value object)

Key Responsibilities:

  • Syncing guild rosters from Battle.net
  • Creating/updating lightweight roster entries
  • Character claiming (linking roster entries to user-owned characters)
  • Auto-claiming characters when sync finds matches
  • Tracking when characters leave the guild
  • Avatar fetching via background jobs

Business Rules:

  • Roster entries are immutable snapshots from external sources
  • Characters can claim roster entries to establish ownership
  • Only one character can claim a roster entry
  • Roster sync runs on schedule (daily at 3 AM)
  • Characters that disappear from roster are marked with leftGuildAt
  • Requires valid Battle.net access token from at least one guild member

Outbound Dependencies: Guild Management (updates guild's lastRosterSync), Member Management (auto-claims link to Character), External API Context (Battle.net API)

Inbound Dependencies: None (operates independently on schedule)

4. Event Scheduling Context​

Responsibility: Managing scheduled guild activities and tracking participation.

Aggregate Root: Event - Scheduled guild activity

Entities: Event (root), Participation (entity within Event aggregate), EventType (value object), ParticipationStatus (value object)

Key Responsibilities:

  • Creating guild events (raids, mythic+, social, PvP)
  • Tracking event metadata (difficulty, instance, notes)
  • Managing invitations and confirmations
  • Recording attendance
  • Tracking no-shows and absences

Business Rules:

  • Events must belong to a guild
  • Events must have a creator (user)
  • Participations track individual user involvement
  • Participation status flow: invited → confirmed → attended/absent
  • Events can be benched (for roster management)

Outbound Dependencies: Guild Management (validates guild exists), Identity Context (links creator and participants)

Inbound Dependencies: Member Management (uses membership data for attendance metrics)

5. Identity & Authentication Context​

Responsibility: Managing user identity, OAuth authentication, and character ownership.

Aggregate Root: User - Represents a real human with authentication credentials

Entities: User (root), Character (entity, but potential separate aggregate), OAuthTokens (value object)

Key Responsibilities:

  • User authentication (Battle.net OAuth, Discord OAuth)
  • Token management (access, refresh, expiry)
  • Character ownership linkage
  • User profile management
  • Last login tracking

Business Rules:

  • Users can authenticate via Battle.net or Discord
  • OAuth tokens are encrypted at rest
  • One user can own multiple characters
  • Characters can be manually created or synced from Battle.net
  • Battle.net ID and Discord ID are unique per user

Outbound Dependencies: External API Context (OAuth providers)

Inbound Dependencies: Member Management (characters belong to users), Event Scheduling (participations and event creation), Guild Management (guild creation requires character ownership)

6. External API Integration Context​

Responsibility: Managing integrations with third-party APIs (Battle.net, Discord, Raider.IO, etc.)

Aggregate Root: None (this is an infrastructure/anti-corruption layer)

Key Responsibilities:

  • Battle.net API integration (roster, character data, OAuth)
  • Discord API integration (identity, future features)
  • Rate limiting and circuit breaking
  • Response caching
  • Error handling and fallback strategies
  • Token refresh logic

Business Rules:

  • All external API calls must be cached
  • Never fetch third-party data synchronously during user requests
  • Background jobs handle ingestion and refresh
  • Expect rate limits and partial failures
  • Treat external APIs as unreliable

Outbound Dependencies: None (this is the boundary layer)

Inbound Dependencies: Roster Sync (uses Battle.net roster API), Identity Context (uses OAuth APIs)

Context Map​

Relationships​

flowchart TD
    A["Identity & Authentication"] --> B["Guild Management<br/>(Core Domain)"]
    B --> C[Member Management]
    B --> D[Event Scheduling]
    C -->|references| E[Roster Sync]
    D -->|references| E
    E --> F[External API Integration]
    F -->|references| A

Integration Patterns​

  • Shared Kernel: User, Character IDs shared across contexts
  • Customer/Supplier:
    • Guild Management supplies to Member Management
    • Identity Context supplies to all contexts
  • Anti-Corruption Layer: External API Integration protects domain from third-party schemas
  • Published Language: Domain events for cross-context communication (future)

Migration Strategy​

Phase Priorities​

  1. Phase 1 (Current): Document contexts and boundaries ✅
  2. Phase 2: Create domain layer structure per context
  3. Phase 3: Migrate Guild Management to rich domain models
  4. Phase 4: Implement Repository Pattern for isolation
  5. Phase 5: Add Domain Events for cross-context communication
  6. Phase 6: Extract contexts into separate NestJS modules with clear boundaries
  7. Phase 7: Prepare for microservice extraction (API contracts, message broker)

Microservice Extraction Order​

When ready to extract microservices:

  1. External API Integration - Already isolated, minimal dependencies
  2. Roster Sync - Scheduled job, clear boundary, uses External API
  3. Event Scheduling - Clear aggregate boundary, minimal cross-context dependencies
  4. Member Management - Depends on Guild Management and Identity
  5. Guild Management - Core domain, extract last

Notes​

  • Standalone Guilds: Template-based guilds (FFXIV, GW2, custom) that don't sync with external APIs
  • Blizzard-Synced Guilds: WoW guilds that sync roster data from Battle.net
  • The current codebase already has good separation in the domains/ folder
  • Focus on making domain logic explicit and moving it into entities