# veasnachan1/hanmemo architecture

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

- Interactive diagram: https://gitdiagram.com/veasnachan1/hanmemo
- Repository: https://github.com/veasnachan1/hanmemo

## Overview

HanMemo is a Mandarin vocabulary-learning app built around lessons, quizzes, flashcard study, and spaced-repetition review. Learners authenticate, select a level, progress through lessons, and rate due vocabulary cards; the API tracks lesson completion and schedules reviews. Separate branches support learner progress/profile views and administrator management of users and learning content. The graph reflects sampled server flows and documented routes; several client and backend subsystems are represented by tree paths and capability names, without asserting unsampled internal wiring.

Main entry points: [`server/models/index.js`](https://github.com/veasnachan1/hanmemo/blob/main/server/models/index.js) (Learning models), [`Client/src/App.jsx`](https://github.com/veasnachan1/hanmemo/blob/main/Client/src/App.jsx) (App routing), [`server/server.js`](https://github.com/veasnachan1/hanmemo/blob/main/server/server.js) (Express API), [`Client/src/api/axios.js`](https://github.com/veasnachan1/hanmemo/blob/main/Client/src/api/axios.js) (HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learner application"]
  node_app["App routing<br/>[App.jsx]"]
  node_lessons_ui["Lessons and study<br/>[LessonsPage.jsx]"]
  node_quiz_ui["Lesson quiz<br/>[QuizPage.jsx]"]
  node_review_ui["Review session"]
  node_progress_ui["Progress views<br/>[ProgressPage.jsx]"]
  node_admin_ui["Admin dashboard<br/>[AdminDashboard.jsx]"]
  node_lesson_api["Lesson API client<br/>[lessonApi.js]"]
  node_review_api["Review API client<br/>[reviewApi.js]"]
  node_progress_api["Progress API client<br/>[progressApi.js]"]
  node_admin_api["Admin API client<br/>[adminApi.js]"]
  node_http["HTTP client<br/>[axios.js]"]
end

subgraph group_api["API routing"]
  node_server["Express API<br/>[server.js]"]
  node_lesson_routes["Lesson routes<br/>[lessonRoutes.js]"]
  node_review_routes["Review routes<br/>[reviewRoutes.js]"]
  node_auth_routes["Auth routes<br/>[authRoutes.js]"]
  node_admin_routes["Admin routes<br/>[adminRoutes.js]"]
  node_progress_routes["Progress routes<br/>[progressRoutes.js]"]
end

subgraph group_learning["Learning services"]
  node_lesson_controller["Lesson workflow"]
  node_review_controller["Review workflow"]
  node_quiz_service["Quiz generation<br/>[quizService.js]"]
  node_srs_service["SM-2 scheduling<br/>[srsService.js]"]
  node_progress_controller["Progress tracking"]
  node_admin_controller["Content administration<br/>[adminController.js]"]
end

subgraph group_identity["Identity and access"]
  node_auth_controller["Authentication<br/>[authController.js]"]
  node_auth_service["Credential and tokens<br/>[authService.js]"]
  node_auth_middleware["JWT authentication<br/>[authMiddleware.js]"]
end

subgraph group_storage["Persistent data"]
  node_db[("MySQL database<br/>[db.js]")]
  node_models["Learning models<br/>[index.js]"]
  node_user_model["User records<br/>[User.js]"]
  node_lesson_model["Lesson and vocabulary<br/>[Lesson.js]"]
  node_review_model["Review sessions<br/>[ReviewSession.js]"]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_app
node_app -->|"routes to"| node_lessons_ui
node_app -->|"routes to"| node_quiz_ui
node_app -->|"routes to"| node_review_ui
node_app -->|"routes to"| node_progress_ui
node_app -->|"routes to"| node_admin_ui
node_lessons_ui -->|"requests lessons"| node_lesson_api
node_quiz_ui -->|"requests quiz"| node_lesson_api
node_review_ui -->|"loads and rates"| node_review_api
node_progress_ui -->|"requests progress"| node_progress_api
node_admin_ui -->|"manages content"| node_admin_api
node_lesson_api -->|"sends requests"| node_http
node_review_api -->|"sends requests"| node_http
node_progress_api -->|"sends requests"| node_http
node_admin_api -->|"sends requests"| node_http
node_http -->|"HTTP requests"| node_server
node_server -->|"dispatches"| node_lesson_routes
node_server -->|"dispatches"| node_review_routes
node_server -->|"dispatches"| node_auth_routes
node_server -->|"dispatches"| node_admin_routes
node_server -->|"dispatches"| node_progress_routes
node_lesson_routes -->|"requires identity"| node_auth_middleware
node_review_routes -->|"requires identity"| node_auth_middleware
node_lesson_routes -->|"dispatches"| node_lesson_controller
node_review_routes -->|"dispatches"| node_review_controller
node_admin_routes -->|"dispatches"| node_admin_controller
node_progress_routes -->|"dispatches"| node_progress_controller
node_auth_routes -->|"dispatches"| node_auth_controller
node_lesson_controller -->|"generates quiz"| node_quiz_service
node_review_controller -->|"calculates schedule"| node_srs_service
node_lesson_controller -->|"reads and writes"| node_models
node_review_controller -->|"reads and writes"| node_models
node_progress_controller -->|"tracks progress"| node_models
node_admin_controller -->|"manages records"| node_models
node_auth_controller -->|"hashes and signs"| node_auth_service
node_auth_controller -->|"reads and writes"| node_models
node_auth_middleware -->|"verifies token"| node_auth_service
node_models -->|"persists records"| node_db
node_models -->|"defines"| node_user_model
node_models -->|"defines"| node_lesson_model
node_models -->|"defines"| node_review_model
node_lesson_controller -->|"creates due reviews"| node_review_model
node_review_controller -->|"loads and updates"| node_review_model

click node_app "https://github.com/veasnachan1/hanmemo/blob/main/Client/src/App.jsx"
click node_lessons_ui "https://github.com/veasnachan1/hanmemo/blob/main/Client/src/pages/LessonsPage.jsx"
click node_quiz_ui "https://github.com/veasnachan1/hanmemo/blob/main/Client/src/pages/QuizPage.jsx"
click node_review_ui "https://github.com/veasnachan1/hanmemo/blob/main/Client/src/pages/ReviewSessionPage.jsx"
click node_progress_ui "https://github.com/veasnachan1/hanmemo/blob/main/Client/src/pages/ProgressPage.jsx"
click node_admin_ui "https://github.com/veasnachan1/hanmemo/blob/main/Client/src/pages/AdminDashboard.jsx"
click node_lesson_api "https://github.com/veasnachan1/hanmemo/blob/main/Client/src/api/lessonApi.js"
click node_review_api "https://github.com/veasnachan1/hanmemo/blob/main/Client/src/api/reviewApi.js"
click node_progress_api "https://github.com/veasnachan1/hanmemo/blob/main/Client/src/api/progressApi.js"
click node_admin_api "https://github.com/veasnachan1/hanmemo/blob/main/Client/src/api/adminApi.js"
click node_http "https://github.com/veasnachan1/hanmemo/blob/main/Client/src/api/axios.js"
click node_server "https://github.com/veasnachan1/hanmemo/blob/main/server/server.js"
click node_lesson_routes "https://github.com/veasnachan1/hanmemo/blob/main/server/routes/lessonRoutes.js"
click node_review_routes "https://github.com/veasnachan1/hanmemo/blob/main/server/routes/reviewRoutes.js"
click node_auth_routes "https://github.com/veasnachan1/hanmemo/blob/main/server/routes/authRoutes.js"
click node_admin_routes "https://github.com/veasnachan1/hanmemo/blob/main/server/routes/adminRoutes.js"
click node_progress_routes "https://github.com/veasnachan1/hanmemo/blob/main/server/routes/progressRoutes.js"
click node_lesson_controller "https://github.com/veasnachan1/hanmemo/blob/main/server/controllers/lessonController.js"
click node_review_controller "https://github.com/veasnachan1/hanmemo/blob/main/server/controllers/reviewController.js"
click node_quiz_service "https://github.com/veasnachan1/hanmemo/blob/main/server/services/quizService.js"
click node_srs_service "https://github.com/veasnachan1/hanmemo/blob/main/server/services/srsService.js"
click node_progress_controller "https://github.com/veasnachan1/hanmemo/blob/main/server/controllers/progressController.js"
click node_admin_controller "https://github.com/veasnachan1/hanmemo/blob/main/server/controllers/adminController.js"
click node_auth_controller "https://github.com/veasnachan1/hanmemo/blob/main/server/controllers/authController.js"
click node_auth_service "https://github.com/veasnachan1/hanmemo/blob/main/server/service/authService.js"
click node_auth_middleware "https://github.com/veasnachan1/hanmemo/blob/main/server/middlewares/authMiddleware.js"
click node_db "https://github.com/veasnachan1/hanmemo/blob/main/server/config/db.js"
click node_models "https://github.com/veasnachan1/hanmemo/blob/main/server/models/index.js"
click node_user_model "https://github.com/veasnachan1/hanmemo/blob/main/server/models/User.js"
click node_lesson_model "https://github.com/veasnachan1/hanmemo/blob/main/server/models/Lesson.js"
click node_review_model "https://github.com/veasnachan1/hanmemo/blob/main/server/models/ReviewSession.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_lessons_ui,node_quiz_ui,node_review_ui,node_progress_ui,node_admin_ui,node_lesson_api,node_review_api,node_progress_api,node_admin_api,node_http toneBlue
class node_server,node_lesson_routes,node_review_routes,node_auth_routes,node_admin_routes,node_progress_routes toneAmber
class node_lesson_controller,node_review_controller,node_quiz_service,node_srs_service,node_progress_controller,node_admin_controller toneMint
class node_auth_controller,node_auth_service,node_auth_middleware toneRose
class node_db,node_models,node_user_model,node_lesson_model,node_review_model,node_learner toneIndigo
```

## Components

### Learner application

- [App routing](https://github.com/veasnachan1/hanmemo/blob/main/Client/src/App.jsx): `Client/src/App.jsx`
- [Lessons and study](https://github.com/veasnachan1/hanmemo/blob/main/Client/src/pages/LessonsPage.jsx): `Client/src/pages/LessonsPage.jsx`
- [Lesson quiz](https://github.com/veasnachan1/hanmemo/blob/main/Client/src/pages/QuizPage.jsx): `Client/src/pages/QuizPage.jsx`
- [Review session](https://github.com/veasnachan1/hanmemo/blob/main/Client/src/pages/ReviewSessionPage.jsx): `Client/src/pages/ReviewSessionPage.jsx`
- [Progress views](https://github.com/veasnachan1/hanmemo/blob/main/Client/src/pages/ProgressPage.jsx): `Client/src/pages/ProgressPage.jsx`
- [Admin dashboard](https://github.com/veasnachan1/hanmemo/blob/main/Client/src/pages/AdminDashboard.jsx): `Client/src/pages/AdminDashboard.jsx`
- [Lesson API client](https://github.com/veasnachan1/hanmemo/blob/main/Client/src/api/lessonApi.js): `Client/src/api/lessonApi.js`
- [Review API client](https://github.com/veasnachan1/hanmemo/blob/main/Client/src/api/reviewApi.js): `Client/src/api/reviewApi.js`
- [Progress API client](https://github.com/veasnachan1/hanmemo/blob/main/Client/src/api/progressApi.js): `Client/src/api/progressApi.js`
- [Admin API client](https://github.com/veasnachan1/hanmemo/blob/main/Client/src/api/adminApi.js): `Client/src/api/adminApi.js`
- [HTTP client](https://github.com/veasnachan1/hanmemo/blob/main/Client/src/api/axios.js): `Client/src/api/axios.js`

### API routing

- [Express API](https://github.com/veasnachan1/hanmemo/blob/main/server/server.js): `server/server.js`
- [Lesson routes](https://github.com/veasnachan1/hanmemo/blob/main/server/routes/lessonRoutes.js): `server/routes/lessonRoutes.js`
- [Review routes](https://github.com/veasnachan1/hanmemo/blob/main/server/routes/reviewRoutes.js): `server/routes/reviewRoutes.js`
- [Auth routes](https://github.com/veasnachan1/hanmemo/blob/main/server/routes/authRoutes.js): `server/routes/authRoutes.js`
- [Admin routes](https://github.com/veasnachan1/hanmemo/blob/main/server/routes/adminRoutes.js): `server/routes/adminRoutes.js`
- [Progress routes](https://github.com/veasnachan1/hanmemo/blob/main/server/routes/progressRoutes.js): `server/routes/progressRoutes.js`

### Learning services

- [Lesson workflow](https://github.com/veasnachan1/hanmemo/blob/main/server/controllers/lessonController.js): `server/controllers/lessonController.js`
- [Review workflow](https://github.com/veasnachan1/hanmemo/blob/main/server/controllers/reviewController.js): `server/controllers/reviewController.js`
- [Quiz generation](https://github.com/veasnachan1/hanmemo/blob/main/server/services/quizService.js): `server/services/quizService.js`
- [SM-2 scheduling](https://github.com/veasnachan1/hanmemo/blob/main/server/services/srsService.js): `server/services/srsService.js`
- [Progress tracking](https://github.com/veasnachan1/hanmemo/blob/main/server/controllers/progressController.js): `server/controllers/progressController.js`
- [Content administration](https://github.com/veasnachan1/hanmemo/blob/main/server/controllers/adminController.js): `server/controllers/adminController.js`

### Identity and access

- [Authentication](https://github.com/veasnachan1/hanmemo/blob/main/server/controllers/authController.js): `server/controllers/authController.js`
- [Credential and tokens](https://github.com/veasnachan1/hanmemo/blob/main/server/service/authService.js): `server/service/authService.js`
- [JWT authentication](https://github.com/veasnachan1/hanmemo/blob/main/server/middlewares/authMiddleware.js): `server/middlewares/authMiddleware.js`

### Persistent data

- [MySQL database](https://github.com/veasnachan1/hanmemo/blob/main/server/config/db.js): `server/config/db.js`
- [Learning models](https://github.com/veasnachan1/hanmemo/blob/main/server/models/index.js): `server/models/index.js`
- [User records](https://github.com/veasnachan1/hanmemo/blob/main/server/models/User.js): `server/models/User.js`
- [Lesson and vocabulary](https://github.com/veasnachan1/hanmemo/blob/main/server/models/Lesson.js): `server/models/Lesson.js`
- [Review sessions](https://github.com/veasnachan1/hanmemo/blob/main/server/models/ReviewSession.js): `server/models/ReviewSession.js`

### Other components

- **Learner**

## Connections

- Learner → App routing: uses
- App routing → Lessons and study: routes to
- App routing → Lesson quiz: routes to
- App routing → Review session: routes to
- App routing → Progress views: routes to
- App routing → Admin dashboard: routes to
- Lessons and study → Lesson API client: requests lessons
- Lesson quiz → Lesson API client: requests quiz
- Review session → Review API client: loads and rates
- Progress views → Progress API client: requests progress
- Admin dashboard → Admin API client: manages content
- Lesson API client → HTTP client: sends requests
- Review API client → HTTP client: sends requests
- Progress API client → HTTP client: sends requests
- Admin API client → HTTP client: sends requests
- HTTP client → Express API: HTTP requests
- Express API → Lesson routes: dispatches
- Express API → Review routes: dispatches
- Express API → Auth routes: dispatches
- Express API → Admin routes: dispatches
- Express API → Progress routes: dispatches
- Lesson routes → JWT authentication: requires identity
- Review routes → JWT authentication: requires identity
- Lesson routes → Lesson workflow: dispatches
- Review routes → Review workflow: dispatches
- Admin routes → Content administration: dispatches
- Progress routes → Progress tracking: dispatches
- Auth routes → Authentication: dispatches
- Lesson workflow → Quiz generation: generates quiz
- Review workflow → SM-2 scheduling: calculates schedule
- Lesson workflow → Learning models: reads and writes
- Review workflow → Learning models: reads and writes
- Progress tracking → Learning models: tracks progress
- Content administration → Learning models: manages records
- Authentication → Credential and tokens: hashes and signs
- Authentication → Learning models: reads and writes
- JWT authentication → Credential and tokens: verifies token
- Learning models → MySQL database: persists records
- Learning models → User records: defines
- Learning models → Lesson and vocabulary: defines
- Learning models → Review sessions: defines
- Lesson workflow → Review sessions: creates due reviews
- Review workflow → Review sessions: loads and updates