How romeirofernandes/vedicmath works
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: App.jsx App.jsx · lessons Lessons · Landing.jsx Landing · ProgressContext.jsx ProgressContext
Components 25
App shell
React entry, routing, and shared layout/navigation.
- main.jsx · React entrypoint that mounts the app.
frontend/src/main.jsx - App.jsx · Top-level app composition and route wiring.
frontend/src/App.jsx - ProtectedRoute · Access-control boundary for private pages.
frontend/src/components/ProtectedRoute.jsx
Learning flow
Public pages, lessons, practice, and course-facing UI.
- Header · Global header for public-facing pages.
frontend/src/components/Header.jsx - Footer · Shared footer for the site.
frontend/src/components/Footer.jsx - SidePanel · Supplementary navigation for learning screens.
frontend/src/components/SidePanel.jsx - LessonItem · Reusable lesson/content tile.
frontend/src/components/LessonItem.jsx - ProgressBar · Visual progress indicator for course completion.
frontend/src/components/ProgressBar.jsx - Landing · Public entry page and marketing surface.
frontend/src/pages/Landing.jsx - SignIn · User login page.
frontend/src/pages/SignIn.jsx - SignUp · User registration page.
frontend/src/pages/SignUp.jsx - Dashboard · Authenticated learner overview.
frontend/src/pages/Dashboard.jsx - Game · Interactive practice or quiz experience.
frontend/src/pages/Game.jsx - Leaderboard · Shared competition or score view.
frontend/src/pages/Leaderboard.jsx - Certificate · Completion or award page driven by progress state.
frontend/src/pages/Certificate.jsx - Lessons · Structured lesson sequence for the course.
frontend/src/pages/lessons - Tech demos · Animated method demonstrations embedded in lessons or practice.
frontend/src/components
AI tutor
Chat-based assistant and Gemini integration.
- VedicAI Assistant · Entry page for the AI tutor experience.
frontend/src/pages/VedicAIAssistant.jsx - AI Chat UI · Chat, prompt, and response interaction components.
frontend/src/components/VedicAI - useGeminiAI · Client-side hook coordinating AI requests and state.
frontend/src/components/hooks/useGeminiAI.js - Gemini service · Low-level Gemini request/response integration.
frontend/src/components/services/geminiService.jsx
State & services
Authentication, progress, and external client integrations.
- AuthContext · Global identity and authentication state.
frontend/src/context/AuthContext.jsx - ProgressContext · Shared lesson completion and advancement state.
frontend/src/context/ProgressContext.jsx - ProgressUtils · Helpers for completion, unlocking, and eligibility calculations.
frontend/src/utils/ProgressUtils.jsx - Supabase client · Browser client for auth and persistent app data.
frontend/src/lib/supabaseClient.js
Connections 31
- 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.