🔮 ArcanaAI – Where Ancient Mysticism Meets Modern AI

ArcanaAI is a practical web application that combines the mysticism of tarot with modern artificial intelligence. The system uses OpenAI's GPT models with function calling to deliver personalized tarot readings that consider each user's specific questions and context.

🤖 Core AI Technologies & Techniques

OpenAI Function Calling Architecture

ArcanaAI uses OpenAI function calling - a technique that allows the AI to decide when to interact with external tools. This creates a practical blend of conversational AI and structured tarot operations.

Intelligent Intent Detection

The system employs natural language understanding to distinguish between casual conversation and genuine requests for spiritual guidance, ensuring that tarot readings are only triggered when appropriate.

Contextual Interpretation Engine

Unlike basic tarot apps with static meanings, ArcanaAI uses contextual AI processing to generate interpretations that consider:

User's specific question and circumstances
Card positions and relationships in spreads
Basic context and cultural elements
User's reading history

✨ Key Features

🧠 AI-Powered Tarot Readings: Personalized interpretations generated using OpenAI GPT with function calling
🎯 Intent Recognition: AI detects when users seek spiritual guidance vs. casual conversation
📚 Context-Aware Interpretations: Readings that consider user context and questions
🔄 Interactive Chat Interface: Real-time sessions with conversation memory
🎴 Multiple Tarot Decks: Support for different styles and spreads
💳 Subscription System: Turn-based free readings and premium features
💰 Dual Payment System: Integrated with Lemon Squeezy (credit cards) and MetaMask (Ethereum)
⚙️ Admin Panel: User and content management with basic analytics
☁️ Cloudflare R2: Secure tarot image storage
🔔 Real-time Notifications via WebSockets

🛠️ Tech Stack

🤖 AI & Machine Learning Layer

OpenAI GPT Models: Language models for conversation and interpretation
Function Calling Framework: Tool routing and execution
Intent Detection System: Basic classification of user requests
Context Management: Conversation memory and continuity

⚡ Backend Infrastructure

FastAPI: Async API for AI model interactions
SQLAlchemy: Data management for user sessions and reading history
PostgreSQL/SQLite: Database for user data and content
Redis: Caching for AI model responses and session data
Celery: Asynchronous task processing
Alembic: Database migration management

🎨 Frontend Experience

Next.js 15: React framework for AI-powered interactions
TypeScript: Type-safe development for AI integration
Tailwind CSS: Design system for the UI
React Query: State management for AI-generated content
Zustand: Lightweight state management for conversation flow

🚀 Infrastructure & DevOps

Docker: Containerized deployment for consistent AI model serving
Traefik: Routing for AI service endpoints
Prometheus: Monitoring for AI model performance
Grafana: Visualization of system metrics and user interactions
GitHub Actions: CI/CD pipeline with testing and validation
Cloudflare R2: Content delivery for tarot imagery

🚀 Deployment & AI Model Management

ArcanaAI supports both local development and production deployment via Docker, with considerations for AI model serving:

AI Model Optimization: Loading and caching of OpenAI models
Rate Limiting: Management of API calls to OpenAI
Fallback Systems: Basic handling when AI services are unavailable
Monitoring: Tracking of AI model performance and user interactions

The system includes a GitHub Actions CI/CD pipeline with automated testing, database migrations, AI model validation, and container builds.

📖 Why ArcanaAI's AI Approach Matters?

While many tarot apps focus on static meanings, ArcanaAI provides AI-powered insights that:

Consider Context: Each reading considers the user's specific situation and question
Use Conversation History: AI models can reference previous interactions for better context
Provide Personalized Interpretations: Go beyond basic card meanings to offer relevant advice
Combine Tradition and Technology: Use modern AI while respecting traditional tarot practices

It bridges spirituality and technology, offering a personalized journey for users worldwide through intelligent AI interpretation.

🔗 Explore the Project

🌐 Production Site: arcanaai.nguyenvanloc.com
📂 GitHub Repository: arcana-ai

🧩 Advanced AI Techniques: Function Calling & Intent Detection

ArcanaAI uses OpenAI function calling to route user intents (like "draw three cards about my career") to server-side tools that perform tarot operations and return structured data for AI interpretation.

1) AI Tool Schema (exact implementation)

