Skip to main content

28. Token System Migration

Status: Accepted Date: 2025-07-06

Context​

The Arcana application requires a payment system using TARO tokens to charge for tarot readings. A fully-functional, PostgreSQL-based token management module already exists but is located within the Mercury domain (domains/mercury/backend/src/token/), where it is not currently being used. The Arcana domain has a pricing service but no token functionality. This is a historical artifact of shifting project priorities.

Decision​

We will perform a direct migration of the existing token module from the Mercury domain to the Arcana domain. This involves physically moving the module's source code from domains/mercury/backend/src/token/ to domains/arcana/backend/src/token/ and updating all necessary imports and database configurations. This is a pragmatic, short-term solution to make the token payment feature functional in Arcana as quickly as possible, re-using existing, proven code.

This decision explicitly defers creating a shared library (libs/token/) until a second domain requires this functionality, following the YAGNI ("You Ain't Gonna Need It") principle.

Consequences​

Positive:

  • Speed of Implementation: This is the fastest way to enable token payments in Arcana, as it re-uses an entire existing module.
  • Code Re-use: Avoids rewriting the token management logic from scratch.
  • Low Risk: The token module is already written and tested, reducing the risk of introducing new bugs.

Negative:

  • Temporary Code Duplication: This is not a DRY solution at the conceptual level, as the "token" concept is being moved rather than shared.
  • Future Refactoring Required: If another domain needs token functionality in the future, this module will need to be extracted into a shared library, which will require a more significant refactoring effort at that time.

Mitigation:

  • Clear Documentation: This ADR serves as documentation for this pragmatic decision and the future expectation of refactoring.
  • YAGNI Principle: We are consciously choosing to accept the future refactoring cost in exchange for immediate functionality, avoiding the premature abstraction of creating a shared library before it is actually needed.
  • Encapsulation: The token module should be treated as a black box within Arcana, making it easier to extract later if needed.