# phuoctan221/capstone_1 architecture

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

- Interactive diagram: https://gitdiagram.com/phuoctan221/capstone_1
- Repository: https://github.com/phuoctan221/capstone_1

## Overview

SmartVocab AI is an adaptive English vocabulary learning platform. Learners authenticate, complete onboarding, study domain- and level-based lessons, answer exercises, review flashcards on an FSRS schedule, and track mastery and progress. Separate branches cover AI vocabulary suggestions, speaking, chat, and administrator management. The graph reflects documented capabilities and relationships visible in the supplied excerpts or source index; several route and integration details are unsampled, so their links are omitted rather than inferred.

Main entry points: [`backend/app/main.py`](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/main.py) (API application), [`backend/app/services/session_service.py`](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/session_service.py) (Learning sessions), [`frontend/src/services/api.js`](https://github.com/phuoctan221/capstone_1/blob/main/frontend/src/services/api.js) (API client), [`frontend/src/App.jsx`](https://github.com/phuoctan221/capstone_1/blob/main/frontend/src/App.jsx) (Web app and routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learner_ui["Learner experience"]
  node_web_app["Web app and routes<br/>[App.jsx]"]
  node_auth_ui["Auth client<br/>[authService.js]"]
  node_learning_pages["Learning pages"]
  node_vocabulary_ui["Vocabulary UI<br/>[VocabularyPage.jsx]"]
  node_admin_ui["Admin UI"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_learning["Learning services"]
  node_app_entry["API application<br/>[main.py]"]
  node_learning_routes["Learning routes<br/>[learning_router.py]"]
  node_lesson_routes["Lesson routes<br/>[lesson_router.py]"]
  node_vocab_routes["Vocabulary routes"]
  node_lesson_catalog["Lesson catalogue<br/>[lesson_service.py]"]
  node_exercise_bank["Exercise bank"]
  node_sessions["Learning sessions<br/>[session_service.py]"]
  node_learning_state["FSRS learning state"]
  node_progress["Mastery and progress"]
end

subgraph group_identity_admin["Identity and admin"]
  node_auth_routes["Auth routes<br/>[auth_router.py]"]
  node_auth_service["JWT and RBAC<br/>[auth_service.py]"]
  node_admin_routes["Admin operations<br/>[admin_router.py]"]
end

subgraph group_platform_data["Platform data and AI"]
  node_domains["Domain definitions<br/>[domains.py]"]
  node_ai_service["AI vocabulary suggestions<br/>[ai_service.py]"]
  node_chat_service["Chat service<br/>[chat_service.py]"]
  node_speaking_service["Speaking service"]
  node_mongo[("MongoDB<br/>[mongodb.py]")]
end

node_learner(("Learner"))
node_gemini["Google Gemini"]

node_learner -->|"uses"| node_web_app
node_web_app -->|"routes to"| node_learning_pages
node_web_app -->|"refreshes session"| node_auth_ui
node_auth_ui -->|"sends auth requests"| node_api_client
node_learning_pages -.->|"requests data"| node_api_client
node_vocabulary_ui -.->|"requests vocabulary"| node_api_client
node_admin_ui -.->|"requests admin data"| node_api_client
node_app_entry -->|"registers"| node_auth_routes
node_app_entry -->|"registers"| node_learning_routes
node_app_entry -->|"registers"| node_lesson_routes
node_app_entry -->|"registers"| node_vocab_routes
node_app_entry -->|"registers"| node_admin_routes
node_auth_routes -->|"validates identity"| node_auth_service
node_learning_routes -->|"dispatches session work"| node_sessions
node_lesson_routes -->|"loads lessons"| node_lesson_catalog
node_lesson_routes -->|"requests suggestions"| node_ai_service
node_vocab_routes -->|"requests suggestions"| node_ai_service
node_sessions -->|"loads lesson words"| node_lesson_catalog
node_sessions -->|"selects exercises"| node_exercise_bank
node_sessions -->|"initializes state"| node_learning_state
node_admin_routes -->|"checks admin role"| node_auth_service
node_admin_routes -->|"regenerates exercises"| node_exercise_bank
node_lesson_catalog -->|"reads catalogue"| node_mongo
node_learning_state -->|"uses mastery updates"| node_progress
node_ai_service -.->|"generates suggestions"| node_gemini
node_chat_service -.->|"uses persistence"| node_mongo
node_speaking_service -.->|"uses persistence"| node_mongo

click node_web_app "https://github.com/phuoctan221/capstone_1/blob/main/frontend/src/App.jsx"
click node_auth_ui "https://github.com/phuoctan221/capstone_1/blob/main/frontend/src/services/authService.js"
click node_learning_pages "https://github.com/phuoctan221/capstone_1/tree/main/frontend/src/pages"
click node_vocabulary_ui "https://github.com/phuoctan221/capstone_1/blob/main/frontend/src/pages/VocabularyPage.jsx"
click node_admin_ui "https://github.com/phuoctan221/capstone_1/blob/main/frontend/src/pages/AdminDashboardPage.jsx"
click node_api_client "https://github.com/phuoctan221/capstone_1/blob/main/frontend/src/services/api.js"
click node_app_entry "https://github.com/phuoctan221/capstone_1/blob/main/backend/app/main.py"
click node_learning_routes "https://github.com/phuoctan221/capstone_1/blob/main/backend/app/routers/learning_router.py"
click node_lesson_routes "https://github.com/phuoctan221/capstone_1/blob/main/backend/app/routers/lesson_router.py"
click node_vocab_routes "https://github.com/phuoctan221/capstone_1/blob/main/backend/app/routers/vocabulary_router.py"
click node_lesson_catalog "https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/lesson_service.py"
click node_exercise_bank "https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/exercise_service.py"
click node_sessions "https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/session_service.py"
click node_learning_state "https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/learning_service.py"
click node_progress "https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/progress_service.py"
click node_auth_routes "https://github.com/phuoctan221/capstone_1/blob/main/backend/app/routers/auth_router.py"
click node_auth_service "https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/auth_service.py"
click node_admin_routes "https://github.com/phuoctan221/capstone_1/blob/main/backend/app/routers/admin_router.py"
click node_domains "https://github.com/phuoctan221/capstone_1/blob/main/backend/app/core/domains.py"
click node_ai_service "https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/ai_service.py"
click node_chat_service "https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/chat_service.py"
click node_speaking_service "https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/speaking_service.py"
click node_mongo "https://github.com/phuoctan221/capstone_1/blob/main/backend/app/db/mongodb.py"

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_web_app,node_auth_ui,node_learning_pages,node_vocabulary_ui,node_admin_ui,node_api_client toneBlue
class node_app_entry,node_learning_routes,node_lesson_routes,node_vocab_routes,node_lesson_catalog,node_exercise_bank,node_sessions,node_learning_state,node_progress toneAmber
class node_auth_routes,node_auth_service,node_admin_routes toneMint
class node_domains,node_ai_service,node_chat_service,node_speaking_service,node_mongo toneRose
class node_learner,node_gemini toneIndigo
```

## Components

### Learner experience

- [Web app and routes](https://github.com/phuoctan221/capstone_1/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Auth client](https://github.com/phuoctan221/capstone_1/blob/main/frontend/src/services/authService.js): `frontend/src/services/authService.js`
- [Learning pages](https://github.com/phuoctan221/capstone_1/tree/main/frontend/src/pages): `frontend/src/pages`
- [Vocabulary UI](https://github.com/phuoctan221/capstone_1/blob/main/frontend/src/pages/VocabularyPage.jsx): `frontend/src/pages/VocabularyPage.jsx`
- [Admin UI](https://github.com/phuoctan221/capstone_1/blob/main/frontend/src/pages/AdminDashboardPage.jsx): `frontend/src/pages/AdminDashboardPage.jsx`
- [API client](https://github.com/phuoctan221/capstone_1/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### Learning services

- [API application](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/main.py): `backend/app/main.py`
- [Learning routes](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/routers/learning_router.py): `backend/app/routers/learning_router.py`
- [Lesson routes](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/routers/lesson_router.py): `backend/app/routers/lesson_router.py`
- [Vocabulary routes](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/routers/vocabulary_router.py): `backend/app/routers/vocabulary_router.py`
- [Lesson catalogue](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/lesson_service.py): `backend/app/services/lesson_service.py`
- [Exercise bank](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/exercise_service.py): `backend/app/services/exercise_service.py`
- [Learning sessions](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/session_service.py): `backend/app/services/session_service.py`
- [FSRS learning state](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/learning_service.py): `backend/app/services/learning_service.py`
- [Mastery and progress](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/progress_service.py): `backend/app/services/progress_service.py`

### Identity and admin

- [Auth routes](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/routers/auth_router.py): `backend/app/routers/auth_router.py`
- [JWT and RBAC](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Admin operations](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/routers/admin_router.py): `backend/app/routers/admin_router.py`

### Platform data and AI

- [Domain definitions](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/core/domains.py): `backend/app/core/domains.py`
- [AI vocabulary suggestions](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [Chat service](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/chat_service.py): `backend/app/services/chat_service.py`
- [Speaking service](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/services/speaking_service.py): `backend/app/services/speaking_service.py`
- [MongoDB](https://github.com/phuoctan221/capstone_1/blob/main/backend/app/db/mongodb.py): `backend/app/db/mongodb.py`

### Other components

- **Learner**
- **Google Gemini**

## Connections

- Learner → Web app and routes: uses
- Web app and routes → Learning pages: routes to (evidence: `frontend/src/App.jsx`)
- Web app and routes → Auth client: refreshes session (evidence: `frontend/src/App.jsx`)
- Auth client → API client: sends auth requests (evidence: `frontend/src/services/authService.js`)
- Learning pages → API client: requests data
- Vocabulary UI → API client: requests vocabulary
- Admin UI → API client: requests admin data
- API application → Auth routes: registers (evidence: `backend/app/main.py`)
- API application → Learning routes: registers (evidence: `backend/app/main.py`)
- API application → Lesson routes: registers (evidence: `backend/app/main.py`)
- API application → Vocabulary routes: registers (evidence: `backend/app/main.py`)
- API application → Admin operations: registers (evidence: `backend/app/main.py`)
- Auth routes → JWT and RBAC: validates identity (evidence: `backend/app/routers/auth_router.py`)
- Learning routes → Learning sessions: dispatches session work (evidence: `backend/app/routers/learning_router.py`)
- Lesson routes → Lesson catalogue: loads lessons (evidence: `backend/app/routers/lesson_router.py`)
- Lesson routes → AI vocabulary suggestions: requests suggestions (evidence: `backend/app/routers/lesson_router.py`)
- Vocabulary routes → AI vocabulary suggestions: requests suggestions (evidence: `backend/app/routers/vocabulary_router.py`)
- Learning sessions → Lesson catalogue: loads lesson words (evidence: `backend/app/services/session_service.py`)
- Learning sessions → Exercise bank: selects exercises (evidence: `backend/app/services/session_service.py`)
- Learning sessions → FSRS learning state: initializes state (evidence: `backend/app/services/session_service.py`)
- Admin operations → JWT and RBAC: checks admin role (evidence: `backend/app/routers/admin_router.py`)
- Admin operations → Exercise bank: regenerates exercises (evidence: `backend/app/routers/admin_router.py`)
- Lesson catalogue → MongoDB: reads catalogue (evidence: `backend/app/services/lesson_service.py`)
- FSRS learning state → Mastery and progress: uses mastery updates (evidence: `backend/app/services/learning_service.py`)
- AI vocabulary suggestions → Google Gemini: generates suggestions
- Chat service → MongoDB: uses persistence
- Speaking service → MongoDB: uses persistence
