# vanyamel/diploma architecture

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

- Interactive diagram: https://gitdiagram.com/vanyamel/diploma
- Repository: https://github.com/vanyamel/diploma

## Overview

LogicMath is a web-based mathematics practice and gamification product. Learners browse categories, generate interactive problems, submit answers, and accumulate progress and XP; accounts support verification and password recovery. The client also exposes favorites, leaderboard, and administration features. The server routes API requests through controllers and domain services to repositories backed by PostgreSQL. The source index identifies several unsampled routes and pages, so their capabilities are represented, but uncertain implementation links are omitted.

Main entry points: [`logicmath/client/src/App.jsx`](https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/App.jsx) (Page Router), [`logicmath/server/controllers/problemsController.js`](https://github.com/vanyamel/diploma/blob/master/logicmath/server/controllers/problemsController.js) (Problem Controller), [`logicmath/client/src/shared/api.js`](https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/shared/api.js) (API Client), [`logicmath/server/controllers/authController.js`](https://github.com/vanyamel/diploma/blob/master/logicmath/server/controllers/authController.js) (Auth Controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learner Client"]
  node_app["Page Router<br/>[App.jsx]"]
  node_catalog["Problem Catalog<br/>[CatalogPage.jsx]"]
  node_solver_ui["Solve Page<br/>[SolvePage.jsx]"]
  node_task_panel["Interactive Tasks"]
  node_task_views["Task Views"]
  node_client_api["API Client<br/>[api.js]"]
  node_client_state["Practice State<br/>[useStore.js]"]
end

subgraph group_identity["Accounts"]
  node_auth_ui["Auth Page<br/>[AuthPage.jsx]"]
  node_auth_state["Auth State<br/>[useAuthStore.js]"]
  node_auth_controller["Auth Controller<br/>[authController.js]"]
  node_auth_service["Auth Service<br/>[authService.js]"]
  node_email["Email Delivery<br/>[emailService.js]"]
  node_users["User Repository<br/>[userRepository.js]"]
end

subgraph group_practice["Problem Practice"]
end

subgraph group_engagement["Progress &amp; Admin"]
  node_progress_ui["Progress Page<br/>[ProgressPage.jsx]"]
  node_favorites_ui["Favorites Page<br/>[FavoritesPage.jsx]"]
  node_leaderboard_ui["Leaderboard Page"]
  node_admin_ui["Admin Page<br/>[AdminPage.jsx]"]
end

subgraph group_server["API &amp; Persistence"]
  node_api_app["API Route Mounts<br/>[app.js]"]
  node_problem_controller["Problem Controller"]
  node_generators["Problem Generators"]
  node_solver["Answer Checker<br/>[ProblemSolver.js]"]
  node_problem_repo["Problem Repository"]
  node_attempt_repo["Attempt Repository"]
  node_db_pool["Database Pool<br/>[pool.js]"]
end

node_learner(("Learner"))
node_postgres[("PostgreSQL")]

node_learner -->|"opens"| node_app
node_app -->|"routes to"| node_catalog
node_app -->|"routes to"| node_solver_ui
node_app -->|"routes to"| node_auth_ui
node_app -->|"routes to"| node_progress_ui
node_app -->|"routes to"| node_favorites_ui
node_app -->|"routes to"| node_leaderboard_ui
node_app -->|"routes to"| node_admin_ui
node_auth_ui -->|"uses"| node_auth_state
node_auth_state -->|"calls"| node_client_api
node_auth_state -->|"updates"| node_client_state
node_task_panel -->|"renders"| node_task_views
node_task_panel -->|"updates"| node_client_state
node_task_panel -->|"calls"| node_client_api
node_client_api -->|"sends API requests"| node_api_app
node_api_app -->|"mounts auth routes"| node_auth_controller
node_api_app -->|"mounts problem routes"| node_problem_controller
node_auth_controller -->|"delegates"| node_auth_service
node_auth_controller -->|"reads user"| node_users
node_auth_controller -->|"reads progress"| node_attempt_repo
node_auth_service -->|"reads and writes"| node_users
node_auth_service -->|"sends email"| node_email
node_problem_controller -->|"creates problems"| node_generators
node_problem_controller -->|"checks answers"| node_solver
node_problem_controller -->|"stores and loads"| node_problem_repo
node_problem_controller -->|"records attempts"| node_attempt_repo
node_problem_controller -->|"reads user data"| node_users
node_users -->|"queries"| node_db_pool
node_attempt_repo -->|"queries"| node_db_pool
node_problem_repo -->|"queries"| node_db_pool
node_db_pool -->|"connects to"| node_postgres
node_favorites_ui -->|"calls"| node_client_api
node_leaderboard_ui -->|"calls"| node_client_api
node_admin_ui -->|"calls"| node_client_api
node_progress_ui -->|"reads progress"| node_client_state

click node_app "https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/App.jsx"
click node_catalog "https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/pages/CatalogPage.jsx"
click node_solver_ui "https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/pages/SolvePage.jsx"
click node_task_panel "https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/features/interactive/InteractiveTaskPanel.jsx"
click node_task_views "https://github.com/vanyamel/diploma/tree/master/logicmath/client/src/features/interactive/tasks"
click node_client_api "https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/shared/api.js"
click node_client_state "https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/shared/useStore.js"
click node_auth_ui "https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/pages/AuthPage.jsx"
click node_auth_state "https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/shared/useAuthStore.js"
click node_auth_controller "https://github.com/vanyamel/diploma/blob/master/logicmath/server/controllers/authController.js"
click node_auth_service "https://github.com/vanyamel/diploma/blob/master/logicmath/server/services/authService.js"
click node_email "https://github.com/vanyamel/diploma/blob/master/logicmath/server/services/emailService.js"
click node_users "https://github.com/vanyamel/diploma/blob/master/logicmath/server/repositories/userRepository.js"
click node_progress_ui "https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/pages/ProgressPage.jsx"
click node_favorites_ui "https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/pages/FavoritesPage.jsx"
click node_leaderboard_ui "https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/pages/LeaderboardPage.jsx"
click node_admin_ui "https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/pages/AdminPage.jsx"
click node_api_app "https://github.com/vanyamel/diploma/blob/master/logicmath/server/app.js"
click node_problem_controller "https://github.com/vanyamel/diploma/blob/master/logicmath/server/controllers/problemsController.js"
click node_generators "https://github.com/vanyamel/diploma/tree/master/logicmath/server/services/generators"
click node_solver "https://github.com/vanyamel/diploma/blob/master/logicmath/server/services/solvers/ProblemSolver.js"
click node_problem_repo "https://github.com/vanyamel/diploma/blob/master/logicmath/server/repositories/problemRepository.js"
click node_attempt_repo "https://github.com/vanyamel/diploma/blob/master/logicmath/server/repositories/attemptRepository.js"
click node_db_pool "https://github.com/vanyamel/diploma/blob/master/logicmath/server/db/pool.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_catalog,node_solver_ui,node_task_panel,node_task_views,node_client_api,node_client_state toneBlue
class node_auth_ui,node_auth_state,node_auth_controller,node_auth_service,node_email,node_users,node_postgres toneAmber
class node_progress_ui,node_favorites_ui,node_leaderboard_ui,node_admin_ui toneRose
class node_api_app,node_problem_controller,node_generators,node_solver,node_problem_repo,node_attempt_repo,node_db_pool,node_learner toneIndigo
```

## Components

### Learner Client

- [Page Router](https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/App.jsx): `logicmath/client/src/App.jsx`
- [Problem Catalog](https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/pages/CatalogPage.jsx): `logicmath/client/src/pages/CatalogPage.jsx`
- [Solve Page](https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/pages/SolvePage.jsx): `logicmath/client/src/pages/SolvePage.jsx`
- [Interactive Tasks](https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/features/interactive/InteractiveTaskPanel.jsx): `logicmath/client/src/features/interactive/InteractiveTaskPanel.jsx`
- [Task Views](https://github.com/vanyamel/diploma/tree/master/logicmath/client/src/features/interactive/tasks): `logicmath/client/src/features/interactive/tasks`
- [API Client](https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/shared/api.js): `logicmath/client/src/shared/api.js`
- [Practice State](https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/shared/useStore.js): `logicmath/client/src/shared/useStore.js`

### Accounts

- [Auth Page](https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/pages/AuthPage.jsx): `logicmath/client/src/pages/AuthPage.jsx`
- [Auth State](https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/shared/useAuthStore.js): `logicmath/client/src/shared/useAuthStore.js`
- [Auth Controller](https://github.com/vanyamel/diploma/blob/master/logicmath/server/controllers/authController.js): `logicmath/server/controllers/authController.js`
- [Auth Service](https://github.com/vanyamel/diploma/blob/master/logicmath/server/services/authService.js): `logicmath/server/services/authService.js`
- [Email Delivery](https://github.com/vanyamel/diploma/blob/master/logicmath/server/services/emailService.js): `logicmath/server/services/emailService.js`
- [User Repository](https://github.com/vanyamel/diploma/blob/master/logicmath/server/repositories/userRepository.js): `logicmath/server/repositories/userRepository.js`

### Progress & Admin

- [Progress Page](https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/pages/ProgressPage.jsx): `logicmath/client/src/pages/ProgressPage.jsx`
- [Favorites Page](https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/pages/FavoritesPage.jsx): `logicmath/client/src/pages/FavoritesPage.jsx`
- [Leaderboard Page](https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/pages/LeaderboardPage.jsx): `logicmath/client/src/pages/LeaderboardPage.jsx`
- [Admin Page](https://github.com/vanyamel/diploma/blob/master/logicmath/client/src/pages/AdminPage.jsx): `logicmath/client/src/pages/AdminPage.jsx`

### API & Persistence

- [API Route Mounts](https://github.com/vanyamel/diploma/blob/master/logicmath/server/app.js): `logicmath/server/app.js`
- [Problem Controller](https://github.com/vanyamel/diploma/blob/master/logicmath/server/controllers/problemsController.js): `logicmath/server/controllers/problemsController.js`
- [Problem Generators](https://github.com/vanyamel/diploma/tree/master/logicmath/server/services/generators): `logicmath/server/services/generators`
- [Answer Checker](https://github.com/vanyamel/diploma/blob/master/logicmath/server/services/solvers/ProblemSolver.js): `logicmath/server/services/solvers/ProblemSolver.js`
- [Problem Repository](https://github.com/vanyamel/diploma/blob/master/logicmath/server/repositories/problemRepository.js): `logicmath/server/repositories/problemRepository.js`
- [Attempt Repository](https://github.com/vanyamel/diploma/blob/master/logicmath/server/repositories/attemptRepository.js): `logicmath/server/repositories/attemptRepository.js`
- [Database Pool](https://github.com/vanyamel/diploma/blob/master/logicmath/server/db/pool.js): `logicmath/server/db/pool.js`

### Other components

- **Learner**
- **PostgreSQL**

## Connections

- Learner → Page Router: opens (evidence: `logicmath/client/src/App.jsx`)
- Page Router → Problem Catalog: routes to (evidence: `logicmath/client/src/App.jsx`)
- Page Router → Solve Page: routes to (evidence: `logicmath/client/src/App.jsx`)
- Page Router → Auth Page: routes to (evidence: `logicmath/client/src/App.jsx`)
- Page Router → Progress Page: routes to (evidence: `logicmath/client/src/App.jsx`)
- Page Router → Favorites Page: routes to (evidence: `logicmath/client/src/App.jsx`)
- Page Router → Leaderboard Page: routes to (evidence: `logicmath/client/src/App.jsx`)
- Page Router → Admin Page: routes to (evidence: `logicmath/client/src/App.jsx`)
- Auth Page → Auth State: uses (evidence: `logicmath/client/src/pages/AuthPage.jsx`)
- Auth State → API Client: calls (evidence: `logicmath/client/src/shared/useAuthStore.js`)
- Auth State → Practice State: updates (evidence: `logicmath/client/src/shared/useAuthStore.js`)
- Interactive Tasks → Task Views: renders (evidence: `logicmath/client/src/features/interactive/InteractiveTaskPanel.jsx`)
- Interactive Tasks → Practice State: updates (evidence: `logicmath/client/src/features/interactive/InteractiveTaskPanel.jsx`)
- Interactive Tasks → API Client: calls (evidence: `logicmath/client/src/features/interactive/InteractiveTaskPanel.jsx`)
- API Client → API Route Mounts: sends API requests (evidence: `logicmath/client/src/shared/api.js`)
- API Route Mounts → Auth Controller: mounts auth routes (evidence: `logicmath/server/app.js`)
- API Route Mounts → Problem Controller: mounts problem routes (evidence: `logicmath/server/app.js`)
- Auth Controller → Auth Service: delegates (evidence: `logicmath/server/controllers/authController.js`)
- Auth Controller → User Repository: reads user (evidence: `logicmath/server/controllers/authController.js`)
- Auth Controller → Attempt Repository: reads progress (evidence: `logicmath/server/controllers/authController.js`)
- Auth Service → User Repository: reads and writes (evidence: `logicmath/server/services/authService.js`)
- Auth Service → Email Delivery: sends email (evidence: `logicmath/server/services/authService.js`)
- Problem Controller → Problem Generators: creates problems (evidence: `logicmath/server/controllers/problemsController.js`)
- Problem Controller → Answer Checker: checks answers (evidence: `logicmath/server/controllers/problemsController.js`)
- Problem Controller → Problem Repository: stores and loads (evidence: `logicmath/server/controllers/problemsController.js`)
- Problem Controller → Attempt Repository: records attempts (evidence: `logicmath/server/controllers/problemsController.js`)
- Problem Controller → User Repository: reads user data (evidence: `logicmath/server/controllers/problemsController.js`)
- User Repository → Database Pool: queries (evidence: `logicmath/server/repositories/userRepository.js`)
- Attempt Repository → Database Pool: queries (evidence: `logicmath/server/repositories/attemptRepository.js`)
- Problem Repository → Database Pool: queries (evidence: `logicmath/server/repositories/problemRepository.js`)
- Database Pool → PostgreSQL: connects to (evidence: `logicmath/server/db/pool.js`)
- Favorites Page → API Client: calls (evidence: `logicmath/client/src/pages/FavoritesPage.jsx`)
- Leaderboard Page → API Client: calls (evidence: `logicmath/client/src/pages/LeaderboardPage.jsx`)
- Admin Page → API Client: calls (evidence: `logicmath/client/src/pages/AdminPage.jsx`)
- Progress Page → Practice State: reads progress (evidence: `logicmath/client/src/pages/ProgressPage.jsx`)
