How asmithcodes/lumina-the-decision-engine works
What this project is (type + purpose)
Lumina is a client-side React (Vite) SPA that guides a user through a “Socratic questioning” flow and renders a physics/motion-driven visualization (“NeuroKnot”). It calls Google Gemini for responses, but critically it does not call Gemini directly from the browser: it routes requests through a Cloudflare Worker API proxy to avoid exposing the API key (“Zero-Exposure API”).
So architecturally it’s a 2-part system:
Frontend root (SPA)
Key files/dirs:
• index.html, index.tsx, App.tsx → SPA entry + root app composition
• components/ → UI modules (major “subsystems” of the UI/UX)
• ApiKeyModal.tsx (user config / key capture UX, depending on implementation)
• IntroBriefing.tsx (onboarding / initial flow)
• WarningGate.tsx (pre-check / gating step)
• CognitiveHUD.tsx (status/telemetry UI)
• NeuroKnot.tsx (visualization “engine”)
• ResetButton.tsx, .module.css (UI control)
• services/geminiService.ts → the frontend’s integration boundary (the “synapse”): constructs prompts, implements the double-model cascade (Flash → fallback Flash Lite), and performs network calls to the Worker URL.
• tailwind.config.js, index.css → styling system
• vite.config.ts, tsconfig.json → build/tooling
Deployment hints:
• .github/workflows/deploy.yml → GitHub Actions deploy (README says GitHub Pages)
• metadata.json, public/ → static assets / PWA-ish metadata (if used)
Cloudflare Worker proxy (serverless edge)
cloudflare-worker-api-proxy/
• src/index.ts → Worker entry: receives browser requests and forwards to Gemini (or Google AI endpoint), injecting the secret API_KEY
• wrangler.toml → Worker config
• package.json etc. → Worker build/deploy
This is a separate deployable and should be drawn as its own node with its own lifecycle.
SPA updates
• text/decision clarity UI
• CognitiveHUD (status: loading, fallback used, errors)
• NeuroKnot visualization (progress/entropy-to-clarity metaphor)
Failure/Resilience path (double-model cascade)
• If Gemini Flash fails (quota/rate/5xx), the system falls back to Flash Lite
• Where this logic lives:
• Per README: “Double-Model Cascade … fallback … quota limits” and file tree: services/geminiService.ts implies the cascade is implemented client-side in the service layer.
• The Worker is primarily the secure proxy boundary.
• “Attempt model=Flash; on error retry model=FlashLite”
Security boundary
Emphasize:
• Browser never sees the Gemini API key
• Worker holds secret in Cloudflare secret store
• SPA only knows VITE_WORKER_URL
• Public zone (browser + static hosting)
• Trusted zone (Worker environment with secrets)
• External vendor zone (Google AI)
Client
• Browser/User
• GitHub Pages (or Static Host)
• Lumina SPA
• IntroBriefing
• WarningGate
• CognitiveHUD
• NeuroKnot
• ApiKeyModal (if used)
• geminiService
• types.ts (contract)
Edge
• Cloudflare Worker (index.ts)
• Cloudflare Secrets store (API_KEY) (can be a sub-node or annotation)
External
• Gemini API: Flash
• Gemini API: Flash Lite
Dev/Deploy
• GitHub Actions workflow (deploy.yml)
• Wrangler deploy pipeline (manual or CI-driven)