# rakesh-bhandari/aptric architecture

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

- Interactive diagram: https://gitdiagram.com/rakesh-bhandari/aptric
- Repository: https://github.com/rakesh-bhandari/aptric

## Overview

Aptric is an aptitude-learning platform whose main learner journey runs from authentication through daily challenges or topic practice to recorded progress and rankings. The repository also includes an administrator workflow for question review and user/question management, plus AI question generation. The README describes a React-to-Express-to-MySQL architecture, while sampled frontend session code uses Supabase; the graph preserves both without assuming how they are integrated. Some feature links rely on README documentation because their implementation files were not sampled.

Main entry points: [`backend/src/server.js`](https://github.com/rakesh-bhandari/aptric/blob/main/backend/src/server.js) (Express API), [`frontend/src/App.jsx`](https://github.com/rakesh-bhandari/aptric/blob/main/frontend/src/App.jsx) (React application), [`backend/src/routes/auth.js`](https://github.com/rakesh-bhandari/aptric/blob/main/backend/src/routes/auth.js) (Authentication routes), [`frontend/src/pages/Practice/Practice.jsx`](https://github.com/rakesh-bhandari/aptric/blob/main/frontend/src/pages/Practice/Practice.jsx) (Daily and topic practice)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learner experience"]
  node_web["React application<br/>[App.jsx]"]
  node_session["Session and profile<br/>[SessionContext.jsx]"]
  node_practice["Daily and topic practice<br/>[Practice.jsx]"]
  node_gameclient["Game API client<br/>[game.js]"]
  node_progress["Progress dashboard<br/>[Profile.jsx]"]
  node_leaderboard["Leaderboard<br/>[Leaderboard.jsx]"]
end

subgraph group_platform["Platform services"]
  node_express["Express API<br/>[server.js]"]
  node_authapi["Authentication routes<br/>[auth.js]"]
  node_gameapi["Game routes<br/>[game.js]"]
  node_questionbank["Question bank<br/>[questionBank.js]"]
  node_mysql[("MySQL database<br/>[db.js]")]
  node_authmiddleware["JWT authorization<br/>[auth.js]"]
end

subgraph group_operations["Admin operations"]
  node_adminui["Admin console<br/>[ReviewQueue.jsx]"]
  node_adminapi["Admin routes<br/>[admin.js]"]
  node_feedback["Feedback and reports<br/>[feedback.js]"]
end

subgraph group_generation["Question generation"]
  node_generator["Generation pipeline<br/>[pipeline.ts]"]
  node_generationentry["Generation endpoint<br/>[index.ts]"]
  node_llm["Structured LLM client<br/>[llm.ts]"]
  node_generationstore["Generation storage<br/>[store.ts]"]
end

node_learner(("Learner"))
node_admin(("Administrator"))
node_ai{{"OpenRouter AI"}}
node_supabase[("Supabase auth/data")]
node_email{{"Email service"}}
node_google{{"Google OAuth"}}

node_learner -->|"uses"| node_web
node_web -->|"provides session"| node_session
node_session -->|"reads auth and profile"| node_supabase
node_learner -->|"solves questions"| node_practice
node_web -->|"routes to"| node_practice
node_practice -->|"requests game data"| node_gameclient
node_gameclient -.->|"calls API"| node_express
node_express -->|"routes requests"| node_gameapi
node_gameapi -->|"gets daily questions"| node_questionbank
node_gameapi -->|"reads and writes"| node_mysql
node_questionbank -->|"stores question data"| node_mysql
node_practice -->|"reviews progress"| node_progress
node_progress -->|"compares ranking"| node_leaderboard
node_admin -->|"manages platform"| node_adminui
node_web -->|"routes to"| node_adminui
node_adminui -.->|"manages questions"| node_adminapi
node_express -->|"routes requests"| node_adminapi
node_adminapi -->|"requires authorization"| node_authmiddleware
node_adminapi -->|"manages records"| node_mysql
node_admin -.->|"starts generation"| node_generator
node_generationentry -->|"runs pipeline"| node_generator
node_generator -->|"requests generations"| node_llm
node_llm -->|"sends prompts"| node_ai
node_generator -->|"reads and inserts"| node_generationstore
node_authapi -->|"reads and writes"| node_mysql
node_express -->|"routes requests"| node_authapi
node_authapi -->|"supports sign-in"| node_google
node_authapi -->|"sends verification mail"| node_email
node_express -->|"routes requests"| node_feedback

click node_web "https://github.com/rakesh-bhandari/aptric/blob/main/frontend/src/App.jsx"
click node_session "https://github.com/rakesh-bhandari/aptric/blob/main/frontend/src/context/SessionContext.jsx"
click node_practice "https://github.com/rakesh-bhandari/aptric/blob/main/frontend/src/pages/Practice/Practice.jsx"
click node_gameclient "https://github.com/rakesh-bhandari/aptric/blob/main/frontend/src/lib/game.js"
click node_progress "https://github.com/rakesh-bhandari/aptric/blob/main/frontend/src/pages/Profile/Profile.jsx"
click node_leaderboard "https://github.com/rakesh-bhandari/aptric/blob/main/frontend/src/pages/Leaderboard/Leaderboard.jsx"
click node_express "https://github.com/rakesh-bhandari/aptric/blob/main/backend/src/server.js"
click node_authapi "https://github.com/rakesh-bhandari/aptric/blob/main/backend/src/routes/auth.js"
click node_gameapi "https://github.com/rakesh-bhandari/aptric/blob/main/backend/src/routes/game.js"
click node_questionbank "https://github.com/rakesh-bhandari/aptric/blob/main/backend/src/services/questionBank.js"
click node_mysql "https://github.com/rakesh-bhandari/aptric/blob/main/backend/src/config/db.js"
click node_authmiddleware "https://github.com/rakesh-bhandari/aptric/blob/main/backend/src/middleware/auth.js"
click node_adminui "https://github.com/rakesh-bhandari/aptric/blob/main/frontend/src/pages/Admin/ReviewQueue.jsx"
click node_adminapi "https://github.com/rakesh-bhandari/aptric/blob/main/backend/src/routes/admin.js"
click node_feedback "https://github.com/rakesh-bhandari/aptric/blob/main/backend/src/routes/feedback.js"
click node_generator "https://github.com/rakesh-bhandari/aptric/blob/main/supabase/functions/generate-questions/pipeline.ts"
click node_generationentry "https://github.com/rakesh-bhandari/aptric/blob/main/supabase/functions/generate-questions/index.ts"
click node_llm "https://github.com/rakesh-bhandari/aptric/blob/main/supabase/functions/generate-questions/llm.ts"
click node_generationstore "https://github.com/rakesh-bhandari/aptric/blob/main/supabase/functions/generate-questions/store.ts"

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,node_session,node_practice,node_gameclient,node_progress,node_leaderboard toneBlue
class node_express,node_authapi,node_gameapi,node_questionbank,node_mysql,node_authmiddleware,node_supabase toneAmber
class node_adminui,node_adminapi,node_feedback,node_ai toneMint
class node_generator,node_generationentry,node_llm,node_generationstore toneRose
class node_learner,node_admin,node_email,node_google toneIndigo
```

## Components

### Learner experience

- [React application](https://github.com/rakesh-bhandari/aptric/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Session and profile](https://github.com/rakesh-bhandari/aptric/blob/main/frontend/src/context/SessionContext.jsx): `frontend/src/context/SessionContext.jsx`
- [Daily and topic practice](https://github.com/rakesh-bhandari/aptric/blob/main/frontend/src/pages/Practice/Practice.jsx): `frontend/src/pages/Practice/Practice.jsx`
- [Game API client](https://github.com/rakesh-bhandari/aptric/blob/main/frontend/src/lib/game.js): `frontend/src/lib/game.js`
- [Progress dashboard](https://github.com/rakesh-bhandari/aptric/blob/main/frontend/src/pages/Profile/Profile.jsx): `frontend/src/pages/Profile/Profile.jsx`
- [Leaderboard](https://github.com/rakesh-bhandari/aptric/blob/main/frontend/src/pages/Leaderboard/Leaderboard.jsx): `frontend/src/pages/Leaderboard/Leaderboard.jsx`

### Platform services

- [Express API](https://github.com/rakesh-bhandari/aptric/blob/main/backend/src/server.js): `backend/src/server.js`
- [Authentication routes](https://github.com/rakesh-bhandari/aptric/blob/main/backend/src/routes/auth.js): `backend/src/routes/auth.js`
- [Game routes](https://github.com/rakesh-bhandari/aptric/blob/main/backend/src/routes/game.js): `backend/src/routes/game.js`
- [Question bank](https://github.com/rakesh-bhandari/aptric/blob/main/backend/src/services/questionBank.js): `backend/src/services/questionBank.js`
- [MySQL database](https://github.com/rakesh-bhandari/aptric/blob/main/backend/src/config/db.js): `backend/src/config/db.js`
- [JWT authorization](https://github.com/rakesh-bhandari/aptric/blob/main/backend/src/middleware/auth.js): `backend/src/middleware/auth.js`

### Admin operations

- [Admin console](https://github.com/rakesh-bhandari/aptric/blob/main/frontend/src/pages/Admin/ReviewQueue.jsx): `frontend/src/pages/Admin/ReviewQueue.jsx`
- [Admin routes](https://github.com/rakesh-bhandari/aptric/blob/main/backend/src/routes/admin.js): `backend/src/routes/admin.js`
- [Feedback and reports](https://github.com/rakesh-bhandari/aptric/blob/main/backend/src/routes/feedback.js): `backend/src/routes/feedback.js`

### Question generation

- [Generation pipeline](https://github.com/rakesh-bhandari/aptric/blob/main/supabase/functions/generate-questions/pipeline.ts): `supabase/functions/generate-questions/pipeline.ts`
- [Generation endpoint](https://github.com/rakesh-bhandari/aptric/blob/main/supabase/functions/generate-questions/index.ts): `supabase/functions/generate-questions/index.ts`
- [Structured LLM client](https://github.com/rakesh-bhandari/aptric/blob/main/supabase/functions/generate-questions/llm.ts): `supabase/functions/generate-questions/llm.ts`
- [Generation storage](https://github.com/rakesh-bhandari/aptric/blob/main/supabase/functions/generate-questions/store.ts): `supabase/functions/generate-questions/store.ts`

### Other components

- **Learner**
- **Administrator**
- **OpenRouter AI**
- **Supabase auth/data**
- **Email service**
- **Google OAuth**

## Connections

- Learner → React application: uses (evidence: `README.md`)
- React application → Session and profile: provides session (evidence: `frontend/src/App.jsx`)
- Session and profile → Supabase auth/data: reads auth and profile (evidence: `frontend/src/context/SessionContext.jsx`)
- Learner → Daily and topic practice: solves questions (evidence: `README.md`)
- React application → Daily and topic practice: routes to (evidence: `frontend/src/App.jsx`)
- Daily and topic practice → Game API client: requests game data (evidence: `frontend/src/pages/Practice/Practice.jsx`)
- Game API client → Express API: calls API
- Express API → Game routes: routes requests (evidence: `backend/src/server.js`)
- Game routes → Question bank: gets daily questions (evidence: `backend/src/routes/game.js`)
- Game routes → MySQL database: reads and writes (evidence: `backend/src/routes/game.js`)
- Question bank → MySQL database: stores question data (evidence: `backend/src/services/questionBank.js`)
- Daily and topic practice → Progress dashboard: reviews progress (evidence: `README.md`)
- Progress dashboard → Leaderboard: compares ranking (evidence: `README.md`)
- Administrator → Admin console: manages platform (evidence: `README.md`)
- React application → Admin console: routes to (evidence: `frontend/src/App.jsx`)
- Admin console → Admin routes: manages questions
- Express API → Admin routes: routes requests (evidence: `backend/src/server.js`)
- Admin routes → JWT authorization: requires authorization (evidence: `backend/src/routes/admin.js`)
- Admin routes → MySQL database: manages records (evidence: `backend/src/routes/admin.js`)
- Administrator → Generation pipeline: starts generation
- Generation endpoint → Generation pipeline: runs pipeline (evidence: `supabase/functions/generate-questions/index.ts`)
- Generation pipeline → Structured LLM client: requests generations (evidence: `supabase/functions/generate-questions/pipeline.ts`)
- Structured LLM client → OpenRouter AI: sends prompts (evidence: `supabase/functions/generate-questions/llm.ts`)
- Generation pipeline → Generation storage: reads and inserts (evidence: `supabase/functions/generate-questions/pipeline.ts`)
- Authentication routes → MySQL database: reads and writes (evidence: `backend/src/routes/auth.js`)
- Express API → Authentication routes: routes requests (evidence: `backend/src/server.js`)
- Authentication routes → Google OAuth: supports sign-in (evidence: `README.md`)
- Authentication routes → Email service: sends verification mail (evidence: `README.md`)
- Express API → Feedback and reports: routes requests (evidence: `backend/src/server.js`)
