# ubuttomkumar-commits/linguaverse-ai architecture

> Architecture diagram of the GitHub repository ubuttomkumar-commits/linguaverse-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ubuttomkumar-commits/linguaverse-ai
- Repository: https://github.com/ubuttomkumar-commits/linguaverse-ai

## Overview

LINGUAVERSE AI is a bilingual, voice-first English-learning and communication platform for Bangla-speaking learners. The learner workflow runs from onboarding and diagnostic assessment into structured Academy lessons, then targeted mistake practice, speaking simulations, and real-world Transfer Lab evaluation; Progress summarizes learning evidence. AuthContext hydrates learner state through a selectable persistence repository. The README documents additional privacy, verified-XP, and admin-governance capabilities. Some pages and integrations are unsampled, so those capability links rely on README evidence rather than inspected implementation.

Main entry points: [`src/App.tsx`](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/App.tsx) (Routes and access), [`src/pages/learner/TransferLabPage.tsx`](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/pages/learner/TransferLabPage.tsx) (Transfer Lab), [`src/pages/admin/AdminControlCenterPage.tsx`](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/pages/admin/AdminControlCenterPage.tsx) (Admin Control Center), [`src/context/AuthContext.tsx`](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/context/AuthContext.tsx) (Auth and learner state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learner experience"]
  node_app["Routes and access<br/>[App.tsx]"]
  node_auth["Auth and learner state<br/>[AuthContext.tsx]"]
  node_academy["Academy lessons"]
  node_diagnostic["Diagnostic assessment<br/>[DiagnosticPage.tsx]"]
  node_speaking["Speaking Studio"]
  node_improve["Mistake practice<br/>[ImprovePage.tsx]"]
  node_transfer["Transfer Lab"]
  node_progress["Progress insights<br/>[ProgressPage.tsx]"]
  node_settings["Privacy settings<br/>[SettingsPage.tsx]"]
  node_adminui["Admin Control Center"]
  node_language["Bilingual interface"]
end

subgraph group_learning["Learning engines"]
  node_curriculum["Curriculum and lessons<br/>[curriculumData.ts]"]
  node_lessonengine["Lesson mastery<br/>[lessonEngine.ts]"]
  node_diagnosticengine["Diagnostic engine"]
  node_mistakes["Mistake Memory"]
  node_dna["Communication DNA"]
  node_intelligence["Learning intelligence"]
  node_scenarios["Speaking scenarios"]
  node_pressure["Pressure Ladder<br/>[pressureLadder.ts]"]
  node_transferengine["Transfer evaluation logic"]
  node_gamification["Verified XP ledger"]
end

subgraph group_evidence["Evidence and persistence"]
  node_repo["Repository interface<br/>[repository.ts]"]
  node_storage["Selectable persistence<br/>[index.ts]"]
  node_localrepo[("Local repository<br/>[localRepository.ts]")]
  node_cloudrepo["D1 API repository<br/>[d1ApiRepository.ts]"]
end

subgraph group_ai["AI evaluation"]
  node_speakingapi["Speaking API client<br/>[speakingApi.ts]"]
  node_transferapi["Transfer API client<br/>[transferApi.ts]"]
  node_server["API route server<br/>[server.ts]"]
  node_geminispeaking["Gemini speaking evaluator<br/>[geminiSpeaking.ts]"]
  node_geminitransfer["Gemini transfer evaluator<br/>[geminiTransfer.ts]"]
end

subgraph group_governance["Governance and privacy"]
  node_governance["Governance rules"]
  node_governancestore["Governance records<br/>[governanceStore.ts]"]
  node_curriculastore["Curriculum overlay store<br/>[curriculumStore.ts]"]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_app
node_app -->|"routes to"| node_diagnostic
node_app -->|"routes to"| node_academy
node_app -->|"routes to"| node_speaking
node_app -->|"routes to"| node_improve
node_app -->|"routes to"| node_transfer
node_app -->|"routes to"| node_progress
node_app -->|"routes to"| node_settings
node_app -->|"routes to"| node_adminui
node_app -->|"guards routes"| node_auth
node_auth -->|"loads learner data"| node_storage
node_storage -->|"implements contract"| node_repo
node_storage -->|"selects backend"| node_localrepo
node_storage -->|"selects backend"| node_cloudrepo
node_diagnostic -.->|"assesses"| node_diagnosticengine
node_academy -.->|"uses lessons"| node_curriculum
node_academy -.->|"records mastery"| node_lessonengine
node_improve -.->|"drills errors"| node_mistakes
node_speaking -->|"submits evaluation"| node_speakingapi
node_speaking -->|"loads scenarios"| node_scenarios
node_speaking -.->|"sets pressure"| node_pressure
node_speakingapi -.->|"calls endpoint"| node_server
node_server -->|"dispatches to"| node_geminispeaking
node_geminispeaking -->|"evaluates with"| node_speakingapi
node_transfer -->|"prepares scenario"| node_transferengine
node_transfer -->|"submits evaluation"| node_transferapi
node_transfer -->|"selects tier"| node_pressure
node_transfer -->|"uses evaluation service"| node_speakingapi
node_transferapi -.->|"calls endpoint"| node_server
node_server -->|"dispatches to"| node_geminitransfer
node_geminitransfer -->|"builds rubric"| node_transferengine
node_transferengine -->|"classifies patterns"| node_mistakes
node_transferengine -->|"reads tiers"| node_pressure
node_progress -.->|"shows dimensions"| node_dna
node_progress -->|"shows insights"| node_intelligence
node_intelligence -->|"classifies errors"| node_mistakes
node_dna -->|"uses error evidence"| node_mistakes
node_auth -->|"computes verified XP"| node_gamification
node_localrepo -->|"scores diagnostic"| node_diagnosticengine
node_localrepo -->|"awards XP"| node_gamification
node_adminui -->|"manages policy"| node_governance
node_adminui -->|"edits curriculum"| node_curriculum
node_adminui -->|"updates overlay"| node_curriculastore
node_adminui -->|"manages records"| node_governancestore
node_governancestore -->|"uses governance rules"| node_governance
node_curriculum -->|"merges overlay"| node_curriculastore
node_settings -.->|"manages account"| node_auth
node_auth -->|"audits privacy actions"| node_governancestore

click node_app "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/App.tsx"
click node_auth "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/context/AuthContext.tsx"
click node_academy "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/pages/learner/LessonPlayerPage.tsx"
click node_diagnostic "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/pages/DiagnosticPage.tsx"
click node_speaking "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/pages/learner/SpeakStudioPage.tsx"
click node_improve "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/pages/learner/ImprovePage.tsx"
click node_transfer "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/pages/learner/TransferLabPage.tsx"
click node_progress "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/pages/learner/ProgressPage.tsx"
click node_settings "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/pages/learner/SettingsPage.tsx"
click node_adminui "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/pages/admin/AdminControlCenterPage.tsx"
click node_curriculum "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/curriculumData.ts"
click node_lessonengine "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/lessonEngine.ts"
click node_diagnosticengine "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/diagnosticEngine.ts"
click node_mistakes "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/mistakeMemoryEngine.ts"
click node_dna "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/communicationDnaEngine.ts"
click node_intelligence "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/personalIntelligenceEngine.ts"
click node_scenarios "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/speakingScenarios.ts"
click node_pressure "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/pressureLadder.ts"
click node_transferengine "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/transferLabEngine.ts"
click node_gamification "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/gamificationEngine.ts"
click node_repo "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/services/storage/repository.ts"
click node_storage "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/services/storage/index.ts"
click node_localrepo "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/services/storage/localRepository.ts"
click node_cloudrepo "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/services/storage/d1ApiRepository.ts"
click node_speakingapi "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/services/speakingApi.ts"
click node_transferapi "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/services/transferApi.ts"
click node_server "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/server.ts"
click node_geminispeaking "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/server/geminiSpeaking.ts"
click node_geminitransfer "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/server/geminiTransfer.ts"
click node_governance "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/adminGovernanceEngine.ts"
click node_governancestore "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/services/governanceStore.ts"
click node_curriculastore "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/services/curriculumStore.ts"
click node_language "https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/i18n/LanguageContext.tsx"

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_app,node_auth,node_academy,node_diagnostic,node_speaking,node_improve,node_transfer,node_progress,node_settings,node_adminui,node_language toneBlue
class node_curriculum,node_lessonengine,node_diagnosticengine,node_mistakes,node_dna,node_intelligence,node_scenarios,node_pressure,node_transferengine,node_gamification toneAmber
class node_repo,node_storage,node_localrepo,node_cloudrepo toneMint
class node_speakingapi,node_transferapi,node_server,node_geminispeaking,node_geminitransfer toneRose
class node_governance,node_governancestore,node_curriculastore,node_learner toneIndigo
```

## Components

### Learner experience

- [Routes and access](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/App.tsx): `src/App.tsx`
- [Auth and learner state](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/context/AuthContext.tsx): `src/context/AuthContext.tsx`
- [Academy lessons](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/pages/learner/LessonPlayerPage.tsx): `src/pages/learner/LessonPlayerPage.tsx`
- [Diagnostic assessment](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/pages/DiagnosticPage.tsx): `src/pages/DiagnosticPage.tsx`
- [Speaking Studio](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/pages/learner/SpeakStudioPage.tsx): `src/pages/learner/SpeakStudioPage.tsx`
- [Mistake practice](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/pages/learner/ImprovePage.tsx): `src/pages/learner/ImprovePage.tsx`
- [Transfer Lab](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/pages/learner/TransferLabPage.tsx): `src/pages/learner/TransferLabPage.tsx`
- [Progress insights](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/pages/learner/ProgressPage.tsx): `src/pages/learner/ProgressPage.tsx`
- [Privacy settings](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/pages/learner/SettingsPage.tsx): `src/pages/learner/SettingsPage.tsx`
- [Admin Control Center](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/pages/admin/AdminControlCenterPage.tsx): `src/pages/admin/AdminControlCenterPage.tsx`
- [Bilingual interface](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/i18n/LanguageContext.tsx): `src/i18n/LanguageContext.tsx`

### Learning engines

- [Curriculum and lessons](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/curriculumData.ts): `src/domain/curriculumData.ts`
- [Lesson mastery](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/lessonEngine.ts): `src/domain/lessonEngine.ts`
- [Diagnostic engine](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/diagnosticEngine.ts): `src/domain/diagnosticEngine.ts`
- [Mistake Memory](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/mistakeMemoryEngine.ts): `src/domain/mistakeMemoryEngine.ts`
- [Communication DNA](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/communicationDnaEngine.ts): `src/domain/communicationDnaEngine.ts`
- [Learning intelligence](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/personalIntelligenceEngine.ts): `src/domain/personalIntelligenceEngine.ts`
- [Speaking scenarios](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/speakingScenarios.ts): `src/domain/speakingScenarios.ts`
- [Pressure Ladder](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/pressureLadder.ts): `src/domain/pressureLadder.ts`
- [Transfer evaluation logic](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/transferLabEngine.ts): `src/domain/transferLabEngine.ts`
- [Verified XP ledger](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/gamificationEngine.ts): `src/domain/gamificationEngine.ts`

### Evidence and persistence

- [Repository interface](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/services/storage/repository.ts): `src/services/storage/repository.ts`
- [Selectable persistence](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/services/storage/index.ts): `src/services/storage/index.ts`
- [Local repository](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/services/storage/localRepository.ts): `src/services/storage/localRepository.ts`
- [D1 API repository](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/services/storage/d1ApiRepository.ts): `src/services/storage/d1ApiRepository.ts`

### AI evaluation

- [Speaking API client](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/services/speakingApi.ts): `src/services/speakingApi.ts`
- [Transfer API client](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/services/transferApi.ts): `src/services/transferApi.ts`
- [API route server](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/server.ts): `server.ts`
- [Gemini speaking evaluator](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/server/geminiSpeaking.ts): `server/geminiSpeaking.ts`
- [Gemini transfer evaluator](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/server/geminiTransfer.ts): `server/geminiTransfer.ts`

### Governance and privacy

- [Governance rules](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/domain/adminGovernanceEngine.ts): `src/domain/adminGovernanceEngine.ts`
- [Governance records](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/services/governanceStore.ts): `src/services/governanceStore.ts`
- [Curriculum overlay store](https://github.com/ubuttomkumar-commits/linguaverse-ai/blob/main/src/services/curriculumStore.ts): `src/services/curriculumStore.ts`

### Other components

- **Learner**

## Connections

- Learner → Routes and access: uses (evidence: `README.md`)
- Routes and access → Diagnostic assessment: routes to (evidence: `src/App.tsx`)
- Routes and access → Academy lessons: routes to (evidence: `src/App.tsx`)
- Routes and access → Speaking Studio: routes to (evidence: `src/App.tsx`)
- Routes and access → Mistake practice: routes to (evidence: `src/App.tsx`)
- Routes and access → Transfer Lab: routes to (evidence: `src/App.tsx`)
- Routes and access → Progress insights: routes to (evidence: `src/App.tsx`)
- Routes and access → Privacy settings: routes to (evidence: `src/App.tsx`)
- Routes and access → Admin Control Center: routes to (evidence: `src/App.tsx`)
- Routes and access → Auth and learner state: guards routes (evidence: `src/App.tsx`)
- Auth and learner state → Selectable persistence: loads learner data (evidence: `src/context/AuthContext.tsx`)
- Selectable persistence → Repository interface: implements contract (evidence: `src/services/storage/index.ts`)
- Selectable persistence → Local repository: selects backend (evidence: `src/services/storage/index.ts`)
- Selectable persistence → D1 API repository: selects backend (evidence: `src/services/storage/index.ts`)
- Diagnostic assessment → Diagnostic engine: assesses
- Academy lessons → Curriculum and lessons: uses lessons
- Academy lessons → Lesson mastery: records mastery
- Mistake practice → Mistake Memory: drills errors
- Speaking Studio → Speaking API client: submits evaluation (evidence: `src/pages/learner/SpeakStudioPage.tsx`)
- Speaking Studio → Speaking scenarios: loads scenarios (evidence: `src/pages/learner/SpeakStudioPage.tsx`)
- Speaking Studio → Pressure Ladder: sets pressure
- Speaking API client → API route server: calls endpoint
- API route server → Gemini speaking evaluator: dispatches to (evidence: `server.ts`)
- Gemini speaking evaluator → Speaking API client: evaluates with (evidence: `server/geminiSpeaking.ts`)
- Transfer Lab → Transfer evaluation logic: prepares scenario (evidence: `src/pages/learner/TransferLabPage.tsx`)
- Transfer Lab → Transfer API client: submits evaluation (evidence: `src/pages/learner/TransferLabPage.tsx`)
- Transfer Lab → Pressure Ladder: selects tier (evidence: `src/pages/learner/TransferLabPage.tsx`)
- Transfer Lab → Speaking API client: uses evaluation service (evidence: `src/pages/learner/TransferLabPage.tsx`)
- Transfer API client → API route server: calls endpoint
- API route server → Gemini transfer evaluator: dispatches to (evidence: `server.ts`)
- Gemini transfer evaluator → Transfer evaluation logic: builds rubric (evidence: `server/geminiTransfer.ts`)
- Transfer evaluation logic → Mistake Memory: classifies patterns (evidence: `src/domain/transferLabEngine.ts`)
- Transfer evaluation logic → Pressure Ladder: reads tiers (evidence: `src/domain/transferLabEngine.ts`)
- Progress insights → Communication DNA: shows dimensions
- Progress insights → Learning intelligence: shows insights
- Learning intelligence → Mistake Memory: classifies errors (evidence: `src/domain/personalIntelligenceEngine.ts`)
- Communication DNA → Mistake Memory: uses error evidence (evidence: `src/domain/communicationDnaEngine.ts`)
- Auth and learner state → Verified XP ledger: computes verified XP (evidence: `src/context/AuthContext.tsx`)
- Local repository → Diagnostic engine: scores diagnostic (evidence: `src/services/storage/localRepository.ts`)
- Local repository → Verified XP ledger: awards XP (evidence: `src/services/storage/localRepository.ts`)
- Admin Control Center → Governance rules: manages policy (evidence: `src/pages/admin/AdminControlCenterPage.tsx`)
- Admin Control Center → Curriculum and lessons: edits curriculum (evidence: `src/pages/admin/AdminControlCenterPage.tsx`)
- Admin Control Center → Curriculum overlay store: updates overlay (evidence: `src/pages/admin/AdminControlCenterPage.tsx`)
- Admin Control Center → Governance records: manages records (evidence: `src/pages/admin/AdminControlCenterPage.tsx`)
- Governance records → Governance rules: uses governance rules (evidence: `src/services/governanceStore.ts`)
- Curriculum and lessons → Curriculum overlay store: merges overlay (evidence: `src/domain/curriculumData.ts`)
- Privacy settings → Auth and learner state: manages account
- Auth and learner state → Governance records: audits privacy actions (evidence: `src/context/AuthContext.tsx`)
