# romeirofernandes/vedicmath architecture

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

- Interactive diagram: https://gitdiagram.com/romeirofernandes/vedicmath
- Repository: https://github.com/romeirofernandes/vedicmath

## Overview

1. **Repository shape**
   - This is a single-page React frontend, not a multi-service backend repo.
   - The `frontend/` app contains all runtime code: pages, shared UI components, context providers, API integrations, and lesson/AI features.

2. **App shell and routing**
   - `main.jsx` bootstraps the React app, and `App.jsx` is the top-level composition point.
   - The app is organized primarily by route-level pages in `src/pages`, with shared navigation/layout pieces in `src/components`.
   - `ProtectedRoute.jsx` acts as the access-control boundary for authenticated or course-restricted pages such as dashboard, progress, certificate, and possibly lessons.

3. **Page-level feature boundaries**
   - `Landing`, `SignIn`, and `SignUp` form the public entry/auth flow.
   - `Dashboard`, `Game`, `Leaderboard`, `Certificate`, and `VedicAIAssistant` are feature pages.
   - `pages/lessons/Lesson1.jsx` through `Lesson5.jsx` implement the structured learning path described in the README.

4. **Learning content subsystem**
   - The lessons are likely the core instructional sequence, with each lesson page responsible for one stage of the Vedic Mathematics curriculum.
   - `LessonItem.jsx`, `Features.jsx`, `Testimonial.jsx`, `Header.jsx`, `Footer.jsx`, and `SidePanel.jsx` support the learning/marketing UI around that content.
   - `ProgressBar.jsx` and `ProgressUtils.jsx` connect learning completion state to the visual progression model.

5. **Interactive technique demonstrations**
   - The `VedicAdditionAnimation`, `VedicSubtractionAnimation`, `VedicMultiplicationAnimation`, `VedicDivisionAnimation`, and `VedicSquaringAnimation` components are a dedicated visualization layer.
   - These are presentation-focused modules that illustrate the mathematical methods rather than compute business logic.
   - They likely sit inside lessons or practice pages as embedded demonstrations.

6. **AI tutor subsystem**
   - `pages/VedicAIAssistant.jsx` is the feature entry point for the AI tutor.
   - The assistant is broken into `components/VedicAI/AIChatInterface.jsx`, `AIProblemGenerator.jsx`, and `AIResponse.jsx`, which suggests a chat-and-practice interaction model.
   - `components/hooks/useGeminiAI.js` and `components/services/geminiService.jsx` form the client-side integration layer to Google Gemini.

7. **Authentication and user state**
   - `AuthContext.jsx` centralizes user identity/session state for the app.
   - `SignIn` and `SignUp` feed into this auth context, while `ProtectedRoute` consumes it to gate private pages.
   - This is the main boundary between anonymous visitors and enrolled/authenticated learners.

8. **Progress and achievement state**
   - `ProgressContext.jsx` is the shared state layer for lesson completion, unlocking, and course advancement.
   - `ProgressUtils.jsx` likely contains helper logic for calculating completion state, eligibility, or certificate readiness.
   - `Certificate.jsx` appears to depend on this progress model to determine when a learner has earned completion.

9. **External platform dependencies**
   - `supabaseClient.js` is the client-side integration point to Supabase, which likely provides auth and persistent user/progress storage.
   - Gemini API access is handled separately through the AI service/hook layer, so AI requests are isolated from the rest of the app state.
   - The repo has no custom server code, so the browser app communicates directly with these external services.

10. **Build, styling, and deployment**
   - The frontend uses Vite for development/build tooling, with CRACO present as supporting config, and TailwindCSS plus Framer Motion for UI styling/animation.
   - `vercel.json` indicates deployment on Vercel as a static SPA.
   - `index.html`, `vite.config.js`, and the root CSS files define the application shell and global styling boundary.

11. **Overall data flow**
   - User enters via landing/auth pages, authenticates through Supabase, then navigates into protected learning pages.
   - Lesson interactions update progress state, which feeds dashboard/progress UI and certificate eligibility.
   - The AI assistant sits beside the learning flow as a separate interactive help path, using Gemini for problem generation and responses.

12. **Architecture summary**
   - The app is best understood as three integrated client-side subsystems: course delivery, learner state management, and AI tutoring.
   - Shared contexts and route guards coordinate those subsystems, while Supabase and Gemini provide the only major external runtime dependencies.

