Lumina: The Decision Clarity Engine

"The hardest person to be honest with is yourself. Lumina is the mirror that doesn't look away."

Lumina is a Socratic mirror designed to deconstruct the ego and expose the hidden truths behind your hardest dilemmas. Utilizing physics-based metaphors and deep-introspection AI, it transforms mental entropy into geometric clarity.

---

The Philosophy

Most decision-making tools help you decide. Lumina helps you see.

Through a sequence of precisely calibrated, hard-hitting questions, Lumina forces you to bypass the superficial layers of self-justification. It doesn't give you advice; it reflects your own truth back to you until you can no longer ignore it.

Cognitive Features

• Deconstructive Questioning: 5 devastatingly simple questions designed to bypass the ego and reach the core of your hesitation.
• The Double-Model Cascade: A resilient architecture using Gemini 2.5 Flash as the primary engine, with an automatic fallback to Flash Lite to ensure clarity even under high entropy (quota limits).
• NeuroKnot Visualization: A kinetic, physics-based UI that reacts to your progress, visualizing the unraveling of mental knots in real-time.
• Zero-Exposure API: All intelligence is proxied through a secure Cloudflare Worker, keeping the "brain" decoupled and the secrets safe.
• Weightless Interface: Built for speed and immersion, featuring glassmorphic aesthetics and motion-driven navigation.

The Cognitive Stack

Layer	Technology	Rationale
Logic	React 19	Functional purity for complex state management.
Motion	Framer Motion	Physics-based micro-interactions that feel "alive."
Styling	Tailwind CSS	Atomic utility for a weightless, premium UI.
Intelligence	Gemini 2.5 Flash	High-speed, high-reasoning Socratic engine.
Security	Cloudflare Workers	Edge-level proxy for secure, serverless API execution.

---

Materializing Locally

Prerequisites

• Node.js 18+
• A Gemini API Key from Google AI Studio

1. Initialize the Core

git clone https://github.com/Asmithcodes/Lumina--The-Decision-Clarity-Engine.git
cd Lumina--The-Decision-Clarity-Engine
npm install

2. Configure the Proxy (Recommended)

This project uses a Cloudflare Worker to secure your API keys.

cd cloudflare-worker-api-proxy
npm install
npx wrangler secret put API_KEY  # Input your Gemini API key
npx wrangler deploy

3. Connect & Ignite

Create a .env in the root and point it to your materialized worker:

VITE_WORKER_URL=https://your-worker-name.workers.dev

Then run the engine:

npm run dev

---

Deployment

Lumina is designed to breathe on the edge.

• Frontend: Shipped via GitHub Pages (automated via .github/workflows/ci.yml).
• Intelligence: Distributed via Cloudflare Workers.

---

Architecture of Thought

├── components/          # The Sensory Organs (React Components)
│   ├── NeuroKnot.tsx    # The Pulse: Physics-based visualizer
│   ├── CognitiveHUD.tsx # The Feedback: Real-time status indicators
│   └── WarningGate.tsx  # The Filter: Ego-check before entry
├── services/
│   └── geminiService.ts # The Synapse: Dual-model cascade logic
├── types.ts             # The Blueprint: Strongly typed schemas
└── cloudflare-worker-api-proxy/ # The Shield: Secure API handling

---

Collaboration

Interested in refining the Socratic engine or the physics of clarity? Pull requests are welcome. Let's build better mirrors together.

Recognition

• Developed by Asmith (asmyth@duck.com).

---

Experience Clarity →