Skip to main content

DDD Ubiquitous Language

This document defines the ubiquitous language for each bounded context, ensuring consistent terminology across code, documentation, and team communication.

Guild Management Context​

Guild Management - Terms​

Guild​

  • A group of players organized for cooperative gameplay
  • Can be Blizzard-synced (WoW guilds) or Standalone (template-based, manually managed)
  • Has identity: name, realm, faction
  • Contains settings, roles, and members

Realm​

  • The game server where a guild exists
  • For Blizzard-synced guilds: actual WoW realm name
  • For standalone guilds: "N/A" or custom identifier

Faction​

  • The allegiance of a guild: alliance or horde
  • Inherited from the founding character's faction

Sync Source​

  • How a guild's roster is managed:
    • blizzard: Roster synced from Battle.net API
    • standalone: Manually managed, no external sync

Role​

  • A position within the guild hierarchy (e.g., Guild Master, Officer, Raider, Member)
  • Contains permissions defining what actions the role can perform
  • Blizzard-synced guilds: Roles map to WoW ranks (0-9, where 0 = Guild Master)
  • Standalone guilds: Custom roles with no WoW rank mapping

WoW Rank​

  • Numeric rank from World of Warcraft (0-9)
  • Lower number = higher authority (0 = Guild Master)
  • Only applies to Blizzard-synced guilds

Founder Role​

  • The initial Guild Master role created at guild creation
  • Cannot be deleted (prevents guilds from becoming leaderless)
  • Marked with isFounder: true

Archive​

  • Soft-delete a guild (marks active: false, sets archivedAt)
  • Archived guilds are hidden by default but can be restored
  • Preserves all data and relationships

Restore​

  • Unarchive a guild (marks active: true, clears archivedAt)
  • Makes the guild visible and active again

Hard Delete​

  • Permanently delete a guild from the database
  • Only allowed for standalone guilds
  • Cascades to all related data (roles, memberships, events)

Logo Management​

  • Synced Logo: Guild emblem from Battle.net API
  • Custom Logo: User-uploaded image
  • Use Custom Logo: Toggle between synced and custom logo
  • Standalone guilds only have custom logos

Guild Settings​

  • JSON object containing feature flags and preferences:
    • template: Character template (wow, ffxiv, gw2, custom)
    • allowCrossFranchise: Allow characters from different games
    • privacy: Guild visibility settings (future)

Guild Management - Verbs​

  • Create Guild: Establish a new guild with a founding character as Guild Master
  • Archive Guild: Soft-delete a guild (can be restored)
  • Restore Guild: Reactivate an archived guild
  • Delete Guild: Permanently remove a standalone guild
  • Update Settings: Modify guild configuration
  • Upload Logo: Add a custom guild emblem
  • Toggle Logo: Switch between synced and custom logo
  • Define Role: Create a new role with permissions
  • Update Role: Change role name or permissions

Member Management Context​

Member Management - Terms​

Membership​

  • The link between a Character and a Guild
  • Represents a character's membership in a guild with a specific role and status
  • One character can have multiple memberships (in different guilds)

Membership Status​

  • Current state of a member within the guild:
    • trial: New member on probation
    • active: Full member in good standing
    • benched: Temporarily not participating in activities
    • removed: No longer a member

Role Assignment​

  • Linking a membership to a specific guild role
  • Determines the member's permissions within the guild

Role Change History​

  • Audit trail of role changes for a membership
  • Tracks:
    • Previous role
    • New role
    • Who made the change (or "system" if automatic)
    • When it happened
    • Optional reason

Joined Date (firstSyncedAt)

  • When the character first joined the guild
  • Set at membership creation

Left Date (leftAt)

  • When the character left the guild
  • Soft-delete mechanism (null = still a member)

Member Management - Verbs​

  • Add Member: Create a new membership (manual addition to standalone guilds)
  • Remove Member: Soft-delete a membership by setting leftAt
  • Assign Role: Link a membership to a specific guild role
  • Change Role: Update a member's role (tracked in history)
  • Promote: Assign a member to a higher-authority role
  • Demote: Assign a member to a lower-authority role
  • Set Status: Update membership status (trial → active → benched → removed)

Member Management - Rules​

  • Cannot manually add/remove members from Blizzard-synced guilds
  • Role changes are always tracked in history
  • Memberships are soft-deleted (never hard-deleted)

Roster Sync Context​

Roster Sync - Terms​

Guild Member (distinct from Membership)

  • Lightweight roster entry from external sync (Battle.net API)
  • Represents a character as it appears in the game's guild roster
  • Not directly linked to user accounts until "claimed"

Roster​

  • The list of characters in a guild as reported by Battle.net
  • Includes character name, realm, and WoW rank

Roster Sync​

  • The process of fetching guild roster data from Battle.net
  • Runs on schedule (daily at 3 AM)
  • Updates/creates GuildMember entries

Claim​

  • Linking a GuildMember (roster entry) to a Character (user-owned)
  • Establishes ownership: "This roster entry is my character"
  • One-to-one relationship (one character claims one roster entry)

Auto-Claim​

  • Automatic linking of a GuildMember to an existing Character
  • Happens during sync if name/realm match and character isn't already claimed

Unclaimed Roster Entry​

  • A GuildMember that no user has claimed ownership of yet
  • Visible in roster but not linked to any user account

Last Seen In Roster​

  • Timestamp of when a character was last observed in Battle.net roster
  • Updated every sync

Left Guild​

  • When a character no longer appears in the roster during sync
  • Marked with leftGuildAt timestamp

Avatar​

  • Character portrait/image from Battle.net
  • Fetched asynchronously via background job queue