Main entry points: [`frontend/src/App.jsx`](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/App.jsx) (App.jsx), [`frontend/src/pages/lessons`](https://github.com/romeirofernandes/vedicmath/tree/main/frontend/src/pages/lessons) (Lessons), [`frontend/src/pages/Landing.jsx`](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/pages/Landing.jsx) (Landing), [`frontend/src/context/ProgressContext.jsx`](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/context/ProgressContext.jsx) (ProgressContext)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_shell["App shell"]
  node_main["main.jsx<br/>bootstrap<br/>[main.jsx]"]
  node_app["App.jsx<br/>router shell<br/>[App.jsx]"]
  node_protected_route{{"ProtectedRoute<br/>route guard<br/>[ProtectedRoute.jsx]"}}
end

subgraph group_group_learning["Learning flow"]
  node_header["Header<br/>layout nav<br/>[Header.jsx]"]
  node_footer["Footer<br/>[Footer.jsx]"]
  node_side_panel["SidePanel<br/>lesson nav<br/>[SidePanel.jsx]"]
  node_lesson_item["LessonItem<br/>lesson card<br/>[LessonItem.jsx]"]
  node_progress_bar["ProgressBar<br/>progress ui<br/>[ProgressBar.jsx]"]
  node_landing["Landing<br/>public page<br/>[Landing.jsx]"]
  node_signin["SignIn<br/>auth page<br/>[SignIn.jsx]"]
  node_signup["SignUp<br/>auth page<br/>[SignUp.jsx]"]
  node_dashboard["Dashboard<br/>learner page<br/>[Dashboard.jsx]"]
  node_game["Game<br/>practice page<br/>[Game.jsx]"]
  node_leaderboard["Leaderboard<br/>ranking page<br/>[Leaderboard.jsx]"]
  node_certificate["Certificate<br/>completion page<br/>[Certificate.jsx]"]
  node_lesson_series["Lessons<br/>curriculum"]
  node_lesson_animations["Tech demos<br/>visualization set"]
end

subgraph group_group_ai["AI tutor"]
  node_vedic_ai_page["VedicAI Assistant<br/>assistant page"]
  node_ai_ui["AI Chat UI<br/>assistant ui"]
  node_ai_hook["useGeminiAI<br/>ai hook<br/>[useGeminiAI.js]"]
  node_gemini_service["Gemini service<br/>ai api client<br/>[geminiService.jsx]"]
end

subgraph group_group_state["State & services"]
  node_auth_context["AuthContext<br/>session state<br/>[AuthContext.jsx]"]
  node_progress_context["ProgressContext<br/>course state"]
  node_progress_utils["ProgressUtils<br/>progress logic<br/>[ProgressUtils.jsx]"]
  node_supabase_client[("Supabase client<br/>backend client<br/>[supabaseClient.js]")]
end

node_main -->|"bootstraps"| node_app
node_app -->|"guards"| node_protected_route
node_app -->|"routes"| node_landing
node_app -->|"routes"| node_signin
node_app -->|"routes"| node_signup
node_app -->|"routes"| node_dashboard
node_app -->|"routes"| node_game
node_app -->|"routes"| node_leaderboard
node_app -->|"routes"| node_certificate
node_app -->|"routes"| node_vedic_ai_page
node_app -->|"routes"| node_lesson_series
node_landing -->|"uses"| node_header
node_landing -->|"uses"| node_footer
node_landing -.->|"shows"| node_lesson_item
node_dashboard -->|"shows"| node_progress_bar
node_dashboard -.->|"uses"| node_side_panel
node_lesson_series -->|"composes"| node_lesson_item
node_lesson_series -->|"uses"| node_side_panel
node_lesson_series -->|"updates"| node_progress_bar
node_lesson_series -->|"embeds"| node_lesson_animations
node_lesson_animations -.->|"informs"| node_progress_context
node_vedic_ai_page -->|"composes"| node_ai_ui
node_ai_ui -->|"calls"| node_ai_hook
node_ai_hook -->|"requests"| node_gemini_service
node_signin -->|"feeds"| node_auth_context
node_signup -->|"feeds"| node_auth_context
node_protected_route -->|"consumes"| node_auth_context
node_progress_context -->|"uses"| node_progress_utils
node_certificate -->|"consumes"| node_progress_context
node_progress_context -->|"persists"| node_supabase_client
node_auth_context -->|"authenticates"| node_supabase_client

click node_main "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/main.jsx"
click node_app "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/App.jsx"
click node_protected_route "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/components/ProtectedRoute.jsx"
click node_header "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/components/Header.jsx"
click node_footer "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/components/Footer.jsx"
click node_side_panel "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/components/SidePanel.jsx"
click node_lesson_item "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/components/LessonItem.jsx"
click node_progress_bar "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/components/ProgressBar.jsx"
click node_landing "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/pages/Landing.jsx"
click node_signin "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/pages/SignIn.jsx"
click node_signup "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/pages/SignUp.jsx"
click node_dashboard "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/pages/Dashboard.jsx"
click node_game "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/pages/Game.jsx"
click node_leaderboard "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/pages/Leaderboard.jsx"
click node_certificate "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/pages/Certificate.jsx"
click node_lesson_series "https://github.com/romeirofernandes/vedicmath/tree/main/frontend/src/pages/lessons"
click node_lesson_animations "https://github.com/romeirofernandes/vedicmath/tree/main/frontend/src/components"
click node_vedic_ai_page "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/pages/VedicAIAssistant.jsx"
click node_ai_ui "https://github.com/romeirofernandes/vedicmath/tree/main/frontend/src/components/VedicAI"
click node_ai_hook "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/components/hooks/useGeminiAI.js"
click node_gemini_service "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/components/services/geminiService.jsx"
click node_auth_context "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/context/AuthContext.jsx"
click node_progress_context "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/context/ProgressContext.jsx"
click node_progress_utils "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/utils/ProgressUtils.jsx"
click node_supabase_client "https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/lib/supabaseClient.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_app,node_protected_route toneBlue
class node_header,node_footer,node_side_panel,node_lesson_item,node_progress_bar,node_landing,node_signin,node_signup,node_dashboard,node_game,node_leaderboard,node_certificate,node_lesson_series,node_lesson_animations toneAmber
class node_vedic_ai_page,node_ai_ui,node_ai_hook,node_gemini_service toneMint
class node_auth_context,node_progress_context,node_progress_utils,node_supabase_client toneRose
```

## Components

### App shell

React entry, routing, and shared layout/navigation.

- [main.jsx](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/main.jsx): bootstrap · React entrypoint that mounts the app. · `frontend/src/main.jsx`
- [App.jsx](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/App.jsx): router shell · Top-level app composition and route wiring. · `frontend/src/App.jsx`
- [ProtectedRoute](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/components/ProtectedRoute.jsx): route guard · Access-control boundary for private pages. · `frontend/src/components/ProtectedRoute.jsx`

### Learning flow

Public pages, lessons, practice, and course-facing UI.

- [Header](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/components/Header.jsx): layout nav · Global header for public-facing pages. · `frontend/src/components/Header.jsx`
- [Footer](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/components/Footer.jsx): layout footer · Shared footer for the site. · `frontend/src/components/Footer.jsx`
- [SidePanel](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/components/SidePanel.jsx): lesson nav · Supplementary navigation for learning screens. · `frontend/src/components/SidePanel.jsx`
- [LessonItem](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/components/LessonItem.jsx): lesson card · Reusable lesson/content tile. · `frontend/src/components/LessonItem.jsx`
- [ProgressBar](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/components/ProgressBar.jsx): progress ui · Visual progress indicator for course completion. · `frontend/src/components/ProgressBar.jsx`
- [Landing](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/pages/Landing.jsx): public page · Public entry page and marketing surface. · `frontend/src/pages/Landing.jsx`
- [SignIn](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/pages/SignIn.jsx): auth page · User login page. · `frontend/src/pages/SignIn.jsx`
- [SignUp](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/pages/SignUp.jsx): auth page · User registration page. · `frontend/src/pages/SignUp.jsx`
- [Dashboard](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/pages/Dashboard.jsx): learner page · Authenticated learner overview. · `frontend/src/pages/Dashboard.jsx`
- [Game](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/pages/Game.jsx): practice page · Interactive practice or quiz experience. · `frontend/src/pages/Game.jsx`
- [Leaderboard](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/pages/Leaderboard.jsx): ranking page · Shared competition or score view. · `frontend/src/pages/Leaderboard.jsx`
- [Certificate](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/pages/Certificate.jsx): completion page · Completion or award page driven by progress state. · `frontend/src/pages/Certificate.jsx`
- [Lessons](https://github.com/romeirofernandes/vedicmath/tree/main/frontend/src/pages/lessons): curriculum · Structured lesson sequence for the course. · `frontend/src/pages/lessons`
- [Tech demos](https://github.com/romeirofernandes/vedicmath/tree/main/frontend/src/components): visualization set · Animated method demonstrations embedded in lessons or practice. · `frontend/src/components`

### AI tutor

Chat-based assistant and Gemini integration.

- [VedicAI Assistant](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/pages/VedicAIAssistant.jsx): assistant page · Entry page for the AI tutor experience. · `frontend/src/pages/VedicAIAssistant.jsx`
- [AI Chat UI](https://github.com/romeirofernandes/vedicmath/tree/main/frontend/src/components/VedicAI): assistant ui · Chat, prompt, and response interaction components. · `frontend/src/components/VedicAI`
- [useGeminiAI](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/components/hooks/useGeminiAI.js): ai hook · Client-side hook coordinating AI requests and state. · `frontend/src/components/hooks/useGeminiAI.js`
- [Gemini service](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/components/services/geminiService.jsx): ai api client · Low-level Gemini request/response integration. · `frontend/src/components/services/geminiService.jsx`

### State & services

Authentication, progress, and external client integrations.

- [AuthContext](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/context/AuthContext.jsx): session state · Global identity and authentication state. · `frontend/src/context/AuthContext.jsx`
- [ProgressContext](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/context/ProgressContext.jsx): course state · Shared lesson completion and advancement state. · `frontend/src/context/ProgressContext.jsx`
- [ProgressUtils](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/utils/ProgressUtils.jsx): progress logic · Helpers for completion, unlocking, and eligibility calculations. · `frontend/src/utils/ProgressUtils.jsx`
- [Supabase client](https://github.com/romeirofernandes/vedicmath/blob/main/frontend/src/lib/supabaseClient.js): backend client · Browser client for auth and persistent app data. · `frontend/src/lib/supabaseClient.js`

## Connections

- main.jsx → App.jsx: bootstraps · Main mounts the root React app.
- App.jsx → ProtectedRoute: guards · App routes authenticated pages through the guard.
- App.jsx → Landing: routes · Defines the public landing route.
- App.jsx → SignIn: routes · Defines the sign-in route.
- App.jsx → SignUp: routes · Defines the sign-up route.
- App.jsx → Dashboard: routes · Defines the learner dashboard route.
- App.jsx → Game: routes · Defines the practice/game route.
- App.jsx → Leaderboard: routes · Defines the leaderboard route.
- App.jsx → Certificate: routes · Defines the certificate route.
- App.jsx → VedicAI Assistant: routes · Defines the AI assistant route.
- App.jsx → Lessons: routes · Links the lesson curriculum into the app.
- Landing → Header: uses · Landing shares the global header.
- Landing → Footer: uses · Landing shares the global footer.
- Landing → LessonItem: shows · Landing may surface featured lessons or cards.
- Dashboard → ProgressBar: shows · Dashboard visualizes learner progress.
- Dashboard → SidePanel: uses · Dashboard includes navigation or learning context panels.
- Lessons → LessonItem: composes · Lesson pages reuse the lesson item component.
- Lessons → SidePanel: uses · Lesson flow is supported by side navigation.
- Lessons → ProgressBar: updates · Lesson completion feeds progress visualization.
- Lessons → Tech demos: embeds · Lessons embed technique demonstrations.
- Tech demos → ProgressContext: informs · Interactive learning state contributes to progress tracking.
- VedicAI Assistant → AI Chat UI: composes · Assistant page is built from AI chat components.
- AI Chat UI → useGeminiAI: calls · Chat UI uses the Gemini hook for generation.
- useGeminiAI → Gemini service: requests · Hook delegates API traffic to the Gemini service layer.
- SignIn → AuthContext: feeds · Sign-in updates shared auth state.
- SignUp → AuthContext: feeds · Sign-up updates shared auth state.
- ProtectedRoute → AuthContext: consumes · Route guard checks current user/session state.
- ProgressContext → ProgressUtils: uses · Shared state relies on progress calculations.
- Certificate → ProgressContext: consumes · Certificate eligibility depends on progress state.
- ProgressContext → Supabase client: persists · Progress state is backed by Supabase storage.
- AuthContext → Supabase client: authenticates · Auth state is backed by Supabase auth.
