CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Meu Tarot Online is a static website built with Jekyll, providing free interactive tarot readings, daily card draws, and articles about tarot and spirituality in Portuguese (pt-BR). The site is deployed to GitHub Pages with a custom domain (meutarotonline.com.br) and includes Google AdSense monetization and Analytics.

Key Technologies:

  • Jekyll (Ruby static site generator)
  • GitHub Pages + GitHub Actions (CI/CD)
  • Vanilla JavaScript (ES6) with modular architecture
  • CSS3 with CSS variables
  • Liquid templating language

Essential Commands

# Install Ruby dependencies
bundle install

# Run local development server (live reload at http://localhost:4000)
bundle exec jekyll serve

# Build static site to _site/ directory
bundle exec jekyll build

# Build with future-dated posts included
bundle exec jekyll build --future

# Clean build artifacts before rebuilding
bundle exec jekyll clean

Project Structure & Architecture

Core Pages

  • index.html – Homepage with call-to-action
  • tarot.html – Main interactive tarot reading application
  • card-of-day.md – Daily card oracle display
  • study.html – Study Hub with flashcards, guides, and learning paths
  • oraculo-amor.md – Love Oracle (3-card love reading, yes/no, name compatibility)
  • oraculo-humor.md – Humor oracle page
  • articles.md – Auto-generated blog post listing
  • about.md – Project philosophy and contact info
  • _posts/ – Blog articles in Markdown (auto-published based on date)
  • rituais/ – Rituals section (index.md + individual ritual posts)
  • arcanos-maiores/ – Major Arcana deep-dive section (index.md + per-card pages)

Template System

  • _layouts/default.html – Base page template (all pages inherit this)
  • _layouts/post.html – Blog post template (inherits from default)
  • _includes/header.html – Navigation with dropdown menus
  • _includes/footer.html – Footer component

JavaScript Architecture

The app uses a modular namespace pattern under TarotApp.*:

Core Modules (js/modules/):

  • cards.js – 78-card database with Portuguese names/meanings. Access via TarotApp.Cards.getAll(), getByName(), isMajorArcana()
  • spread.js – Spread configurations (3-card, 5-card guidance, 5-card love). Access via TarotApp.Spread.getById(), getPositionInfo()
  • reading.js – Reading state and Fisher-Yates shuffle. Access via TarotApp.Reading.start(), getDrawnCards(), generateInterpretation()
  • ui.js – Card DOM creation with staggered animations, flip interactions
  • modal.js – Card detail modal with ESC/click-outside close
  • flashcards-app.js – Flashcard study system for study.html
  • reading-history.js – LocalStorage reading history
  • share-reading.js – Reading share functionality
  • card-contexts.js – Context-aware card interpretations per spread position
  • analytics.js – GA4 event tracking

Main Orchestrators:

  • js/tarot-app.js – Original monolithic app (still loads card data)
  • js/tarot-app-refactored.js – Modular version coordinating all modules
  • js/love-oracle.js – Love Oracle page logic
  • js/love-compatibility-messages.js – 253 customized compatibility messages
  • js/home-widgets.js – Homepage “Carta do Dia” and “Fase Lunar” widget logic (self-contained IIFE)
  • js/lunar-phase.js – Lunar phase calculation utility used by home widgets
  • js/nav.js – Navigation/header interactive behavior
  • js/spread-preview.js + spread-preview-init.js – Spread selector preview UI
  • js/simple-progress.js – Reading progress indicator

Minified files: tarot-app.min.js and style.min.css are pre-built minified copies. Update the source file, then regenerate the .min version before committing.

Module Load Order (required):

<script src="/js/modules/cards.js"></script>
<script src="/js/modules/spread.js"></script>
<script src="/js/modules/reading.js"></script>
<script src="/js/modules/ui.js"></script>
<script src="/js/modules/modal.js"></script>
<script src="/js/tarot-app-refactored.js"></script>

CSS Architecture

  • css/style.css – Main responsive styling with dark mystical theme
  • css/study.css – Study Hub page styles
  • css/love-oracle.css – Love Oracle page styles
  • css/reading-history.css – Reading history component
  • css/share-reading.css – Share reading component
  • css/spread-preview.css – Spread preview component
  • css/rituais.css – Rituals section styles
  • css/post-ritual.css – Individual ritual post layout
  • css/simple-progress.css – Progress indicator styles

Assets

  • images/cartas/ – 78 tarot card images (PNG and WebP formats)
  • images/Mesa.png – Hero background image

Tarot Card Data Structure

Each card in cards.js/tarot-app.js contains:

{
  name: "Card name in Portuguese",
  image: "images/cartas/cardname.png",
  meaning: "Upright interpretation in Portuguese",
  reversedMeaning: "Reversed interpretation in Portuguese"
}

The 78-card deck is organized as:

  • 22 Major Arcana (0-21)
  • 4 Suits: Wands/Paus, Cups/Copas, Swords/Espadas, Pentacles/Ouros (14 cards each)

Build & Deployment

Automated Deployment (GitHub Actions)

  • jekyll-gh-pages.yml – Triggers on push to master, builds and deploys to GitHub Pages
  • jekyll-docker.yml – Validates build on push/PR using Docker

Publishing Posts

  • Posts in _posts/ follow Jekyll naming: YYYY-MM-DD-slug-name.md
  • Default config has future: false – use --future flag to include future-dated posts locally
  • Posts auto-appear on articles.md and get SEO tags, feed entries, sitemap inclusion

Key Design Decisions

Color Scheme (CSS Variables):

  • Dark background: #0a0a14
  • Primary text: #e8e8e8
  • Accent/purple: #b0a3d7
  • Love Oracle uses pink accent: #ff6b9d

Fonts:

  • Headers: Cinzel (serif)
  • Body: Raleway (sans-serif)

Reversal Probability: 30% chance in reading.js

Important Constraints

  1. Language: All content must be in Brazilian Portuguese (pt-BR)
  2. Static site: No backend/database—only static files served by GitHub Pages
  3. Theme system: Using Jekyll’s “minima” theme—custom CSS layers on top
  4. Plugin limitations: Only GitHub Pages-compatible plugins (jekyll-feed, jekyll-seo-tag, jekyll-sitemap)

Repository Info

  • Git branch: master (main development branch)
  • Repository: LuigiDeFacci/Site-Tarrot
  • Domain: meutarotonline.com.br
  • Analytics: GA-4 tag G-VTSVNSFRZ7
  • AdSense: ca-pub-7268118989139833