Jarvis-Cali React - Multi-File Structure 🚀

A modern, mobile-friendly math suite built with React, Vite, and Tailwind CSS. The project is organized with a feature-first architecture for scalability and clean ownership.

🗂️ Project Structure

jarvis-cali/
├── server/
│   └── index.js                                   # Secure Gemini proxy API (server-side key)
├── src/
│   ├── app/
│   │   └── App.jsx                                # App shell + view switching + global state
│   ├── features/
│   │   ├── calculator/
│   │   │   ├── components/
│   │   │   │   ├── SimpleCalculatorPage.jsx       # Main calculator UI + modes + history sheet
│   │   │   │   ├── UnitConverter.jsx              # Multi-category unit conversion
│   │   │   │   ├── DateCalculator.jsx             # Date difference and add/subtract calculator
│   │   │   │   ├── CalendarWidget.jsx             # Date picker for calculator flows
│   │   │   │   └── GraphingCalculator.jsx         # Function plotting view
│   │   │   ├── hooks/
│   │   │   │   └── useCalendarNavigation.js       # Calendar month/year/view state logic
│   │   │   └── services/
│   │   │       └── calculatorHistoryService.js    # Calculator history persistence
│   │   ├── tutor/
│   │   │   ├── components/
│   │   │   │   └── AiTutorPage.jsx                # AI tutor (typed math, drawing, image input)
│   │   │   ├── hooks/
│   │   │   │   └── useTutorHistory.js             # Tutor history persistence
│   │   │   └── services/
│   │   │       └── tutorService.js                # Gemini request/response handling
│   │   ├── practice/
│   │   │   ├── components/
│   │   │   │   └── PracticeMode.jsx               # AI-generated quiz flow + scoring
│   │   │   ├── hooks/
│   │   │   │   └── usePracticeOptions.js          # Practice option constants
│   │   │   └── services/
│   │   │       └── practiceQuestionsService.js    # Gemini quiz generation logic
│   │   └── settings/
│   │       ├── components/
│   │       │   └── SettingsModal.jsx              # Theme, API key, model selection, PWA install
│   │       ├── hooks/
│   │       │   └── useDebouncedValue.js           # Debounced input handling
│   │       └── services/
│   │           └── geminiModelsService.js         # Fetch available Gemini models
│   ├── shared/
│   │   ├── assets/
│   │   │   └── logo.svg
│   │   ├── components/
│   │   │   └── MathRenderers.jsx                  # KaTeX/math rendering helpers
│   │   ├── hooks/
│   │   │   └── useSwipeGesture.js                 # Reusable swipe navigation hook
│   │   └── utils/
│   │       ├── constants.js                       # Math keyboard + shared constants
│   │       └── dateUtils.js                       # Date parsing/formatting helpers
│   ├── assets/
│   │   └── logo.png
│   ├── index.css
│   └── main.jsx
├── public/
│   ├── manifest.json
│   └── sw.js
├── .env.example
├── jsconfig.json                                   # Alias mapping for editor tooling
├── vite.config.js                                  # Vite config + alias mapping
├── tailwind.config.js
├── postcss.config.js
└── README.md

📦 Installation & Setup

✅ Prerequisites

• Node.js 16+
• npm

🛠️ Steps

1. Install dependencies:

npm install --legacy-peer-deps

2. Create your local environment file:

cp .env.example .env

3. Add your Gemini API key in .env:

GEMINI_API_KEY=your_api_key_here

4. Start the dev server:

npm run dev

App runs at http://localhost:5173.

5. Build for production:

npm run build

6. Preview production build:

npm run preview

🔐 Environment & API Key Behavior

API key resolution priority:

1. User-saved key from Settings (optional override)
2. GEMINI_API_KEY on backend server (.env)
3. VITE_PUBLIC_GEMINI_API_KEY (risky static fallback)

Notes:

• 🔒 The default key stays server-side and is never bundled into frontend code.
• 🔁 If user clears their custom key, requests use secure server default key.
• 🌐 On static hosting without backend (for example GitHub Pages), users must provide their own Gemini key in Settings.
• 🔀 Gateway behavior: app first tries backend proxy, then falls back to direct Gemini calls when a user key is available.

Security note:

• In secure mode (VITE_BACKEND_PROXY_BASE), no Gemini key is bundled in frontend code.
• In risky mode (VITE_PUBLIC_GEMINI_API_KEY), key is bundled and exposed.
• Direct browser calls use user key when provided, otherwise public fallback key if configured.

Risky fallback option:

• Set VITE_PUBLIC_GEMINI_API_KEY only if you intentionally want a default key on static hosting.
• This key is exposed in frontend bundle and can be extracted.
• If you enable it, lock down hard:
  • API restriction: Generative Language API only.
  • HTTP referrer allowlist: your exact domains only.
  • Strict quotas and billing alerts.

🌐 Secure Default Key Without Traditional Server

If you want all users to get AI responses on GitHub Pages without entering their own key, while keeping your key secret, use a serverless proxy (Cloudflare Worker).

How it works:

1. User opens app on GitHub Pages.
2. Frontend sends requests to your Worker URL (VITE_BACKEND_PROXY_BASE).
3. Worker uses secret GEMINI_API_KEY (stored in Cloudflare secrets).
4. If user enters their own key in Settings, that key is used as override.

This gives you:

• ✅ Default key for all users
• ✅ Optional user key override
• ✅ No key in frontend bundle

