Skip to main content

27. Dynamic Deck Loading

Status: Accepted Date: 2025-07-06

Context​

The Arcana application supports multiple tarot decks (e.g., Rider-Waite, Thoth). Initially, these decks were hardcoded into the source, meaning that adding, removing, or modifying a deck required changing the application code and redeploying it. This process was inefficient, error-prone, and coupled the application's logic to its content.

Decision​

We will replace the hardcoded deck system with a dynamic loading mechanism. All available tarot decks will be defined in a dedicated configuration file (e.g., decks.json). This file will contain the metadata for each deck, including its name, a description, and the path to its image assets. At startup, the application will read this configuration file to determine the available decks and load them into a central DeckService. This decouples the deck content from the application's business logic.

Consequences​

Positive:

  • Maintainability: Adding or updating a tarot deck is as simple as editing the configuration file and adding the image assets. No code changes are required.
  • Decoupling: The application's core logic is no longer concerned with the specifics of which decks are available. It simply requests a deck by name from the DeckService.
  • Flexibility: This system makes it much easier to add support for new types of decks or even user-submitted decks in the future.

Negative:

  • Layer of Abstraction: This introduces an extra layer of indirection. A misconfiguration in the decks.json file (e.g., a typo in a path) can cause runtime errors that might be harder to debug than a compile-time error from a missing import.
  • Startup Complexity: Adds a small amount of complexity to the application's startup process, as it now needs to parse the configuration and load the decks.

Mitigation:

  • Schema Validation: Use a schema validation library (like Zod) to validate the structure of decks.json at application startup. The application should fail fast with a clear error message if the configuration is invalid.
  • Clear Documentation: Maintain clear documentation for the structure of the decks.json file and the process for adding new decks.
  • Asset Validation: The startup process should include a step to verify that the image asset paths specified in the configuration file actually exist, preventing broken image links.