CoolFace
Apppublic

kkmenon35/intu-mirror-ai

sourceHugging Faceupdated 8mo agoView on Hugging Face
0likes
App README

✧ IntuMirror: An AI-Guided Journey into the Self ✧

<p align="center"> <img src="docs/image.png" alt="IntuMirror Intro Image" width="700"> </p>

Welcome to IntuMirror. The name represents our core mission: to serve as a mirror for your own intuition. Unlike traditional apps, IntuMirror brings out your inner wisdom using four foundational pillars:

  • —Ancient Tarot Symbolism: To trigger subconscious projections.
  • —Modern Jungian Psychology: To provide a structured framework for self-understanding.
  • —Metacognitive Training: To help you observe the "process" of your own thinking.
  • —AI-Powered Pattern Recognition: To translate symbolic data into actionable life narratives.

This blend creates a shared space where the "best of Tarot" (mystery and intuition) meets the "best of psychology" (structure and logic), helping you see what is already there but perhaps hidden from view.

🧭 Your Guide to a Tarot Session

If you’ve never had a tarot reading, don't worry. In this system, we don't predict the future; we explore the now.

  1. 1.Centered Intention: Start by typing what’s on your mind. It could be a feeling ("I feel burnt out"), a crossroads ("I'm unsure about my career"), or a simple curiosity. This acts as the "anchor" for your session.
  2. 2.The Three-Card Spread: You will draw three cards, each serving a specific psychological function:
  3. 3.Current State: Your conscious experience and the energy you are currently radiating.
  4. 4.The Hidden Shadow: Aspects of yourself or the situation that are currently in your "blind spot"—things you might be avoiding or suppressing.
  5. 5.Emerging Potential: The psychological path forward. If you integrate the lessons of the first two cards, this is the energy that is ready to bloom.
  6. 6.Reflection, Not Prediction: As you flip each card, take a moment to look at the image. What's the first emotion you feel? The AI will provide a narrative, but your intuition is the final authority.
Looking for a deeper understanding? Check out our Detailed Guide to Tarot Cards & Symbols to learn more about the 22 cards and the meaning behind the Mirror.

🧠 The Wisdom Behind the Mirror: Jungian Archetypes

This project is grounded in the work of Swiss psychiatrist Carl Jung. Jung believed that the human psyche isn't just personal; it's shared. He called this the Collective Unconscious.

  • —What are Archetypes? Think of them as "universal blueprints" for human experience. Every culture has the Hero, the Mother, the Shadow, and the Wise Guide.
  • —Tarot as a Projection Tool: The 78 cards of the Tarot are a visual encyclopedia of these archetypes. When you look at a card like The Tower (Sudden Change) or The Star (Hope), your mind "projects" your own life story onto that symbol.
  • —Shadow Work: A core part of our system is identifying the "Shadow." These aren't "bad" parts of you; they are simply the parts you've locked away in the basement. By bringing them into the light of the AI's interpretation, you begin the process of Individuation—becoming a more whole, integrated version of yourself.
Want to master the psychology? Read our Deep Dive into Jungian Psychology to understand the science of the subconscious.

🤖 The Ghost in the Machine: How AI & Machine Learning Work Here

While the interface looks mystical, the engine is built on sophisticated logic and language processing.

  1. 1.Semantic Narrative Construction: Uses LLMs to weave your specific intention and card draws into a personalized Narrative Arc rather than providing static definitions.
  2. 2.The Metacognitive Audit: Prompts for your raw projection first, then performs an "Audit" to reveal the cognitive gap and hidden biases between your intuition and archetypal symbols.
  3. 3.Contextual Continuity: The system remembers your history, offering tailored follow-up questions to ensure your growth is a continuous dialogue across sessions.
  4. 4.Pattern Recognition (Soul Map): Matches archetypes across sessions to build a statistical model of your psychological progress through Shadow and Potential positions.
  5. 5.The Grand Synthesis (The Rebirth): Upon completing the full Soul Map (16+ cards), the AI generates a Sacred Integration—a singular, powerful summary of your entire journey.
  6. 6.Symbolic AI Fallback: For zero-downtime reliability, the system falls back to a deterministic, rule-based Symbolic AI Layer if the primary AI API is unreachable.
  7. 7.Non-Judgmental Processing: Trained in therapeutic, Jungian language to provide a "clean" reflection that encourages self-reliance rather than AI dependency.
  8. 8.The Archiivist (History): Records every reflection in a high-efficiency journal, allowing you to revisit archetypal patterns and your original projections at any time.

🧩 The Two Minds of IntuMirror: Generative vs. Symbolic