Files included for this flow:

• edge/cloudflare-worker.js
• edge/wrangler.toml.example

Quick setup:

1. Install Wrangler and login:

npm i -D wrangler
npx wrangler login

2. Create edge/wrangler.toml from example and deploy worker:

cp edge/wrangler.toml.example edge/wrangler.toml
cd edge
npx wrangler secret put GEMINI_API_KEY
npx wrangler deploy

3. Set frontend to use Worker URL in .env:

VITE_BACKEND_PROXY_BASE=https://your-worker-name.your-subdomain.workers.dev

4. Rebuild and deploy frontend:

npm run deploy

✨ Key Features

🎯 Core Experience

• Multi-view app shell with smooth animated transitions.
• Universal swipe gestures for intuitive back navigation on mobile.
• Dark/light theme support from Settings.

🧮 Calculator Feature

• Standard and scientific calculator modes.
• Local expression evaluation with support for trig, log/ln, factorial, powers, constants, and angle unit switching (DEG/RAD).
• Live result preview while typing.
• History drawer with expandable mobile sheet behavior.
• Unit converter (Area, Length, Temperature, Volume, Mass, Data, Speed, Time).
• Date calculator with:
  • Date difference mode
  • Add/subtract years/months/days
  • Interactive calendar widget
• Graphing calculator powered by function plotting.

🤖 AI Tutor Feature

• Supports typed math input with structured math keyboard tabs.
• Supports handwritten/drawing mode on canvas.
• Supports image upload and camera capture for problem input.
• Gemini-powered step-by-step solution generation.
• KaTeX-based rendering for math expressions and explanations.
• Persistent tutor history with re-openable attempts.

🧠 Practice Mode Feature

• AI-generated quizzes based on topic, difficulty, and question count.
• Curated question bank with difficulty tags and curriculum mapping (General, Common Core, IGCSE, SAT).
• Hybrid generation strategy: approved curated items first, then AI fallback for missing coverage.
• Built-in solution quality review queue for AI-generated questions (approve / needs work workflow).
• Topic presets: Algebra, Calculus, Geometry, Trigonometry, Arithmetic, Statistics.
• Per-question feedback with explanation.
• End-of-quiz summary with score/percentage and retry flow.

⚙️ Settings & PWA Feature

• Save personal Gemini API key override.
• Auto-detect available Gemini models via secure backend proxy.
• Select and persist preferred model.
• Theme toggling.
• Progressive Web App install prompt integration when available.
• Offline action queue for tutor/practice requests.
• Background sync trigger for queued actions when connectivity returns.
• Conflict-safe queue replay strategy (last-write-wins per conflict key).
• In-app update toast when a new service worker version is available.

🧪 Content Quality Workflow

• curatedQuestionBank.js stores approved baseline content with metadata:
  • topic
  • difficulty
  • curriculumTag
  • quality.status
• questionBankService.js handles filtering and review override state.
• qualityReviewService.js tracks generated-question review queue and outcomes.

🏗️ Architecture Highlights

• Feature-first folder structure (features/*) for domain ownership.
• Internal separation into:
  • components for UI
  • hooks for reusable state logic
  • services for IO/API and persistence logic
• Shared cross-domain layer in src/shared.
• Backend proxy layer in server/index.js for secure Gemini communication.
• Import aliases for clean paths:
  • @app
  • @features
  • @shared
  • @

📜 Scripts

• npm run dev - run proxy server + Vite together 🚀
• npm run server - run secure proxy server only 🔐
• npm run build - create production bundle 🏗️
• npm run test - run smoke tests ✅
• npm run preview - preview production build locally 👀
• npm run lint - run ESLint 🧹
• npm run deploy - deploy dist to GitHub Pages 🌐

🔁 Professional DevOps

GitHub Actions workflows included:

• .github/workflows/ci.yml
  • Runs lint, tests, and production build on push/PR.
• .github/workflows/preview-artifact.yml
  • Builds PR preview artifact (dist) for quick QA download.
• .github/workflows/uptime.yml
  • Scheduled uptime checks for live web URL and optional API health URL.
• .github/workflows/release.yml
  • Auto-generates GitHub release notes for v* tags.

Optional monitoring:

• Frontend Sentry via VITE_SENTRY_DSN.

🚢 Deployment

🐙 GitHub Pages (configured)

npm run deploy

The predeploy script runs production build automatically.

☁️ Other Platforms

You can deploy the generated dist/ folder to Vercel, Netlify, Cloudflare Pages, or any static host.

📝 Architecture Decisions (ADR)

ADR-001: Feature-Based Modules 🧩

• Status: Accepted
• Decision: Organize code by feature (calculator, tutor, practice, settings) with components, hooks, and services.
• Rationale: Keeps business logic close to UI and reduces cross-feature coupling.

ADR-002: Shared Core Layer ♻️

• Status: Accepted
• Decision: Keep common assets, hooks, components, and utilities in src/shared.
• Rationale: Enables reuse without blurring feature boundaries.

ADR-003: Path Alias Strategy 🧭

• Status: Accepted
• Decision: Use aliases (@app, @features, @shared, @) in Vite and jsconfig.
• Rationale: Improves readability and minimizes brittle relative imports.

🤝 Contributing

Contributions are welcome.

1. Fork the repo
2. Create a feature branch
3. Commit your changes
4. Open a pull request