# anhtuansss/manmath architecture

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

- Interactive diagram: https://gitdiagram.com/anhtuansss/manmath
- Repository: https://github.com/anhtuansss/manmath

## Overview

ManMath is a Vietnamese high-school mathematics exam and practice application. Its principal workflow is discovering a published, versioned exam, answering it in the V2 client, submitting for server-authoritative grading and timing, then viewing an owner-authorized receipt, review, history, and learning progress. Separate branches cover quick and persistent topic practice, analytics and recommendations, authentication, and the content/question-bank lifecycle. Some subsystem links are based on README capability descriptions; unsampled implementation details are not inferred as direct calls.

Main entry points: [`backend/src/controllers/examController.ts`](https://github.com/anhtuansss/manmath/blob/main/backend/src/controllers/examController.ts) (Exam controller), [`backend/src/services/examContentAttemptService.ts`](https://github.com/anhtuansss/manmath/blob/main/backend/src/services/examContentAttemptService.ts) (Attempt persistence), [`backend/src/app.ts`](https://github.com/anhtuansss/manmath/blob/main/backend/src/app.ts) (Express application), [`frontend/src/components/exam-v2/ExamContentTakingClient.tsx`](https://github.com/anhtuansss/manmath/blob/main/frontend/src/components/exam-v2/ExamContentTakingClient.tsx) (V2 exam client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learner experience"]
  node_exam_catalog["Exam discovery<br/>[ExamListClient.tsx]"]
  node_exam_taking["V2 exam client"]
  node_exam_result["Result and review"]
  node_practice_ui["Topic practice<br/>[PracticeClient.tsx]"]
  node_persistent_ui["Persistent practice UI"]
  node_history_ui["Attempt history<br/>[HistoryClient.tsx]"]
  node_learning_ui["Learning dashboard"]
  node_api_config["API configuration<br/>[api.ts]"]
end

subgraph group_http["HTTP and identity"]
  node_http_app["Express application<br/>[app.ts]"]
  node_exam_routes["Exam routes<br/>[examRoutes.ts]"]
  node_auth_routes["Auth routes<br/>[authRoutes.ts]"]
  node_me_routes["User routes<br/>[meRoutes.ts]"]
  node_exam_controller["Exam controller<br/>[examController.ts]"]
  node_auth_service["Authentication<br/>[authService.ts]"]
end

subgraph group_exam["Exam domain"]
  node_exam_read["Published exam read"]
  node_timing["Timing sessions"]
  node_attempts["Attempt persistence"]
  node_grading["Validation and grading"]
  node_question_grading["Score rules<br/>[examGrading.ts]"]
end

subgraph group_learning["Practice and progress"]
  node_practice_grading["Quick practice grading"]
  node_practice_sessions["Practice sessions"]
  node_question_bank["Question bank"]
  node_analytics["Analytics and overview"]
  node_analytics_service["Learning metrics"]
end

subgraph group_content["Content operations"]
  node_content_lifecycle["Content import and publishing"]
end

node_learner(("Learner"))
node_database[("PostgreSQL")]
node_google(("Google identity"))

node_learner -->|"browses"| node_exam_catalog
node_exam_catalog -->|"requests API"| node_api_config
node_exam_taking -->|"requests API"| node_api_config
node_learner -->|"answers exam"| node_exam_taking
node_exam_taking -->|"views result"| node_exam_result
node_learner -->|"practices topic"| node_practice_ui
node_learner -->|"practices persistently"| node_persistent_ui
node_learner -->|"views history"| node_history_ui
node_learner -->|"views progress"| node_learning_ui
node_api_config -.->|"targets API"| node_http_app
node_http_app -->|"mounts"| node_exam_routes
node_http_app -->|"mounts"| node_auth_routes
node_http_app -->|"mounts"| node_me_routes
node_exam_routes -->|"routes requests"| node_exam_controller
node_auth_routes -->|"handles identity"| node_auth_service
node_me_routes -->|"routes requests"| node_analytics
node_exam_controller -->|"loads exam"| node_exam_read
node_exam_controller -->|"submits attempt"| node_attempts
node_exam_controller -->|"grades practice"| node_practice_grading
node_exam_controller -->|"saves response"| node_practice_sessions
node_attempts -->|"grades submission"| node_grading
node_attempts -->|"checks timing"| node_timing
node_attempts -->|"reads exam content"| node_exam_read
node_grading -->|"scores questions"| node_question_grading
node_practice_grading -->|"reuses grading"| node_grading
node_practice_sessions -->|"selects questions"| node_question_bank
node_analytics -->|"loads metrics"| node_analytics_service
node_exam_read -->|"reads versions"| node_database
node_timing -->|"persists sessions"| node_database
node_attempts -->|"persists attempts"| node_database
node_practice_sessions -->|"persists sessions"| node_database
node_question_bank -.->|"reads bank"| node_database
node_analytics_service -.->|"reads learning data"| node_database
node_content_lifecycle -.->|"publishes content"| node_database
node_google -.->|"provides login"| node_auth_service

click node_exam_catalog "https://github.com/anhtuansss/manmath/blob/main/frontend/src/components/exam/ExamListClient.tsx"
click node_exam_taking "https://github.com/anhtuansss/manmath/blob/main/frontend/src/components/exam-v2/ExamContentTakingClient.tsx"
click node_exam_result "https://github.com/anhtuansss/manmath/blob/main/frontend/src/components/exam-v2/ExamContentResultClient.tsx"
click node_practice_ui "https://github.com/anhtuansss/manmath/blob/main/frontend/src/components/practice/PracticeClient.tsx"
click node_persistent_ui "https://github.com/anhtuansss/manmath/blob/main/frontend/src/components/practice/PersistentPracticeClient.tsx"
click node_history_ui "https://github.com/anhtuansss/manmath/blob/main/frontend/src/components/history/HistoryClient.tsx"
click node_learning_ui "https://github.com/anhtuansss/manmath/blob/main/frontend/src/components/dashboard/LearningDashboardClient.tsx"
click node_api_config "https://github.com/anhtuansss/manmath/blob/main/frontend/src/config/api.ts"
click node_http_app "https://github.com/anhtuansss/manmath/blob/main/backend/src/app.ts"
click node_exam_routes "https://github.com/anhtuansss/manmath/blob/main/backend/src/routes/examRoutes.ts"
click node_auth_routes "https://github.com/anhtuansss/manmath/blob/main/backend/src/routes/authRoutes.ts"
click node_me_routes "https://github.com/anhtuansss/manmath/blob/main/backend/src/routes/meRoutes.ts"
click node_exam_controller "https://github.com/anhtuansss/manmath/blob/main/backend/src/controllers/examController.ts"
click node_auth_service "https://github.com/anhtuansss/manmath/blob/main/backend/src/services/authService.ts"
click node_exam_read "https://github.com/anhtuansss/manmath/blob/main/backend/src/services/examContentReadService.ts"
click node_timing "https://github.com/anhtuansss/manmath/blob/main/backend/src/services/examTimingSessionService.ts"
click node_attempts "https://github.com/anhtuansss/manmath/blob/main/backend/src/services/examContentAttemptService.ts"
click node_grading "https://github.com/anhtuansss/manmath/blob/main/backend/src/services/examContentGradingService.ts"
click node_question_grading "https://github.com/anhtuansss/manmath/blob/main/backend/src/services/examGrading.ts"
click node_practice_grading "https://github.com/anhtuansss/manmath/blob/main/backend/src/services/examContentPracticeService.ts"
click node_practice_sessions "https://github.com/anhtuansss/manmath/blob/main/backend/src/services/practiceSessionService.ts"
click node_question_bank "https://github.com/anhtuansss/manmath/blob/main/backend/src/services/questionBankService.ts"
click node_analytics "https://github.com/anhtuansss/manmath/blob/main/backend/src/controllers/analyticsController.ts"
click node_analytics_service "https://github.com/anhtuansss/manmath/blob/main/backend/src/services/learningOverviewService.ts"
click node_content_lifecycle "https://github.com/anhtuansss/manmath/tree/main/backend/src/scripts"

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_exam_catalog,node_exam_taking,node_exam_result,node_practice_ui,node_persistent_ui,node_history_ui,node_learning_ui,node_api_config toneBlue
class node_http_app,node_exam_routes,node_auth_routes,node_me_routes,node_exam_controller,node_auth_service,node_database toneAmber
class node_exam_read,node_timing,node_attempts,node_grading,node_question_grading toneMint
class node_practice_grading,node_practice_sessions,node_question_bank,node_analytics,node_analytics_service toneRose
class node_content_lifecycle,node_learner,node_google toneIndigo
```

## Components

### Learner experience

- [Exam discovery](https://github.com/anhtuansss/manmath/blob/main/frontend/src/components/exam/ExamListClient.tsx): `frontend/src/components/exam/ExamListClient.tsx`
- [V2 exam client](https://github.com/anhtuansss/manmath/blob/main/frontend/src/components/exam-v2/ExamContentTakingClient.tsx): `frontend/src/components/exam-v2/ExamContentTakingClient.tsx`
- [Result and review](https://github.com/anhtuansss/manmath/blob/main/frontend/src/components/exam-v2/ExamContentResultClient.tsx): `frontend/src/components/exam-v2/ExamContentResultClient.tsx`
- [Topic practice](https://github.com/anhtuansss/manmath/blob/main/frontend/src/components/practice/PracticeClient.tsx): `frontend/src/components/practice/PracticeClient.tsx`
- [Persistent practice UI](https://github.com/anhtuansss/manmath/blob/main/frontend/src/components/practice/PersistentPracticeClient.tsx): `frontend/src/components/practice/PersistentPracticeClient.tsx`
- [Attempt history](https://github.com/anhtuansss/manmath/blob/main/frontend/src/components/history/HistoryClient.tsx): `frontend/src/components/history/HistoryClient.tsx`
- [Learning dashboard](https://github.com/anhtuansss/manmath/blob/main/frontend/src/components/dashboard/LearningDashboardClient.tsx): `frontend/src/components/dashboard/LearningDashboardClient.tsx`
- [API configuration](https://github.com/anhtuansss/manmath/blob/main/frontend/src/config/api.ts): `frontend/src/config/api.ts`

### HTTP and identity

- [Express application](https://github.com/anhtuansss/manmath/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Exam routes](https://github.com/anhtuansss/manmath/blob/main/backend/src/routes/examRoutes.ts): `backend/src/routes/examRoutes.ts`
- [Auth routes](https://github.com/anhtuansss/manmath/blob/main/backend/src/routes/authRoutes.ts): `backend/src/routes/authRoutes.ts`
- [User routes](https://github.com/anhtuansss/manmath/blob/main/backend/src/routes/meRoutes.ts): `backend/src/routes/meRoutes.ts`
- [Exam controller](https://github.com/anhtuansss/manmath/blob/main/backend/src/controllers/examController.ts): `backend/src/controllers/examController.ts`
- [Authentication](https://github.com/anhtuansss/manmath/blob/main/backend/src/services/authService.ts): `backend/src/services/authService.ts`

### Exam domain

- [Published exam read](https://github.com/anhtuansss/manmath/blob/main/backend/src/services/examContentReadService.ts): `backend/src/services/examContentReadService.ts`
- [Timing sessions](https://github.com/anhtuansss/manmath/blob/main/backend/src/services/examTimingSessionService.ts): `backend/src/services/examTimingSessionService.ts`
- [Attempt persistence](https://github.com/anhtuansss/manmath/blob/main/backend/src/services/examContentAttemptService.ts): `backend/src/services/examContentAttemptService.ts`
- [Validation and grading](https://github.com/anhtuansss/manmath/blob/main/backend/src/services/examContentGradingService.ts): `backend/src/services/examContentGradingService.ts`
- [Score rules](https://github.com/anhtuansss/manmath/blob/main/backend/src/services/examGrading.ts): `backend/src/services/examGrading.ts`

### Practice and progress

- [Quick practice grading](https://github.com/anhtuansss/manmath/blob/main/backend/src/services/examContentPracticeService.ts): `backend/src/services/examContentPracticeService.ts`
- [Practice sessions](https://github.com/anhtuansss/manmath/blob/main/backend/src/services/practiceSessionService.ts): `backend/src/services/practiceSessionService.ts`
- [Question bank](https://github.com/anhtuansss/manmath/blob/main/backend/src/services/questionBankService.ts): `backend/src/services/questionBankService.ts`
- [Analytics and overview](https://github.com/anhtuansss/manmath/blob/main/backend/src/controllers/analyticsController.ts): `backend/src/controllers/analyticsController.ts`
- [Learning metrics](https://github.com/anhtuansss/manmath/blob/main/backend/src/services/learningOverviewService.ts): `backend/src/services/learningOverviewService.ts`

### Content operations

- [Content import and publishing](https://github.com/anhtuansss/manmath/tree/main/backend/src/scripts): `backend/src/scripts`

### Other components

- **Learner**
- **PostgreSQL**
- **Google identity**

## Connections

- Learner → Exam discovery: browses (evidence: `README.md`)
- Exam discovery → API configuration: requests API (evidence: `frontend/src/config/api.ts`)
- V2 exam client → API configuration: requests API (evidence: `frontend/src/config/api.ts`)
- Learner → V2 exam client: answers exam (evidence: `README.md`)
- V2 exam client → Result and review: views result (evidence: `README.md`)
- Learner → Topic practice: practices topic (evidence: `README.md`)
- Learner → Persistent practice UI: practices persistently (evidence: `README.md`)
- Learner → Attempt history: views history (evidence: `README.md`)
- Learner → Learning dashboard: views progress (evidence: `README.md`)
- API configuration → Express application: targets API
- Express application → Exam routes: mounts (evidence: `backend/src/app.ts`)
- Express application → Auth routes: mounts (evidence: `backend/src/app.ts`)
- Express application → User routes: mounts (evidence: `backend/src/app.ts`)
- Exam routes → Exam controller: routes requests (evidence: `backend/src/routes/examRoutes.ts`)
- Auth routes → Authentication: handles identity (evidence: `backend/src/routes/authRoutes.ts`)
- User routes → Analytics and overview: routes requests (evidence: `backend/src/routes/meRoutes.ts`)
- Exam controller → Published exam read: loads exam (evidence: `backend/src/controllers/examController.ts`)
- Exam controller → Attempt persistence: submits attempt (evidence: `backend/src/controllers/examController.ts`)
- Exam controller → Quick practice grading: grades practice (evidence: `backend/src/controllers/examController.ts`)
- Exam controller → Practice sessions: saves response (evidence: `backend/src/controllers/examController.ts`)
- Attempt persistence → Validation and grading: grades submission (evidence: `backend/src/services/examContentAttemptService.ts`)
- Attempt persistence → Timing sessions: checks timing (evidence: `backend/src/services/examContentAttemptService.ts`)
- Attempt persistence → Published exam read: reads exam content (evidence: `backend/src/services/examContentAttemptService.ts`)
- Validation and grading → Score rules: scores questions (evidence: `backend/src/services/examContentGradingService.ts`)
- Quick practice grading → Validation and grading: reuses grading (evidence: `backend/src/services/examContentPracticeService.ts`)
- Practice sessions → Question bank: selects questions (evidence: `backend/src/services/practiceSessionService.ts`)
- Analytics and overview → Learning metrics: loads metrics (evidence: `backend/src/controllers/analyticsController.ts`)
- Published exam read → PostgreSQL: reads versions (evidence: `backend/src/services/examContentReadService.ts`)
- Timing sessions → PostgreSQL: persists sessions (evidence: `backend/src/services/examTimingSessionService.ts`)
- Attempt persistence → PostgreSQL: persists attempts (evidence: `backend/src/services/examContentAttemptService.ts`)
- Practice sessions → PostgreSQL: persists sessions (evidence: `backend/src/services/practiceSessionService.ts`)
- Question bank → PostgreSQL: reads bank
- Learning metrics → PostgreSQL: reads learning data
- Content import and publishing → PostgreSQL: publishes content
- Google identity → Authentication: provides login
