# jewinjibu/eduspark architecture

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

- Interactive diagram: https://gitdiagram.com/jewinjibu/eduspark
- Repository: https://github.com/jewinjibu/eduspark

## Overview

#### Purpose and Runtime
EduSpark 2.1 is a TypeScript React learning platform: curriculum browsing, topic learning, quizzes, missions, flashcards, progress, an IDE, certificates, and an AI-assisted coding workspace. The browser app is built and served by Vite; a separate Node/Express service proxies AI requests to OpenRouter. Entry points are `src/main.tsx`, `src/App.tsx`, and `server/server.js`.

#### Application Shell and Navigation
`src/App.tsx` is the likely composition and route-selection boundary for page-level experiences. Shared presentation and fault containment sit around those pages through `src/components/AppLayout.tsx` and `src/components/ErrorBoundary.tsx`. Page modules under `src/pages/`, notably `src/pages/LearningWorkspace.tsx`, `src/pages/IDEPage.tsx`, and `src/pages/SubjectDetailPage.tsx`, own major user workflows rather than a server-rendered backend.

#### Learning Content and Curriculum Flow
Curriculum is primarily client-owned static data: subject, course, lesson, quiz, mission, and flashcard definitions in `src/data/subjects.ts`, `src/data/lessons.ts`, and `src/data/courseSchema.json` (with language-specific JSON datasets alongside them). Users move from subject/topic views into learning content and practice; reusable content renderers include `src/components/LanguageSection.tsx`, `src/components/LessonCard.tsx`, and `src/components/CodePractice.tsx`.

#### User State, Authentication, and Persistence Boundary
Firebase is the external identity/application-service boundary, initialized in `src/lib/firebase.ts`. Authentication state is exposed through `src/contexts/AuthContext.tsx` and consumed via `src/hooks/useAuth.ts`. Learning-state concerns are separated into focused hooks—progress, streaks, missions, notifications, recommendations, and spaced repetition—such as `src/hooks/useProgress.ts`, `src/hooks/useMissions.ts`, and `src/hooks/useSpacedRepetition.ts`; shared client state utilities reside in `src/lib/store.ts`.

#### Learning Feature Modules
Feature directories package interactive learning surfaces independently from general pages: quizzes (`src/features/quiz/QuizPanel.tsx`), flashcards (`src/features/flashcards/FlashcardPanel.tsx`), missions (`src/features/missions/MissionPanel.tsx`), and mastery/progress (`src/features/progress/MasteryPanel.tsx`). This creates a flow from static curriculum and authenticated learner state into task-specific panels, then back into progress-oriented hooks/state.

#### IDE and AI Coding OS
The coding environment is split between a conventional IDE workspace—`src/features/ide/IDE.tsx`, `src/features/ide/IDEWorkspace.tsx`, `src/features/ide/VisualBlockEditor.tsx`—and the broader AI Coding OS at `src/features/ai-coding-os/AICodingOS.tsx`. The latter organizes Learn/Build/Debug/Review/Ship/Grow stages through panel modules such as `src/features/ai-coding-os/panels/BuildPanel.tsx` and `src/features/ai-coding-os/panels/DebugPanel.tsx`, backed by local concepts, paths, templates, and progression logic in `src/features/ai-coding-os/data/` and `src/features/ai-coding-os/lib/progression.ts`.

#### AI Service and Deployment Boundary
The browser must not call OpenRouter with credentials directly. `server/server.js` owns `/api/ai/*` proxy behavior, obtains `OPENROUTER_API_KEY` from `server/.env`, and can enforce Bearer-token and CORS-origin controls. The front end’s AI integration surface includes `src/hooks/useAIModels.ts`; requests cross from Vite-hosted client code to Express, then OpenRouter. Production frontend deployment is configured by `vercel.json`; the Express server remains a separately runnable/deployable Node service.

