TarotApp Module System

Overview

The Tarot application has been refactored from a monolithic 559-line file into a modular architecture with clear separation of concerns.

Module Structure

📦 Modules

1. cards.js - Card Database

  • Stores all 78 tarot cards (22 Major Arcana + 4 suits of 14 cards)
  • Provides methods to access and query card data
  • No DOM dependencies

Key Methods:

TarotApp.Cards.getAll()              // Get all 78 cards
TarotApp.Cards.getByIndex(i)         // Get card by position
TarotApp.Cards.getByName(name)       // Get card by name
TarotApp.Cards.isMajorArcana(card)   // Check if card is Major Arcana
TarotApp.Cards.getMajorArcanaCount() // Count Major Arcana in reading

2. spread.js - Spread Configuration

  • Defines available spreads (3-card, 5-card guidance, 5-card love)
  • Maps card positions to position labels and context text
  • Generates summaries based on card composition

Key Methods:

TarotApp.Spread.getAll()             // Get all spreads
TarotApp.Spread.getById(id)          // Get spread by ID
TarotApp.Spread.getCardCount(id)     // Get card count for spread
TarotApp.Spread.getPositionInfo(idx) // Get position label/context
TarotApp.Spread.getSummary(...)      // Get interpretation summary

3. ui.js - Card Display & Interactions

  • Creates card DOM elements with staggered animations
  • Manages card flipping interactions
  • Handles interpretation block clickability

Key Methods:

TarotApp.UI.init(container)          // Initialize with container
TarotApp.UI.createCard(...)          // Create card element
TarotApp.UI.addFlipListener(...)     // Add flip animation handler
TarotApp.UI.areAllCardsFlipped()     // Check if reading complete
TarotApp.UI.addInterpretationListeners() // Add click handlers
TarotApp.UI.clearCards()             // Clear all cards from display

4. modal.js - Card Detail Modal

  • Opens detailed view of cards with both meanings
  • Handles modal interactions (close on ESC, click outside, etc.)
  • Maintains modal state

Key Methods:

TarotApp.Modal.init()                // Initialize modal
TarotApp.Modal.open(cardData)        // Open modal with card
TarotApp.Modal.close()               // Close modal
TarotApp.Modal.isOpen()              // Check modal state

5. reading.js - Reading Logic & State

  • Manages reading state (drawn cards, in progress flag)
  • Implements Fisher-Yates shuffle algorithm
  • Generates HTML interpretation from drawn cards

Key Methods:

TarotApp.Reading.start(spreadId, allowReversals) // Start new reading
TarotApp.Reading.end()               // End current reading
TarotApp.Reading.isInProgress()      // Check if reading in progress
TarotApp.Reading.getDrawnCards()     // Get cards from current reading
TarotApp.Reading.generateInterpretation() // Create HTML output
TarotApp.Reading.getCardById(id)     // Find card in current reading

🎮 Main Orchestrator

tarot-app-refactored.js (or tarot-app.js)

  • Coordinates all modules
  • Handles user interactions (button clicks, etc.)
  • Manages DOM element references
  • Controls reading workflow

Module Dependencies

tarot-app-refactored.js
├── TarotApp.Cards
├── TarotApp.Spread
├── TarotApp.UI
├── TarotApp.Modal
└── TarotApp.Reading

Load Order

Modules must be loaded in this order in your HTML:

<!-- Database and Logic Modules -->
<script src="/js/modules/cards.js"></script>
<script src="/js/modules/spread.js"></script>
<script src="/js/modules/reading.js"></script>

<!-- UI and Interaction Modules -->
<script src="/js/modules/ui.js"></script>
<script src="/js/modules/modal.js"></script>

<!-- Main Orchestrator -->
<script src="/js/tarot-app-refactored.js"></script>

Usage Examples

Draw a Reading

// Start a reading
const result = TarotApp.Reading.start('3', true); // 3-card spread, allow reversals
console.log(result.cardCount); // 3

// Get HTML interpretation
const html = TarotApp.Reading.generateInterpretation("My question?");

// End reading
TarotApp.Reading.end();

Access Card Data

// Get all cards
const deck = TarotApp.Cards.getAll();

// Get specific card
const card = TarotApp.Cards.getByName("O Louco");

// Check if Major Arcana
console.log(TarotApp.Cards.isMajorArcana(card)); // true

Check Spread Info

// Get all spreads
const spreads = TarotApp.Spread.getAll();

// Get card count for spread
const count = TarotApp.Spread.getCardCount('love5'); // 5

// Get position info for card
const position = TarotApp.Spread.getPositionInfo(0, '5');
// { label: "O Coração da Questão", context: "..." }

Open Modal

const cardData = {
    name: "O Louco",
    image: "images/cartas/olouco.png",
    meaning: "...",
    reversedMeaning: "...",
    reversed: false
};

TarotApp.Modal.open(cardData);

Configuration

Reversal Probability

Located in reading.js:

const REVERSAL_PROBABILITY = 0.3; // 30% chance

Card Flip Duration

Located in ui.js:

const CONFIG = {
    CARD_FLIP_DURATION: 900, // ms
    STAGGER_DELAY: 150       // ms between cards
};

Debugging

Check browser console for logs:

// Enable debug mode (add to console)
window.TarotApp = window.TarotApp || {};

// Check module availability
console.log(TarotApp.Cards);   // Should return module object
console.log(TarotApp.Reading); // Should return module object

// Check reading state
console.log(TarotApp.Reading.getDrawnCards());
console.log(TarotApp.Reading.isInProgress());

Migration from Old Code

If upgrading from the original tarot-app.js:

  1. Backup original file
  2. Load new modules in HTML before old main script
  3. Replace references from old code to use new APIs
  4. Test thoroughly

Example migration:

// OLD
const cards = [...]; // 559-line file
const drawnCards = [];

// NEW
TarotApp.Cards.getAll();           // Same data, cleaner access
TarotApp.Reading.getDrawnCards();  // Encapsulated state

Adding New Features

Add New Spread

Edit spread.js:

const SPREADS = {
    '7': {
        id: '7',
        name: 'Celtic Cross',
        cardCount: 10,
        positions: [...]
    }
};

Add New Card Method

Edit cards.js:

getBySuit: function(suit) {
    // Implementation
}

Add New UI Feature

Edit ui.js:

myNewFeature: function() {
    // Implementation
}

Performance Notes

  • Module Pattern: No impact on performance (compile-time optimization)
  • Card Data: Single copy in memory (efficient)
  • DOM: Only created when needed (efficient)
  • Bundle Size: ~45KB minified (minimal overhead vs monolithic)

Future Improvements

  • Local storage for reading history
  • Offline support with service workers
  • Additional spreads (Celtic Cross, etc)
  • Astrological correspondences
  • Relationship analysis between cards
  • Responsive design for spreads

Last Updated: November 2025 Module Pattern: Object Namespace (IIFE) Compatibility: IE11+, All modern browsers