# asmithcodes/lumina-the-decision-engine architecture

> Architecture diagram of the GitHub repository asmithcodes/lumina-the-decision-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asmithcodes/lumina-the-decision-engine
- Repository: https://github.com/asmithcodes/lumina-the-decision-engine

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% System Context (C4 L1-ish)
  %% =========================
  subgraph PZ["Public Zone (Browser + Static Hosting)"]
    U["User"]:::person
    B["Browser Runtime"]:::client

    subgraph SH["Static Hosting"]
      GH["GitHub Pages (Static Host)"]:::hosting
      NF["Netlify (Alternative Static Host)"]:::hosting
      GA["GitHub Actions (Deploy SPA)"]:::cicd
    end

    subgraph SPA["Lumina SPA (React 19 + Vite)"]
      HTML["index.html (HTML Shell)"]:::artifact
      MOUNT["index.tsx (React Mount)"]:::artifact
      APP["App.tsx (Root Composition)"]:::artifact

      subgraph UIFLOW["UI Flow Components"]
        Intro["IntroBriefing"]:::ui
        Gate["WarningGate"]:::ui
        KeyModal["ApiKeyModal"]:::ui
        Reset["ResetButton"]:::ui
        ResetCSS["ResetButton.module.css"]:::cssStyle
      end

      subgraph TELEMETRY["Status / Telemetry UI"]
        HUD["CognitiveHUD"]:::ui
      end

      subgraph VIZ["Visualization & Motion Layer"]
        Knot["NeuroKnot (Physics/Motion Visualization)"]:::viz
        Motion["Framer Motion (Animation Engine)"]:::lib
      end

      subgraph INTEGRATION["Integration Layer"]
        GeminiSvc["geminiService (Prompt Orchestration + Double-Model Cascade)"]:::service
        Types["types.ts (Contracts/Schemas)"]:::contract
      end

      subgraph STYLING["Styling & Tooling"]
        TW["tailwind.config.js"]:::cssStyle
        CSS["index.css (Global CSS)"]:::cssStyle
        Vite["vite.config.ts"]:::tooling
        TS["tsconfig.json"]:::tooling
        ViteEnv["vite-env.d.ts"]:::tooling
        Pub["public/ (Static Assets)"]:::artifact
        Meta["metadata.json"]:::artifact
      end
    end
  end

  subgraph TZ["Trusted Zone (Edge Backend with Secrets)"]
    CF["Cloudflare Worker API Proxy (BFF/Edge Proxy)"]:::edge
    Secrets[("Cloudflare Secrets Store\nAPI_KEY")]:::secret

    subgraph WORKER["Worker Deployable (cloudflare-worker-api-proxy)"]
      WorkerRoot["Worker Project Root"]:::edge
      WorkerEntry["src/index.ts (Request Handling + Forwarding)"]:::edge
      Wrangler["wrangler.toml (Config)"]:::edge
      WorkerPkg["package.json (Deps/Build)"]:::edge
    end
  end

  subgraph VZ["External Vendor Zone"]
    Gemini["Google Gemini API"]:::external
    Flash["Gemini 2.5 Flash (Primary)"]:::externalModel
    Lite["Flash Lite (Fallback)"]:::externalModel
  end

  %% =========================
  %% Relationships / Data Flow
  %% =========================
  U -->|interacts| B

  B -->|"loads_static_assets (HTML/JS/CSS)"| GH
  B -->|"loads_static_assets (HTML/JS/CSS)"| NF

  GH -->|serves_bundle| HTML
  NF -->|serves_bundle| HTML
  HTML -->|bootstraps| MOUNT
  MOUNT -->|renders| APP

  %% UI -> Service -> Edge -> Vendor
  APP -->|composes| Intro
  APP -->|composes| Gate
  APP -->|composes| KeyModal
  APP -->|composes| Reset
  APP -->|composes| HUD
  APP -->|composes| Knot

  Knot -->|animates_with| Motion

  Intro -->|user_events| GeminiSvc
  Gate -->|user_events| GeminiSvc
  KeyModal -->|user_events| GeminiSvc
  Reset -->|reset_flow| APP

  GeminiSvc -->|uses_types| Types

  GeminiSvc -->|"HTTPS_fetch (VITE_WORKER_URL)\ntry_model=Flash;on_error_retry=FlashLite"| CF

  %% Worker internals
  CF -->|implemented_in| WorkerEntry
  WorkerRoot -->|contains| WorkerEntry
  WorkerRoot -->|contains| Wrangler
  WorkerRoot -->|contains| WorkerPkg

  CF -->|reads_secret| Secrets
  CF -->|"HTTPS_call (inject_API_KEY)"| Gemini

  Gemini -->|routes_to| Flash
  Gemini -->|routes_to| Lite

  Flash -->|response| CF
  Lite -->|response| CF

  CF -->|normalized_response| GeminiSvc
  GeminiSvc -->|"updates_state (loading/errors/fallback_used)"| HUD
  GeminiSvc -->|"updates_state (visual_progress)"| Knot

  %% CI/CD
  GA -->|deploys_to| GH
  GA -->|builds_from| Vite
  GA -->|ships_assets| GH

  %% Notes / Emphasis
  CF -.->|"security_boundary: API_KEY never_in_browser"| B

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click HTML "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/index.html"
  click MOUNT "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/index.tsx"
  click APP "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/App.tsx"

  click Intro "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/components/IntroBriefing.tsx"
  click Gate "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/components/WarningGate.tsx"
  click KeyModal "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/components/ApiKeyModal.tsx"
  click Reset "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/components/ResetButton.tsx"
  click ResetCSS "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/components/ResetButton.module.css"

  click HUD "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/components/CognitiveHUD.tsx"
  click Knot "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/components/NeuroKnot.tsx"

  click GeminiSvc "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/services/geminiService.ts"
  click Types "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/types.ts"

  click TW "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/tailwind.config.js"
  click CSS "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/index.css"
  click Vite "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/vite.config.ts"
  click TS "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/tsconfig.json"
  click ViteEnv "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/vite-env.d.ts"

  click WorkerRoot "https://github.com/asmithcodes/lumina-the-decision-engine/tree/main/cloudflare-worker-api-proxy/"
  click WorkerEntry "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/cloudflare-worker-api-proxy/src/index.ts"
  click Wrangler "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/cloudflare-worker-api-proxy/wrangler.toml"
  click WorkerPkg "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/cloudflare-worker-api-proxy/package.json"

  click GA "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/.github/workflows/deploy.yml"
  click NF "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/netlify.toml"
  click Pub "https://github.com/asmithcodes/lumina-the-decision-engine/tree/main/public/"
  click Meta "https://github.com/asmithcodes/lumina-the-decision-engine/blob/main/metadata.json"

  %% =========================
  %% Styles
  %% =========================
  classDef person fill:#FFE08A,stroke:#8A5A00,stroke-width:2px,color:#1f2937
  classDef client fill:#C7F9CC,stroke:#1B7F3A,stroke-width:2px,color:#0f172a
  classDef hosting fill:#D9F99D,stroke:#4D7C0F,stroke-width:2px,color:#0f172a
  classDef cicd fill:#E0E7FF,stroke:#3730A3,stroke-width:2px,color:#0f172a

  classDef ui fill:#A7F3D0,stroke:#047857,stroke-width:2px,color:#0f172a
  classDef viz fill:#99F6E4,stroke:#0F766E,stroke-width:2px,color:#0f172a
  classDef lib fill:#BAE6FD,stroke:#0369A1,stroke-width:2px,color:#0f172a
  classDef service fill:#FED7AA,stroke:#C2410C,stroke-width:2px,color:#0f172a
  classDef contract fill:#FDE68A,stroke:#B45309,stroke-width:2px,color:#0f172a

  classDef artifact fill:#F3F4F6,stroke:#6B7280,stroke-width:2px,color:#111827
  classDef cssStyle fill:#FBCFE8,stroke:#9D174D,stroke-width:2px,color:#0f172a
  classDef tooling fill:#DDD6FE,stroke:#5B21B6,stroke-width:2px,color:#0f172a

  classDef edge fill:#FFB4A2,stroke:#9A3412,stroke-width:2px,color:#0f172a
  classDef secret fill:#FFD6A5,stroke:#9A3412,stroke-width:2px,color:#0f172a

  classDef external fill:#FCA5A5,stroke:#991B1B,stroke-width:2px,color:#0f172a
  classDef externalModel fill:#FECACA,stroke:#B91C1C,stroke-width:2px,color:#0f172a
```
