# tharani927/lingualearn architecture

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

- Interactive diagram: https://gitdiagram.com/tharani927/lingualearn
- Repository: https://github.com/tharani927/lingualearn

## Overview

LinguaLearn is a React-and-Express language-learning platform. Learners authenticate, browse courses, complete lessons and assessments, then receive diagnostic feedback and can revisit mistakes, track skills, and earn achievements or certificates. Administrators manage users, courses and questions, and inspect analytics and reports. The graph follows the documented browser-to-API flow and sampled module calls; several domain services are represented by their actual service paths, but unshown controller-to-service wiring and database relationships are omitted where evidence is unavailable.

Main entry points: [`backend/src/config/db.js`](https://github.com/tharani927/lingualearn/blob/main/backend/src/config/db.js) (PostgreSQL pool), [`frontend/src/services/api.js`](https://github.com/tharani927/lingualearn/blob/main/frontend/src/services/api.js) (API client), [`frontend/src/App.jsx`](https://github.com/tharani927/lingualearn/blob/main/frontend/src/App.jsx) (Routed SPA), [`backend/src/routes/index.js`](https://github.com/tharani927/lingualearn/blob/main/backend/src/routes/index.js) (API route registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learner and Admin App"]
  node_app["Routed SPA<br/>[App.jsx]"]
  node_authctx["Session context<br/>[AuthContext.jsx]"]
  node_apiclient["API client<br/>[api.js]"]
  node_learnerui["Learning screens"]
  node_adminui["Admin screens"]
  node_theme["Theme preferences<br/>[ThemeContext.jsx]"]
end

subgraph group_api["API and Identity"]
  node_apiapp["Express API<br/>[app.js]"]
  node_routes["API route registry<br/>[index.js]"]
  node_authroutes["Authentication routes<br/>[authRoutes.js]"]
  node_authctrl["Authentication controller<br/>[authController.js]"]
  node_authsvc["Identity service<br/>[authService.js]"]
  node_authmw["JWT authentication<br/>[auth.js]"]
  node_courseroutes["Course routes<br/>[courseRoutes.js]"]
  node_coursectrl["Course controller"]
  node_adminroutes["Admin routes<br/>[adminRoutes.js]"]
end

subgraph group_learning["Learning Services"]
  node_coursesvc["Course service<br/>[courseService.js]"]
  node_lessonsvc["Lesson service<br/>[lessonService.js]"]
  node_assesssvc["Assessment service"]
  node_adaptivesvc["Adaptive learning"]
  node_aisvc["AI diagnostics<br/>[aiService.js]"]
  node_gamesvc["Gamification"]
end

subgraph group_insight["Insights and Admin"]
  node_adminctrl["Admin controller<br/>[adminController.js]"]
  node_adminsvc["Admin service<br/>[adminService.js]"]
  node_analytics["Analytics service"]
  node_reports["Reports service<br/>[reportService.js]"]
end

subgraph group_state["Persistence"]
  node_db[("PostgreSQL pool<br/>[db.js]")]
end

node_browser(("Learner or admin"))

node_browser -->|"uses"| node_app
node_app -->|"routes to"| node_learnerui
node_app -->|"routes to"| node_adminui
node_app -->|"checks session"| node_authctx
node_authctx -->|"calls auth API"| node_apiclient
node_learnerui -.->|"requests data"| node_apiclient
node_adminui -->|"requests data"| node_apiclient
node_theme -->|"syncs preferences"| node_apiclient
node_apiclient -->|"HTTP requests"| node_apiapp
node_apiapp -->|"mounts routes"| node_routes
node_routes -->|"registers"| node_authroutes
node_routes -->|"registers"| node_courseroutes
node_authroutes -->|"dispatches"| node_authctrl
node_authctrl -->|"calls"| node_authsvc
node_authroutes -->|"guards requests"| node_authmw
node_courseroutes -->|"guards requests"| node_authmw
node_courseroutes -->|"dispatches"| node_coursectrl
node_coursectrl -->|"calls"| node_coursesvc
node_authsvc -->|"queries"| node_db
node_coursesvc -.->|"accesses"| node_db
node_lessonsvc -.->|"accesses"| node_db
node_assesssvc -.->|"accesses"| node_db
node_adaptivesvc -.->|"accesses"| node_db
node_aisvc -.->|"accesses"| node_db
node_gamesvc -->|"accesses"| node_db
node_adminroutes -->|"dispatches"| node_adminctrl
node_adminctrl -->|"calls"| node_adminsvc
node_adminsvc -->|"queries"| node_db
node_analytics -.->|"accesses"| node_db
node_reports -.->|"accesses"| node_db

click node_app "https://github.com/tharani927/lingualearn/blob/main/frontend/src/App.jsx"
click node_authctx "https://github.com/tharani927/lingualearn/blob/main/frontend/src/contexts/AuthContext.jsx"
click node_apiclient "https://github.com/tharani927/lingualearn/blob/main/frontend/src/services/api.js"
click node_learnerui "https://github.com/tharani927/lingualearn/tree/main/frontend/src/pages/learner"
click node_adminui "https://github.com/tharani927/lingualearn/tree/main/frontend/src/pages/admin"
click node_apiapp "https://github.com/tharani927/lingualearn/blob/main/backend/src/app.js"
click node_routes "https://github.com/tharani927/lingualearn/blob/main/backend/src/routes/index.js"
click node_authroutes "https://github.com/tharani927/lingualearn/blob/main/backend/src/routes/authRoutes.js"
click node_authctrl "https://github.com/tharani927/lingualearn/blob/main/backend/src/controllers/authController.js"
click node_authsvc "https://github.com/tharani927/lingualearn/blob/main/backend/src/services/authService.js"
click node_authmw "https://github.com/tharani927/lingualearn/blob/main/backend/src/middleware/auth.js"
click node_courseroutes "https://github.com/tharani927/lingualearn/blob/main/backend/src/routes/courseRoutes.js"
click node_coursectrl "https://github.com/tharani927/lingualearn/blob/main/backend/src/controllers/courseController.js"
click node_coursesvc "https://github.com/tharani927/lingualearn/blob/main/backend/src/services/courseService.js"
click node_lessonsvc "https://github.com/tharani927/lingualearn/blob/main/backend/src/services/lessonService.js"
click node_assesssvc "https://github.com/tharani927/lingualearn/blob/main/backend/src/services/assessmentService.js"
click node_adaptivesvc "https://github.com/tharani927/lingualearn/blob/main/backend/src/services/adaptiveLearningService.js"
click node_aisvc "https://github.com/tharani927/lingualearn/blob/main/backend/src/services/aiService.js"
click node_gamesvc "https://github.com/tharani927/lingualearn/blob/main/backend/src/services/gamificationService.js"
click node_adminctrl "https://github.com/tharani927/lingualearn/blob/main/backend/src/controllers/adminController.js"
click node_adminsvc "https://github.com/tharani927/lingualearn/blob/main/backend/src/services/adminService.js"
click node_analytics "https://github.com/tharani927/lingualearn/blob/main/backend/src/services/analyticsService.js"
click node_reports "https://github.com/tharani927/lingualearn/blob/main/backend/src/services/reportService.js"
click node_db "https://github.com/tharani927/lingualearn/blob/main/backend/src/config/db.js"
click node_theme "https://github.com/tharani927/lingualearn/blob/main/frontend/src/contexts/ThemeContext.jsx"
click node_adminroutes "https://github.com/tharani927/lingualearn/blob/main/backend/src/routes/adminRoutes.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_app,node_authctx,node_apiclient,node_learnerui,node_adminui,node_theme toneBlue
class node_apiapp,node_routes,node_authroutes,node_authctrl,node_authsvc,node_authmw,node_courseroutes,node_coursectrl,node_adminroutes toneAmber
class node_coursesvc,node_lessonsvc,node_assesssvc,node_adaptivesvc,node_aisvc,node_gamesvc toneMint
class node_adminctrl,node_adminsvc,node_analytics,node_reports toneRose
class node_db,node_browser toneIndigo
```

## Components

### Learner and Admin App

- [Routed SPA](https://github.com/tharani927/lingualearn/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Session context](https://github.com/tharani927/lingualearn/blob/main/frontend/src/contexts/AuthContext.jsx): `frontend/src/contexts/AuthContext.jsx`
- [API client](https://github.com/tharani927/lingualearn/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Learning screens](https://github.com/tharani927/lingualearn/tree/main/frontend/src/pages/learner): `frontend/src/pages/learner`
- [Admin screens](https://github.com/tharani927/lingualearn/tree/main/frontend/src/pages/admin): `frontend/src/pages/admin`
- [Theme preferences](https://github.com/tharani927/lingualearn/blob/main/frontend/src/contexts/ThemeContext.jsx): `frontend/src/contexts/ThemeContext.jsx`

### API and Identity

- [Express API](https://github.com/tharani927/lingualearn/blob/main/backend/src/app.js): `backend/src/app.js`
- [API route registry](https://github.com/tharani927/lingualearn/blob/main/backend/src/routes/index.js): `backend/src/routes/index.js`
- [Authentication routes](https://github.com/tharani927/lingualearn/blob/main/backend/src/routes/authRoutes.js): `backend/src/routes/authRoutes.js`
- [Authentication controller](https://github.com/tharani927/lingualearn/blob/main/backend/src/controllers/authController.js): `backend/src/controllers/authController.js`
- [Identity service](https://github.com/tharani927/lingualearn/blob/main/backend/src/services/authService.js): `backend/src/services/authService.js`
- [JWT authentication](https://github.com/tharani927/lingualearn/blob/main/backend/src/middleware/auth.js): `backend/src/middleware/auth.js`
- [Course routes](https://github.com/tharani927/lingualearn/blob/main/backend/src/routes/courseRoutes.js): `backend/src/routes/courseRoutes.js`
- [Course controller](https://github.com/tharani927/lingualearn/blob/main/backend/src/controllers/courseController.js): `backend/src/controllers/courseController.js`
- [Admin routes](https://github.com/tharani927/lingualearn/blob/main/backend/src/routes/adminRoutes.js): `backend/src/routes/adminRoutes.js`

### Learning Services

- [Course service](https://github.com/tharani927/lingualearn/blob/main/backend/src/services/courseService.js): `backend/src/services/courseService.js`
- [Lesson service](https://github.com/tharani927/lingualearn/blob/main/backend/src/services/lessonService.js): `backend/src/services/lessonService.js`
- [Assessment service](https://github.com/tharani927/lingualearn/blob/main/backend/src/services/assessmentService.js): `backend/src/services/assessmentService.js`
- [Adaptive learning](https://github.com/tharani927/lingualearn/blob/main/backend/src/services/adaptiveLearningService.js): `backend/src/services/adaptiveLearningService.js`
- [AI diagnostics](https://github.com/tharani927/lingualearn/blob/main/backend/src/services/aiService.js): `backend/src/services/aiService.js`
- [Gamification](https://github.com/tharani927/lingualearn/blob/main/backend/src/services/gamificationService.js): `backend/src/services/gamificationService.js`

### Insights and Admin

- [Admin controller](https://github.com/tharani927/lingualearn/blob/main/backend/src/controllers/adminController.js): `backend/src/controllers/adminController.js`
- [Admin service](https://github.com/tharani927/lingualearn/blob/main/backend/src/services/adminService.js): `backend/src/services/adminService.js`
- [Analytics service](https://github.com/tharani927/lingualearn/blob/main/backend/src/services/analyticsService.js): `backend/src/services/analyticsService.js`
- [Reports service](https://github.com/tharani927/lingualearn/blob/main/backend/src/services/reportService.js): `backend/src/services/reportService.js`

### Persistence

- [PostgreSQL pool](https://github.com/tharani927/lingualearn/blob/main/backend/src/config/db.js): `backend/src/config/db.js`

### Other components

- **Learner or admin**

## Connections

- Learner or admin → Routed SPA: uses (evidence: `frontend/src/App.jsx`)
- Routed SPA → Learning screens: routes to (evidence: `frontend/src/App.jsx`)
- Routed SPA → Admin screens: routes to (evidence: `frontend/src/App.jsx`)
- Routed SPA → Session context: checks session (evidence: `frontend/src/App.jsx`)
- Session context → API client: calls auth API (evidence: `frontend/src/contexts/AuthContext.jsx`)
- Learning screens → API client: requests data (evidence: `frontend/src/pages/learner/DashboardPage.jsx`)
- Admin screens → API client: requests data (evidence: `frontend/src/pages/admin/CourseManagementPage.jsx`)
- Theme preferences → API client: syncs preferences (evidence: `frontend/src/contexts/ThemeContext.jsx`)
- API client → Express API: HTTP requests (evidence: `frontend/src/services/api.js`)
- Express API → API route registry: mounts routes (evidence: `backend/src/app.js`)
- API route registry → Authentication routes: registers (evidence: `backend/src/routes/index.js`)
- API route registry → Course routes: registers (evidence: `backend/src/routes/index.js`)
- Authentication routes → Authentication controller: dispatches (evidence: `backend/src/routes/authRoutes.js`)
- Authentication controller → Identity service: calls (evidence: `backend/src/controllers/authController.js`)
- Authentication routes → JWT authentication: guards requests (evidence: `backend/src/routes/authRoutes.js`)
- Course routes → JWT authentication: guards requests (evidence: `backend/src/routes/courseRoutes.js`)
- Course routes → Course controller: dispatches (evidence: `backend/src/routes/courseRoutes.js`)
- Course controller → Course service: calls (evidence: `backend/src/controllers/courseController.js`)
- Identity service → PostgreSQL pool: queries (evidence: `backend/src/services/authService.js`)
- Course service → PostgreSQL pool: accesses
- Lesson service → PostgreSQL pool: accesses
- Assessment service → PostgreSQL pool: accesses
- Adaptive learning → PostgreSQL pool: accesses
- AI diagnostics → PostgreSQL pool: accesses
- Gamification → PostgreSQL pool: accesses (evidence: `backend/src/services/gamificationService.js`)
- Admin routes → Admin controller: dispatches (evidence: `backend/src/routes/adminRoutes.js`)
- Admin controller → Admin service: calls (evidence: `backend/src/controllers/adminController.js`)
- Admin service → PostgreSQL pool: queries (evidence: `backend/src/services/adminService.js`)
- Analytics service → PostgreSQL pool: accesses
- Reports service → PostgreSQL pool: accesses