Main entry points: [`src/pages/LearningWorkspace.tsx`](https://github.com/jewinjibu/eduspark/blob/main/src/pages/LearningWorkspace.tsx) (Learning pages), [`src/App.tsx`](https://github.com/jewinjibu/eduspark/blob/main/src/App.tsx) (App and route selection), [`src/data/subjects.ts`](https://github.com/jewinjibu/eduspark/blob/main/src/data/subjects.ts) (Curriculum datasets), [`src/hooks/useProgress.ts`](https://github.com/jewinjibu/eduspark/blob/main/src/hooks/useProgress.ts) (Learner state hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser application"]
  node_main(("React entry<br/>entry point<br/>[main.tsx]"))
  node_app["App and route selection<br/>application shell<br/>[App.tsx]"]
  node_layout["Layout and error boundary<br/>shared presentation<br/>[AppLayout.tsx]"]
  node_pages["Learning pages<br/>page workflows"]
end

subgraph group_learning["Learning domain"]
  node_curriculum["Curriculum datasets<br/>static content<br/>[subjects.ts]"]
  node_content["Learning content renderers<br/>content components"]
  node_auth["Auth context<br/>identity state<br/>[AuthContext.tsx]"]
  node_firebase[("Firebase<br/>external application service<br/>[firebase.ts]")]
  node_learnerstate["Learner state hooks<br/>client state<br/>[useProgress.ts]"]
  node_quiz["Quiz panel<br/>learning feature<br/>[QuizPanel.tsx]"]
  node_flashcards["Flashcard panel<br/>learning feature<br/>[FlashcardPanel.tsx]"]
  node_missions["Mission panel<br/>learning feature<br/>[MissionPanel.tsx]"]
  node_mastery["Mastery panel<br/>progress feature<br/>[MasteryPanel.tsx]"]
end

subgraph group_coding["Coding workspaces"]
  node_ide["IDE workspace<br/>coding feature<br/>[IDEWorkspace.tsx]"]
  node_aios["AI Coding OS<br/>coding workflow<br/>[AICodingOS.tsx]"]
  node_aiprogression["AI progression logic<br/>workspace domain logic<br/>[progression.ts]"]
  node_aimodels["AI model client<br/>client integration<br/>[useAIModels.ts]"]
end

subgraph group_ai["AI service boundary"]
  node_express{{"Express AI proxy<br/>Node service<br/>[server.js]"}}
  node_openrouter{{"OpenRouter<br/>external AI provider"}}
end

node_main -->|"mounts"| node_app
node_app -->|"wraps with"| node_layout
node_app -->|"selects workflows"| node_pages
node_pages -->|"browses"| node_curriculum
node_pages -->|"renders"| node_content
node_pages -->|"opens"| node_ide
node_pages -->|"opens"| node_aios
node_auth -->|"uses"| node_firebase
node_app -->|"provides session"| node_auth
node_curriculum -->|"supplies practice data"| node_quiz
node_curriculum -->|"supplies cards"| node_flashcards
node_curriculum -->|"supplies missions"| node_missions
node_quiz -->|"records outcomes"| node_learnerstate
node_flashcards -->|"updates repetition"| node_learnerstate
node_missions -->|"updates progress"| node_learnerstate
node_learnerstate -->|"drives"| node_mastery
node_aios -->|"uses"| node_aiprogression
node_aios -->|"requests assistance"| node_aimodels
node_aimodels -->|"calls /api/ai/*"| node_express
node_express -->|"proxies authenticated requests"| node_openrouter

click node_main "https://github.com/jewinjibu/eduspark/blob/main/src/main.tsx"
click node_app "https://github.com/jewinjibu/eduspark/blob/main/src/App.tsx"
click node_layout "https://github.com/jewinjibu/eduspark/blob/main/src/components/AppLayout.tsx"
click node_pages "https://github.com/jewinjibu/eduspark/blob/main/src/pages/LearningWorkspace.tsx"
click node_curriculum "https://github.com/jewinjibu/eduspark/blob/main/src/data/subjects.ts"
click node_content "https://github.com/jewinjibu/eduspark/blob/main/src/components/LanguageSection.tsx"
click node_auth "https://github.com/jewinjibu/eduspark/blob/main/src/contexts/AuthContext.tsx"
click node_firebase "https://github.com/jewinjibu/eduspark/blob/main/src/lib/firebase.ts"
click node_learnerstate "https://github.com/jewinjibu/eduspark/blob/main/src/hooks/useProgress.ts"
click node_quiz "https://github.com/jewinjibu/eduspark/blob/main/src/features/quiz/QuizPanel.tsx"
click node_flashcards "https://github.com/jewinjibu/eduspark/blob/main/src/features/flashcards/FlashcardPanel.tsx"
click node_missions "https://github.com/jewinjibu/eduspark/blob/main/src/features/missions/MissionPanel.tsx"
click node_mastery "https://github.com/jewinjibu/eduspark/blob/main/src/features/progress/MasteryPanel.tsx"
click node_ide "https://github.com/jewinjibu/eduspark/blob/main/src/features/ide/IDEWorkspace.tsx"
click node_aios "https://github.com/jewinjibu/eduspark/blob/main/src/features/ai-coding-os/AICodingOS.tsx"
click node_aiprogression "https://github.com/jewinjibu/eduspark/blob/main/src/features/ai-coding-os/lib/progression.ts"
click node_aimodels "https://github.com/jewinjibu/eduspark/blob/main/src/hooks/useAIModels.ts"
click node_express "https://github.com/jewinjibu/eduspark/blob/main/server/server.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_layout,node_pages toneBlue
class node_curriculum,node_content,node_auth,node_firebase,node_learnerstate,node_quiz,node_flashcards,node_missions,node_mastery toneAmber
class node_ide,node_aios,node_aiprogression,node_aimodels toneMint
class node_express,node_openrouter toneRose
```

## Components

### Browser application

Vite-built React client.

- [React entry](https://github.com/jewinjibu/eduspark/blob/main/src/main.tsx): entry point · `src/main.tsx`
- [App and route selection](https://github.com/jewinjibu/eduspark/blob/main/src/App.tsx): application shell · `src/App.tsx`
- [Layout and error boundary](https://github.com/jewinjibu/eduspark/blob/main/src/components/AppLayout.tsx): shared presentation · `src/components/AppLayout.tsx`
- [Learning pages](https://github.com/jewinjibu/eduspark/blob/main/src/pages/LearningWorkspace.tsx): page workflows · Subject detail, learning workspace, and IDE page experiences. · `src/pages/LearningWorkspace.tsx`

### Learning domain

Curriculum, learner state, and practice modules.

- [Curriculum datasets](https://github.com/jewinjibu/eduspark/blob/main/src/data/subjects.ts): static content · Subjects, lessons, schemas, and language datasets. · `src/data/subjects.ts`
- [Learning content renderers](https://github.com/jewinjibu/eduspark/blob/main/src/components/LanguageSection.tsx): content components · Lesson, language, and code-practice surfaces. · `src/components/LanguageSection.tsx`
- [Auth context](https://github.com/jewinjibu/eduspark/blob/main/src/contexts/AuthContext.tsx): identity state · `src/contexts/AuthContext.tsx`
- [Firebase](https://github.com/jewinjibu/eduspark/blob/main/src/lib/firebase.ts): external application service · Identity and application-service boundary. · `src/lib/firebase.ts`
- [Learner state hooks](https://github.com/jewinjibu/eduspark/blob/main/src/hooks/useProgress.ts): client state · Progress, missions, streaks, recommendations, and spaced repetition. · `src/hooks/useProgress.ts`
- [Quiz panel](https://github.com/jewinjibu/eduspark/blob/main/src/features/quiz/QuizPanel.tsx): learning feature · `src/features/quiz/QuizPanel.tsx`
- [Flashcard panel](https://github.com/jewinjibu/eduspark/blob/main/src/features/flashcards/FlashcardPanel.tsx): learning feature · `src/features/flashcards/FlashcardPanel.tsx`
- [Mission panel](https://github.com/jewinjibu/eduspark/blob/main/src/features/missions/MissionPanel.tsx): learning feature · `src/features/missions/MissionPanel.tsx`
- [Mastery panel](https://github.com/jewinjibu/eduspark/blob/main/src/features/progress/MasteryPanel.tsx): progress feature · `src/features/progress/MasteryPanel.tsx`

### Coding workspaces

IDE and AI-assisted coding experiences.

- [IDE workspace](https://github.com/jewinjibu/eduspark/blob/main/src/features/ide/IDEWorkspace.tsx): coding feature · Conventional IDE and visual block editing workspace. · `src/features/ide/IDEWorkspace.tsx`
- [AI Coding OS](https://github.com/jewinjibu/eduspark/blob/main/src/features/ai-coding-os/AICodingOS.tsx): coding workflow · Learn, Build, Debug, Review, Ship, and Grow stages. · `src/features/ai-coding-os/AICodingOS.tsx`
- [AI progression logic](https://github.com/jewinjibu/eduspark/blob/main/src/features/ai-coding-os/lib/progression.ts): workspace domain logic · Local paths, templates, concepts, and progression. · `src/features/ai-coding-os/lib/progression.ts`
- [AI model client](https://github.com/jewinjibu/eduspark/blob/main/src/hooks/useAIModels.ts): client integration · `src/hooks/useAIModels.ts`

### AI service boundary

Credentials stay behind the Express proxy.

- [Express AI proxy](https://github.com/jewinjibu/eduspark/blob/main/server/server.js): Node service · Owns /api/ai/*, credentials, Bearer controls, and CORS. · `server/server.js`
- **OpenRouter**: external AI provider

## Connections

- React entry → App and route selection: mounts
- App and route selection → Layout and error boundary: wraps with
- App and route selection → Learning pages: selects workflows
- Learning pages → Curriculum datasets: browses
- Learning pages → Learning content renderers: renders
- Learning pages → IDE workspace: opens
- Learning pages → AI Coding OS: opens
- Auth context → Firebase: uses
- App and route selection → Auth context: provides session
- Curriculum datasets → Quiz panel: supplies practice data
- Curriculum datasets → Flashcard panel: supplies cards
- Curriculum datasets → Mission panel: supplies missions
- Quiz panel → Learner state hooks: records outcomes
- Flashcard panel → Learner state hooks: updates repetition
- Mission panel → Learner state hooks: updates progress
- Learner state hooks → Mastery panel: drives
- AI Coding OS → AI progression logic: uses
- AI Coding OS → AI model client: requests assistance
- AI model client → Express AI proxy: calls /api/ai/*
- Express AI proxy → OpenRouter: proxies authenticated requests