Roster Sync - Verbs​

  • Sync Roster: Fetch current guild roster from Battle.net
  • Upsert Member: Create or update a GuildMember entry
  • Claim Member: Link a roster entry to a user-owned character
  • Auto-Claim: Automatically link matching roster entries during sync
  • Mark As Left: Set leftGuildAt when character no longer in roster
  • Fetch Avatar: Queue background job to retrieve character portrait

Roster Sync - Rules​

  • Roster entries are created/updated from external source (read-only from user perspective)
  • Only Blizzard-synced guilds have roster entries
  • Claiming requires character ownership verification
  • Requires valid Battle.net access token from at least one guild member

Event Scheduling Context​

Event Scheduling - Terms​

Event​

  • A scheduled guild activity (raid, mythic+, social, PvP)
  • Has a type, title, scheduled time, and metadata

Event Type​

  • Category of event:
    • raid: PvE raid content
    • mythic_plus: Mythic+ dungeon runs
    • social: Guild gatherings, meetings
    • pvp: Player vs Player activities

Participation​

  • A user's involvement in an event
  • Tracks invitation, confirmation, and attendance

Participation Status​

  • Current state of a user's participation:
    • invited: User has been invited
    • confirmed: User confirmed they'll attend
    • attended: User showed up (marked by officer)
    • benched: User was on standby
    • absent: User didn't show up (no-show)

Event Metadata​

  • JSON object with event-specific details:
    • difficulty: Raid difficulty (normal, heroic, mythic)
    • instance: Which raid/dungeon
    • notes: Additional information

Event Creator​

  • The user who created the event
  • Typically an officer or raid leader

Event Scheduling - Verbs​

  • Schedule Event: Create a new event with date/time
  • Invite Member: Add a participation with invited status
  • Confirm Attendance: User confirms they'll attend
  • Mark Attended: Officer marks user as present
  • Mark Absent: Officer marks user as no-show
  • Bench Member: Place user on standby

Event Scheduling - Rules​

  • Events belong to a guild
  • Events must have a creator
  • Participations track individual users (not characters)
  • Attendance data used for trial evaluation

Identity & Authentication Context​

Identity & Authentication - Terms​

User​

  • A real human using the platform
  • Authenticated via OAuth (Battle.net, Discord)
  • Can own multiple characters

Character​

  • A player avatar in a game (WoW, FFXIV, GW2, custom)
  • Owned by a user
  • Can be Blizzard-synced or manually created

Sync Source (Character)

  • How the character was created:
    • blizzard: Synced from Battle.net API
    • manual: Manually created in the app

Character Template​

  • The type of character: wow, wow_classic, ffxiv, gw2, custom
  • Determines available attributes (class, race, level, etc.)
  • Extensible for new games

Battle.net ID​

  • Unique identifier from Battle.net API
  • Used for character sync and OAuth

Discord ID​

  • Unique identifier from Discord
  • Used for Discord OAuth integration

OAuth Tokens​

  • Access token, refresh token, and expiry
  • Encrypted at rest for security
  • Required for Battle.net API calls

Display Name​

  • User's visible name on the platform
  • Set from OAuth provider (Battle.net or Discord)

Active Character​

  • Character that is not deleted/transferred
  • Marked with active: true

Identity & Authentication - Verbs​

  • Authenticate: Log in via OAuth (Battle.net or Discord)
  • Create Character: Manually create a character
  • Sync Character: Fetch character data from Battle.net
  • Deactivate Character: Mark character as inactive (server transfer, deletion)
  • Refresh Token: Get new access token using refresh token

Identity & Authentication - Rules​

  • Users must authenticate to access the platform
  • OAuth tokens are encrypted at rest
  • Battle.net ID and Discord ID are unique per user
  • One user can own multiple characters
  • Characters can only be claimed by their owner

Cross-Context Terms​

These terms are used across multiple contexts and have shared meanings:

Aggregate​

  • A cluster of domain objects treated as a single unit for data changes
  • Has a root entity and boundary

Aggregate Root​

  • The main entity in an aggregate
  • Controls access to aggregate internals
  • Enforces invariants

Value Object​

  • Immutable object defined by its attributes (no identity)
  • Examples: GuildSettings, OAuthTokens, EventType

Entity​

  • Object with identity that persists over time
  • Examples: Guild, User, Character, Membership

Domain Event​

  • Something that happened in the domain that domain experts care about
  • Examples: GuildCreated, MemberJoined, RosterSynced (future)

Invariant​

  • A business rule that must always be true
  • Enforced by the aggregate root

Repository​

  • Interface for accessing and persisting aggregates
  • Abstracts database details from domain logic

Anti-Patterns to Avoid​

Don't Say​

  • "User" when you mean "Character" (users own characters, characters have memberships)
  • "Delete" when you mean "Archive" (use soft-delete by default)
  • "Permission" when you mean "Role" (roles have permissions)
  • "Rank" without context (WoW rank vs. custom role priority)
  • "Member" without context (Membership vs. GuildMember are different!)

Do Say​

  • "Membership" for the character-guild-role link
  • "GuildMember" for the lightweight roster entry
  • "Archive" for soft-delete of guilds
  • "WoW Rank" for the numeric 0-9 rank from Blizzard
  • "Role" for the guild position with permissions

Usage in Code​

The ubiquitous language should appear consistently in:

  • Class names: Guild, Membership, GuildMember, ParticipationStatus
  • Method names: archiveGuild(), assignRole(), claimRosterEntry()
  • Variable names: syncSource, wowRank, useCustomLogo
  • Comments and documentation
  • API endpoint names: /guilds/:id/archive, /memberships/:id/assign-role
  • Domain events: GuildCreated, MemberJoined, RosterSynced

This ensures that developers, stakeholders, and documentation all speak the same language.