IntuMirror employs a dual-engine strategy to balance creative depth with technical resilience.

  • —Primary: Google Gemini (Generative AI):
  • —Pros: High creativity, nuanced "meaning-making," and the ability to find deep semantic links between your specific intention and the Tarot archetypes.
  • —Cons: Requires an internet connection and an API key; subject to external latency and rate limits.
  • —Fallback: The Symbolic AI Layer (Deterministic Engine):
  • —Pros: Zero-latency, works offline, and follows strict Jungian logic. It ensures the app remains functional as a tool for reflection regardless of API status.
  • —Cons: Less personalized phrasing compared to Gemini; follows a more clinical, rule-based narrative structure.

🚀 Exploration & Rapid Testing

The core user flow follows a path from Intention to Projection, mediated by Archetypal Synthesis. You begin by setting your focus, drawing cards that trigger your subconscious, and then logging your raw reaction before the AI reveals a deeper narrative connection.

<p align="center"> <img src="docs/image2.png" alt="IntuMirror Journey Flow" width="700"> </p>

New to the Mirror? We highly recommend reading the Complete Ritual Guide: Tarot + Jungian + AI to understand how to get the most out of your reflection journey.

Want to see the full power of the AI and Soul Map without starting from scratch? We have curated 10 Sacred Test Arcs covering various life themes (Entrepreneurship, Healing, Creativity, etc.).

🧪 [The 10 Sacred Test Arcs: A Structured Testing Guide](./docs/TEST_ARCS.md)

Following these arcs will help you reach the Final Rebirth phase and trigger the high-end "Soul Map Integration" features.

🛠️ Installation & Reproduction Guide

Option 1: Running with Docker (Recommended)

The entire system is containerized for seamless reproduction.

  1. 1.Requirement: Ensure Docker and Docker Compose are installed.
  2. 2.Run:
bash
    docker compose up --build
  1. 1.Access:
  2. 2.Frontend: http://localhost:8080
  3. 3.Backend API: http://localhost:5000

Option 2: Local Manual Setup

  1. 1.Backend:
bash
    cd backend
    npm install
  1. 1.Configuration:
  2. 2.Copy the template: cp backend/.env.template backend/.env
  3. 3.Open backend/.env and add your Google Gemini API Key. You can get one for free at the Google AI Studio.
  4. 4.(Note: If no key is provided, the system will automatically utilize the Symbolic AI Fallback.)
  5. 5.Start Backend:
bash
    npm start
  1. 1.Frontend:
bash
    cd frontend
    npm install
    npm run dev

🧪 Running Tests

  • —Backend Integration Tests: cd backend && npm test
  • —Frontend Component Tests: cd frontend && npm test

🏗️ System Architecture

For a complete understanding of how this product was conceived and built, please refer to our Master Source of Truth:

🧭 [Master PRD: Concepts, Logic & Technical Architecture](./docs/MASTER_PRD.md)

🤖 AI-Assisted System Development & MCP Workflow

This project represents a fully documented AI-assisted system development lifecycle. Using an agentic workflow anchored in the Model Context Protocol (MCP), the system was built through a series of specialized prompts, coding assistants, and automated tool-orchestration.

  • —Agentic Evolution: Chronological logs of the AI development workflow including prompt strategy and implementation phases.
  • —MCP & Context: Documentation on how MCP tools and project context were leveraged to manage the full-stack architecture.
  • —Frontend: React (Vite) + Vitest.
  • —Backend: Express + SQLite + Jest.
  • —API Documentation: OpenAPI 3.0 Specification
  • —AI Intelligence: Symbolic AI & Knowledge Graph
  • —Mindfulness Engine: The Metacognitive Mirror
  • —Database: Persistent SQLite storage for long-term pattern tracking.

⚖️ Ethical Boundary & Disclaimer

IntuMirror is a tool for self-reflection. It is not a substitute for professional mental health care, medical diagnosis, or psychiatric treatment. It does not predict external events, deaths, or "fate."

This project is for educational and research purposes only as part of the AI Dev Tools Zoomcamp. The Archetypal Pattern Recognition and Soul Map are proofs of concept to demonstrate AI's ability to assist in qualitative self-inquiry and reduce cognitive bias.

📜 License

This project is provided as-is for educational purposes. See LICENSE file for details.

🤝 Acknowledgments

  • —AI Dev Tools Zoomcamp: Many thanks to DataTalksClub for the course and project framework.
  • —Knowledge Base: Grateful for the foundational works of Carl Jung and the open-source community for the symbolic Tarot datasets.
  • —Contributors and Reviewers: Thanks to all who provided feedback during the development of this AI-guided experience.