Skip to content

Character Import and Update System Design

This document outlines the design for the character import and update system in StingbatBot, focusing on syncing with Shadowdarklings as the source of truth.

Overview

The system allows users to: - Import new characters from JSON files or URLs (primarily from Shadowdarklings) - Update existing characters from their source URLs or JSON files - Maintain character data for use in the bot - Automatically handle re-imports as updates when a character with the same name, ancestry, and class already exists

Immediate Goal: Character Updates

Current Focus

The immediate implementation priority is to enable users to update their existing characters from Shadowdarklings:

  • Users create and modify their characters on Shadowdarklings (level ups, equipment changes, etc.)
  • The bot serves as a tool for using these characters in Discord (rolling attacks, spells, etc.)
  • The !update command syncs the bot's character data with the latest from Shadowdarklings or a provided JSON file
  • Re-importing an existing character automatically triggers the update process

Character Storage

Characters are stored in two ways: 1. Source JSON: The complete, unmodified JSON from Shadowdarklings 2. Parsed Representation: A processed version used by the bot's systems

Version Management

For update tracking, characters will use a simple version number:

  1. Import Creates V1: Initial import creates version 1 with approval timestamp
  2. Update Creates New Version: Each update creates a new unapproved version
  3. Approval Process: Updates use the same approval pattern as imports:
  4. New version is created without approval timestamp
  5. User approves: approval timestamp is set
  6. User rejects: new version is deleted
  7. Version Field: A simple integer field on the character schema tracks the current version
  8. Timeout Handling:
  9. Unapproved versions automatically timeout after 5 minutes
  10. On timeout: character is deleted and user is notified
  11. Prevents accumulation of unapproved versions
  12. Single Unapproved Version:
  13. Only one unapproved version allowed per character
  14. Before creating new version, any existing unapproved versions are deleted
  15. Prevents confusion from multiple pending updates
  16. Re-import Handling:
  17. When importing, check if character with same name/ancestry/class exists
  18. If exists: treat as an update instead of a new import
  19. Use the same approval process as regular updates
  20. Preserve the character's source URL if not provided in the new data

Character Context Functions

The character context will provide these functions for version management:

  1. Version Management Functions:
  2. get_latest_version/1 - Get current approved version (only returns approved versions)
  3. get_unapproved_version/1 - Get any pending unapproved version
  4. delete_unapproved_versions/1 - Clean up any pending versions
  5. create_new_version/2 - Create new version with incremented number

  6. approve/1 - Set approval timestamp on a version

  7. Existing Functions:

  8. get/1 - Get character by ID
  9. get_by_identity/2 - Get character by user_id and name
  10. delete/1 - Delete character

Update Flow

  1. User runs !update with character JSON
  2. delete_unapproved_versions/1 - Clean up any existing unapproved versions
  3. get_latest_version/1 - Get current approved version
  4. Check if new data is identical to current version
    • If identical: Send message and return
    • If different: Continue with update process

  5. create_new_version/2 - Create new version (current version + 1) with no approval timestamp

  6. User approves the update

  7. get_unapproved_version/1 - Get the unapproved version

  8. approve/1 - Set approval timestamp

  9. User rejects the update

  10. get_unapproved_version/1 - Get the unapproved version

  11. delete/1 - Remove the unapproved version

  12. Update times out

  13. get_unapproved_version/1 - Get the unapproved version
  14. delete/1 - Remove the unapproved version

Re-import Flow

  1. User runs !import with existing character
  2. get_by_identity/2 - Find existing character (existing code)
  3. If found, follow update flow above
  4. If not found, follow import flow

Implementation Notes

  1. Order of Operations:
  2. Always clean up unapproved versions before getting the latest version
  3. This ensures we don't have stale unapproved versions affecting our logic
  4. Check for identical data before creating a new version

  5. Skip version creation and approval process if no changes detected

  6. Version Functions:

  7. get_latest_version/1 only returns approved versions
  8. get_unapproved_version/1 makes the code more readable than using get/1

  9. approve/1 centralizes the approval logic

  10. Error Handling:

  11. All functions should return standard {:ok, result} or {:error, reason} tuples

  12. Consistent error handling makes the code more predictable

  13. Database Transactions:

  14. Consider wrapping related operations in transactions
  15. For example: cleanup + create new version could be atomic

This approach is simpler than a full versioning system because: - We always get the complete character state from Shadowdarklings - We don't need to track individual field changes - The version number serves as a simple counter for updates - Storage is more efficient than storing diffs between versions - We can reuse the same approval pattern as character imports - Users don't need to know the difference between import and update

Implementation Strategy

Initial Implementation

For the immediate implementation, we'll focus on the core update functionality:

  1. Command Structure:
  2. !update with no args updates the selected character
  3. Both variants can accept a JSON file attachment as an alternative data source
  4. If no file is attached, requires that the character has a source URL stored

  5. !import automatically detects and handles re-imports as updates

  6. Update Process:

  7. For URL updates: Fetch JSON from stored source URL
  8. For file updates: Extract and parse JSON from the attachment
  9. Validate and parse as a character
  10. Delete any existing unapproved versions
  11. Create new unapproved version
  12. Show preview for user confirmation

  13. Schedule timeout cleanup

  14. Simple Versioning:

  15. Add version field to character schema
  16. Each update creates new unapproved version
  17. Approval sets timestamp, rejection deletes version

  18. Timeout automatically cleans up unapproved versions

  19. Source Tracking:

  20. Record whether the update came from a URL or file
  21. Maintain the original source URL even when updating from file
  22. Only update the source URL if explicitly provided in the new data

Technical Components

  • Command Handler: Processes the update command with or without attachments
  • HTTP Client: Fetches character data from URLs
  • File Handler: Extracts and validates JSON from attachments
  • Character Parser: Validates and processes character JSON
  • Preview Generator: Shows character info for approval
  • Version Management: Tracks character versions with simple integer field
  • Timeout Handler: Automatically cleans up unapproved versions after 5 minutes
  • Version Cleanup: Ensures only one unapproved version exists per character
  • Re-import Detector: Identifies when an import should be treated as an update
  • Change Detector: Compares new data with current version to avoid unnecessary updates