# AI tool definition for tarot operations
DRAW_CARDS_TOOL = {
    "type": "function",
    "function": {
        "name": "draw_cards",
        "description": (
            "Draw tarot cards and provide a reading for the user's question or concern. "
            "Use this when the user is asking for guidance, advice, insights about their life, "
            "future, relationships, career, or any other personal matter."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "user_question": {
                    "type": "string",
                    "description": "The user's question or concern for which to draw cards",
                },
                "num_cards": {
                    "type": "integer",
                    "description": "Number of cards to draw (1-10)",
                    "minimum": 1,
                    "maximum": 10,
                    "default": 3,
                },
            },
            "required": ["user_question"],
        },
    },
}

2) AI-Powered Intent Detection & Decision Making

The AI model uses natural language understanding to determine when to invoke tarot tools:

🎯 Guidance Intent Detection: AI recognizes requests for life advice, career guidance, relationship insights
💬 Conversation Filtering: Casual chat and clarifying questions remain in standard conversation mode
🧠 Contextual Analysis: AI considers conversation history for better responses

AI Turn Management: Free/premium turns are only consumed when AI invokes draw_cards. Intelligent conversation does not deduct turns, optimizing user experience.

3) AI Request–Response Flow Architecture

sequenceDiagram
  participant User
  participant Frontend
  participant AI as GPT (Function Calling)
  participant API as FastAPI
  participant Tool as draw_cards()

  User->>Frontend: "Career advice for next 3 months?"
  Frontend->>API: POST /chat {messages + context}
  API->>AI: messages + tools=[draw_cards] + user_history
  Note over AI: AI analyzes intent and context
  AI-->>API: tool_calls: [{name: "draw_cards", args:{user_question, num_cards}}]
  Note over API: AI decision triggers turn deduction
  API->>Tool: draw_cards(user_question, num_cards)
  Tool-->>API: {cards:[...], spread, orientation, meanings}
  API->>AI: messages + tool result + contextual data
  Note over AI: AI generates personalized interpretation
  AI-->>API: Natural-language reading with card citations
  API-->>Frontend: AI response + drawn cards + metadata
  Frontend-->>User: Render AI interpretation + interactive elements

4) AI Model Interaction Examples

AI Intent Recognition Output:

{
  "tool_calls": [
    {
      "id": "call_123",
      "type": "function",
      "function": {
        "name": "draw_cards",
        "arguments": "{\"user_question\":\"Career path in the next quarter\",\"num_cards\":3}"
      }
    }
  ]
}

AI-Enhanced Tarot Data Processing:

{
  "spread": "three-card",
  "cards": [
    { "name": "The Chariot", "position": "past", "orientation": "upright" },
    { "name": "Two of Pentacles", "position": "present", "orientation": "reversed" },
    { "name": "The Sun", "position": "future", "orientation": "upright" }
  ],
  "ai_context": {
    "career_focus": true,
    "timeframe": "quarterly",
    "user_energy": "transitional"
  }
}

AI-Generated Personalized Interpretation: The AI then synthesizes this structured data into a contextually-aware reading that considers the user's specific career question, the cards drawn, and their positions in the spread.

5) AI Safety & Validation Systems

🧠 Schema Validation: AI inputs are validated against parameter schemas
🔄 Idempotent Operations: Duplicate AI tool calls are safely ignored
🎯 Content Routing: AI routes requests to appropriate tools
📊 Observability: Logging of AI decisions and tool usage
🛡️ Rate Limiting: Basic throttling of AI model requests

6) AI-Powered Billing & Turn Management

✅ AI-Triggered Billing: Turns are consumed only when AI invokes tarot tools
❌ Smart Conversation: AI-powered chat without tool invocation remains free
🧠 Turn Tracking: AI tracks user's remaining turns
📈 Usage Tracking: Basic insights into user engagement

🌟 The Future of AI-Powered Spirituality

ArcanaAI demonstrates practical applications of AI in spiritual services, where:

Personalized Interpretation: AI provides readings based on user questions and context
Context Awareness: Each reading considers the user's specific situation
Conversation Memory: AI can reference previous interactions for better context
Respectful AI: Spiritual guidance is delivered with respect for tradition

ArcanaAI is a practical tarot reading tool that combines traditional wisdom with modern AI, offering a personalized experience for users. 🌙✨