Tableu is a sophisticated AI-powered tarot reading application that bridges traditional cartomancy with modern generative AI. Unlike simple database-lookup tarot apps, it uses advanced Large Language Models to synthesize complex card relationships, positional meanings, and user context into cohesive, human-like narratives.
🔮 Designed to feel like sitting with a practiced reader, not a generic card widget.
- Multiple Spread Types: One-Card Insight, Three-Card Story, Five-Card Clarity, Decision/Two-Path, Relationship Snapshot, and Celtic Cross (10-card)
- AI-Generated Narratives: Context-aware readings powered by Azure OpenAI GPT-5.1 with Claude fallback
- Knowledge Graph Analysis: Advanced pattern detection including elemental dignities, suit progressions, and archetypal triads
- Text-to-Speech: Listen to readings with Azure GPT-4o-mini TTS
- Personal Journal: Save and reflect on readings (cloud sync for authenticated users, localStorage for anonymous)
- Shareable Readings: Generate links to share readings with others
- Ritual Experience: Authentic tarot feel with knocks, deck cutting, and card reveal animations
- Accessibility: WCAG-compliant with keyboard navigation, ARIA labels, and reduced-motion support
- PWA Support: Installable progressive web app with offline capabilities
| Layer | Technology |
|---|---|
| Frontend | React 18, Vite, Tailwind CSS |
| Backend | Cloudflare Workers (serverless) |
| AI | Azure OpenAI (GPT-5.1, GPT-4o-mini TTS), Anthropic Claude |
| Database | Cloudflare D1 (SQLite) |
| Caching/Rate Limiting | Cloudflare KV |
| Storage | Cloudflare R2 |
├── src/ # React frontend
│ ├── components/ # UI components (Card, ReadingGrid, etc.)
│ ├── contexts/ # React contexts (Auth, Preferences, Reading)
│ ├── data/ # Card data and spread definitions
│ ├── hooks/ # Custom React hooks
│ ├── lib/ # Frontend utilities (audio, deck, formatting)
│ ├── pages/ # Route pages
│ ├── styles/ # CSS files (Tailwind + custom)
│ ├── worker/ # Cloudflare Worker entry point
│ └── TarotReading.jsx # Main orchestration component
├── functions/ # Cloudflare Pages Functions (API)
│ ├── api/ # API endpoints
│ └── lib/ # Backend logic and narrative generation
├── public/ # Static assets (images, sounds, icons)
├── tests/ # Test files (*.test.mjs)
├── scripts/ # Utility scripts (evaluation, training)
├── docs/ # Documentation
└── migrations/ # Database migrations (D1)
- Node.js 18.0.0 or later
- npm (included with Node.js)
- Cloudflare account (for deployment)
# Clone the repository
git clone https://github.com/henryperkins/tarot.git
cd tarot
# Install dependencies
npm install-
A0BA
Create
.dev.varsand fill in the required secrets:# Azure OpenAI (required for AI-generated readings) AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com AZURE_OPENAI_API_KEY=your-api-key AZURE_OPENAI_GPT5_MODEL=gpt-5.1 # Azure TTS (optional, for voice readings) AZURE_OPENAI_TTS_ENDPOINT=https://your-resource.openai.azure.com AZURE_OPENAI_TTS_API_KEY=your-tts-api-key AZURE_OPENAI_GPT_AUDIO_MINI_DEPLOYMENT=gpt-4o-mini-tts # Anthropic (optional, for Claude fallback) AZURE_ANTHROPIC_ENDPOINT=https://<resource>.services.ai.azure.com/anthropic AZURE_ANTHROPIC_API_KEY=your-azure-foundry-key # optional; can fall back to AZURE_OPENAI_API_KEY AZURE_ANTHROPIC_MODEL=claude-opus-4-5 # Vision research mode (optional) VISION_PROOF_SECRET=your-secret-key
-
Verify your configuration:
npm run config:check
⚠️ Never commit.dev.varsto version control. It's already in.gitignore.
npm run devThis starts both the Vite dev server and Wrangler Workers dev server. Access the app at http://localhost:5173 (or 5174 if 5173 is in use). Vite proxies /api requests to Workers on 8787.
| Command | Description |
|---|---|
npm run dev |
Start full-stack development server |
npm run dev:frontend |
Start Vite dev server only (no API) |
npm run dev:wrangler |
Start Wrangler Workers dev server |
npm run build |
Build for production |
npm run preview |
Preview production build |
npm test |
Run tests |
npm run lint |
Run ESLint |
npm run lint:fix |
Fix linting issues |
| URL | Purpose |
|---|---|
| http://localhost:5173 | Full app with API (HMR + /api proxy) |
| http://localhost:8787 | Workers preview (serves dist/) |
Some debugging workflows (including VS Code “Attach to Chrome”) expect a browser already running with Chrome DevTools Protocol (CDP) enabled on port 9222.
This repo includes a helper script that launches Playwright’s bundled Chromium with CDP enabled (so you don’t need system Chrome installed):
# Starts Chromium with CDP on http://127.0.0.1:9222
npm run chrome:debugNotes:
-
In many Linux container/remote environments Chromium sandboxing is restricted; the script will automatically fall back to
--no-sandboxwhen needed. -
If you need the port reachable from outside the container/VM, bind to all interfaces and forward the port:
npm run chrome:debug -- --host 0.0.0.0
-
To avoid port conflicts, pick another port:
npm run chrome:debug -- --port 9333
If you use VS Code, this repo also includes .vscode/launch.json + .vscode/tasks.json with an “Attach to CDP Chromium (9222)” configuration.
# Run all tests
npm test
# Accessibility tests
npm run test:a11y
# Vision quality gates
npm run gate:vision
# Narrative quality gates
npm run gate:narrativeTests use Node.js native test runner with .test.mjs files in the tests/ directory.
# Build and deploy
npm run build && npm run deploy
# Or use the combined script
npm run deploywrangler secret put AZURE_OPENAI_ENDPOINT --config wrangler.jsonc
wrangler secret put AZURE_OPENAI_API_KEY --config wrangler.jsonc
wrangler secret put AZURE_OPENAI_GPT5_MODEL --config wrangler.jsonc
# ... add other secrets as needed- Production: https://tableau-8xz.pages.dev
- Branch Previews: https://<branch-name>.tableau-8xz.pages.dev
Detailed documentation is available in the docs/ directory:
- Developer Onboarding - Getting started guide with setup instructions
- Vision Pipeline - Physical card recognition system
- Knowledge Graph - Tarot pattern and archetype documentation
- Evaluation System - Automated reading quality evaluation
- Reasoning Chain - Narrative builder for the local composer fallback
- Architecture Diagram - Technical architecture overview
For comprehensive project guidance, see CLAUDE.md.
- Follow Conventional Commits:
feat:,fix:,chore:,docs:,test: - Run
npm testbefore pushing changes - Run
npm run lintto check code style - Include screenshots for UI changes in PR descriptions
- Keep PRs focused; avoid bundling unrelated changes
| Spread | Cards | Description |
|---|---|---|
| One-Card Insight | 1 | Quick guidance for a focused question |
| Three-Card Story | 3 | Past, Present, Future narrative |
| Five-Card Clarity | 5 | Core, Challenge, Hidden, Support, Direction |
| Decision/Two-Path | 5 | Compare two options with clarity |
| Relationship Snapshot | 3 | You, Them, Connection dynamic |
| Celtic Cross | 10 | Classic deep dive for complex questions |
- Tarot readings are for guidance and reflection, not replacement for professional advice
- Emphasizes user agency and free will over deterministic predictions
- No medical, legal, or financial advice
- Trauma-informed, empowering language
- Cards are never invented or hallucinated by the AI
The app uses public domain 1909 Rider-Waite "Roses & Lilies" deck images from Wikimedia Commons.
Built with 🔮 by the Tableu team