# k2aitutor/frontend architecture

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

- Interactive diagram: https://gitdiagram.com/k2aitutor/frontend
- Repository: https://github.com/k2aitutor/frontend

## Overview

This monorepo provides web and mobile clients for an AI-assisted learning product, with student practice and exams alongside role-specific dashboards for teachers, parents, contributors, and administrators. A typical student path is to choose a subject or topic, work through practice, and review progress or exam results; billing, notifications, and content operations are additional capabilities. The shared package supplies API constants, hooks, and types. The README is empty, and many routes were not sampled, so links are limited to relationships visible in excerpts or the source index.

Main entry points: [`packages/shared/src/hooks/practice.ts`](https://github.com/k2aitutor/frontend/blob/main/packages/shared/src/hooks/practice.ts) (Practice hooks), [`apps/web/src/app/(dashboard)`](https://github.com/k2aitutor/frontend/tree/main/apps/web/src/app/(dashboard)) (Role dashboards), [`apps/mobile/src/lib/apiClient.ts`](https://github.com/k2aitutor/frontend/blob/main/apps/mobile/src/lib/apiClient.ts) (Mobile API client), [`apps/mobile/app/practice/session/[sessionId].tsx`](https://github.com/k2aitutor/frontend/blob/main/apps/mobile/app/practice/session/%5BsessionId%5D.tsx) (Mobile practice session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile app"]
  node_mobile_home["Mobile dashboard<br/>[index.tsx]"]
  node_mobile_subscribe["Mobile subscription<br/>[subscription.tsx]"]
  node_dashboard_cards["Dashboard cards<br/>[DashboardCards.tsx]"]
  node_math_view["Math rendering<br/>[MathView.tsx]"]
  node_mobile_api["Mobile API client<br/>[apiClient.ts]"]
  node_secure_store["Secure token storage<br/>[secureStore.ts]"]
  node_observability["Request observability<br/>[observability.ts]"]
  node_iap["In-app purchases<br/>[iap.ts]"]
end

subgraph group_web["Web app"]
  node_web_api["Web API client<br/>[apiClient.ts]"]
end

subgraph group_shared["Shared client layer"]
  node_shared_practice["Practice hooks<br/>[practice.ts]"]
  node_fetcher_context["Fetcher context<br/>[FetcherContext.ts]"]
  node_api_constants["API route constants<br/>[api.ts]"]
  node_exam_types["Exam types<br/>[exam.ts]"]
  node_practice_types["Practice types<br/>[practice.ts]"]
end

subgraph group_learning["Learning workflows"]
  node_mobile_practice["Mobile practice session<br/>[&#91;sessionId&#93;.tsx]"]
  node_mobile_review["Mobile exam review<br/>[review.tsx]"]
  node_web_student["Web student practice"]
  node_web_exam["Web exam session"]
end

subgraph group_operations["Role operations"]
  node_web_roles["Role dashboards"]
  node_web_admin["Admin content and billing"]
  node_web_contributor["Contributor workflows"]
  node_web_parent_teacher["Parent and teacher views"]
end

node_student(("Student"))

node_student -->|"opens"| node_mobile_home
node_mobile_home -->|"renders"| node_dashboard_cards
node_student -.->|"practices"| node_mobile_practice
node_mobile_practice -->|"uses hooks"| node_shared_practice
node_mobile_practice -->|"renders math"| node_math_view
node_mobile_review -->|"loads review"| node_mobile_api
node_mobile_subscribe -->|"uses purchases"| node_iap
node_mobile_api -->|"reads tokens"| node_secure_store
node_mobile_api -->|"reports requests"| node_observability
node_shared_practice -->|"uses routes"| node_api_constants
node_shared_practice -->|"uses types"| node_exam_types
node_shared_practice -->|"uses types"| node_practice_types
node_fetcher_context -.->|"provides fetcher"| node_shared_practice
node_student -.->|"practices"| node_web_student
node_student -.->|"takes exams"| node_web_exam
node_student -.->|"uses dashboards"| node_web_roles
node_web_roles -.->|"routes by role"| node_web_admin
node_web_roles -.->|"routes by role"| node_web_contributor
node_web_roles -.->|"routes by role"| node_web_parent_teacher
node_web_student -.->|"loads learning data"| node_web_api

click node_mobile_home "https://github.com/k2aitutor/frontend/blob/main/apps/mobile/app/(tabs)/index.tsx"
click node_mobile_practice "https://github.com/k2aitutor/frontend/blob/main/apps/mobile/app/practice/session/%5BsessionId%5D.tsx"
click node_mobile_review "https://github.com/k2aitutor/frontend/blob/main/apps/mobile/app/exam/%5BattemptId%5D/review.tsx"
click node_mobile_subscribe "https://github.com/k2aitutor/frontend/blob/main/apps/mobile/app/subscription.tsx"
click node_dashboard_cards "https://github.com/k2aitutor/frontend/blob/main/apps/mobile/src/components/DashboardCards.tsx"
click node_math_view "https://github.com/k2aitutor/frontend/blob/main/apps/mobile/src/components/math/MathView.tsx"
click node_mobile_api "https://github.com/k2aitutor/frontend/blob/main/apps/mobile/src/lib/apiClient.ts"
click node_secure_store "https://github.com/k2aitutor/frontend/blob/main/apps/mobile/src/lib/secureStore.ts"
click node_observability "https://github.com/k2aitutor/frontend/blob/main/apps/mobile/src/lib/observability.ts"
click node_iap "https://github.com/k2aitutor/frontend/blob/main/apps/mobile/src/lib/iap.ts"
click node_web_student "https://github.com/k2aitutor/frontend/tree/main/apps/web/src/app/(dashboard)/student/practice"
click node_web_exam "https://github.com/k2aitutor/frontend/blob/main/apps/web/src/components/exam/ExamSessionClient.tsx"
click node_web_roles "https://github.com/k2aitutor/frontend/tree/main/apps/web/src/app/(dashboard)"
click node_web_admin "https://github.com/k2aitutor/frontend/tree/main/apps/web/src/app/(dashboard)/admin"
click node_web_contributor "https://github.com/k2aitutor/frontend/tree/main/apps/web/src/app/(dashboard)/contributor"
click node_web_parent_teacher "https://github.com/k2aitutor/frontend/tree/main/apps/web/src/app/(dashboard)/parent"
click node_web_api "https://github.com/k2aitutor/frontend/blob/main/apps/web/src/lib/apiClient.ts"
click node_shared_practice "https://github.com/k2aitutor/frontend/blob/main/packages/shared/src/hooks/practice.ts"
click node_fetcher_context "https://github.com/k2aitutor/frontend/blob/main/packages/shared/src/hooks/FetcherContext.ts"
click node_api_constants "https://github.com/k2aitutor/frontend/blob/main/packages/shared/src/constants/api.ts"
click node_exam_types "https://github.com/k2aitutor/frontend/blob/main/packages/shared/src/types/exam.ts"
click node_practice_types "https://github.com/k2aitutor/frontend/blob/main/packages/shared/src/types/practice.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_mobile_home,node_mobile_subscribe,node_dashboard_cards,node_math_view,node_mobile_api,node_secure_store,node_observability,node_iap toneBlue
class node_web_api toneAmber
class node_shared_practice,node_fetcher_context,node_api_constants,node_exam_types,node_practice_types toneMint
class node_mobile_practice,node_mobile_review,node_web_student,node_web_exam toneRose
class node_web_roles,node_web_admin,node_web_contributor,node_web_parent_teacher,node_student toneIndigo
```

## Components

### Mobile app

- [Mobile dashboard](https://github.com/k2aitutor/frontend/blob/main/apps/mobile/app/(tabs)/index.tsx): `apps/mobile/app/(tabs)/index.tsx`
- [Mobile subscription](https://github.com/k2aitutor/frontend/blob/main/apps/mobile/app/subscription.tsx): `apps/mobile/app/subscription.tsx`
- [Dashboard cards](https://github.com/k2aitutor/frontend/blob/main/apps/mobile/src/components/DashboardCards.tsx): `apps/mobile/src/components/DashboardCards.tsx`
- [Math rendering](https://github.com/k2aitutor/frontend/blob/main/apps/mobile/src/components/math/MathView.tsx): `apps/mobile/src/components/math/MathView.tsx`
- [Mobile API client](https://github.com/k2aitutor/frontend/blob/main/apps/mobile/src/lib/apiClient.ts): `apps/mobile/src/lib/apiClient.ts`
- [Secure token storage](https://github.com/k2aitutor/frontend/blob/main/apps/mobile/src/lib/secureStore.ts): `apps/mobile/src/lib/secureStore.ts`
- [Request observability](https://github.com/k2aitutor/frontend/blob/main/apps/mobile/src/lib/observability.ts): `apps/mobile/src/lib/observability.ts`
- [In-app purchases](https://github.com/k2aitutor/frontend/blob/main/apps/mobile/src/lib/iap.ts): `apps/mobile/src/lib/iap.ts`

### Web app

- [Web API client](https://github.com/k2aitutor/frontend/blob/main/apps/web/src/lib/apiClient.ts): `apps/web/src/lib/apiClient.ts`

### Shared client layer

- [Practice hooks](https://github.com/k2aitutor/frontend/blob/main/packages/shared/src/hooks/practice.ts): `packages/shared/src/hooks/practice.ts`
- [Fetcher context](https://github.com/k2aitutor/frontend/blob/main/packages/shared/src/hooks/FetcherContext.ts): `packages/shared/src/hooks/FetcherContext.ts`
- [API route constants](https://github.com/k2aitutor/frontend/blob/main/packages/shared/src/constants/api.ts): `packages/shared/src/constants/api.ts`
- [Exam types](https://github.com/k2aitutor/frontend/blob/main/packages/shared/src/types/exam.ts): `packages/shared/src/types/exam.ts`
- [Practice types](https://github.com/k2aitutor/frontend/blob/main/packages/shared/src/types/practice.ts): `packages/shared/src/types/practice.ts`

### Learning workflows

- [Mobile practice session](https://github.com/k2aitutor/frontend/blob/main/apps/mobile/app/practice/session/%5BsessionId%5D.tsx): `apps/mobile/app/practice/session/[sessionId].tsx`
- [Mobile exam review](https://github.com/k2aitutor/frontend/blob/main/apps/mobile/app/exam/%5BattemptId%5D/review.tsx): `apps/mobile/app/exam/[attemptId]/review.tsx`
- [Web student practice](https://github.com/k2aitutor/frontend/tree/main/apps/web/src/app/(dashboard)/student/practice): `apps/web/src/app/(dashboard)/student/practice`
- [Web exam session](https://github.com/k2aitutor/frontend/blob/main/apps/web/src/components/exam/ExamSessionClient.tsx): `apps/web/src/components/exam/ExamSessionClient.tsx`

### Role operations

- [Role dashboards](https://github.com/k2aitutor/frontend/tree/main/apps/web/src/app/(dashboard)): `apps/web/src/app/(dashboard)`
- [Admin content and billing](https://github.com/k2aitutor/frontend/tree/main/apps/web/src/app/(dashboard)/admin): `apps/web/src/app/(dashboard)/admin`
- [Contributor workflows](https://github.com/k2aitutor/frontend/tree/main/apps/web/src/app/(dashboard)/contributor): `apps/web/src/app/(dashboard)/contributor`
- [Parent and teacher views](https://github.com/k2aitutor/frontend/tree/main/apps/web/src/app/(dashboard)/parent): `apps/web/src/app/(dashboard)/parent`

### Other components

- **Student**

## Connections

- Student → Mobile dashboard: opens (evidence: `apps/mobile/app/(tabs)/index.tsx`)
- Mobile dashboard → Dashboard cards: renders (evidence: `apps/mobile/app/(tabs)/index.tsx`)
- Student → Mobile practice session: practices
- Mobile practice session → Practice hooks: uses hooks (evidence: `apps/mobile/app/practice/session/[sessionId].tsx`)
- Mobile practice session → Math rendering: renders math (evidence: `apps/mobile/app/practice/session/[sessionId].tsx`)
- Mobile exam review → Mobile API client: loads review (evidence: `apps/mobile/app/exam/[attemptId]/review.tsx`)
- Mobile subscription → In-app purchases: uses purchases (evidence: `apps/mobile/app/subscription.tsx`)
- Mobile API client → Secure token storage: reads tokens (evidence: `apps/mobile/src/lib/apiClient.ts`)
- Mobile API client → Request observability: reports requests (evidence: `apps/mobile/src/lib/apiClient.ts`)
- Practice hooks → API route constants: uses routes (evidence: `packages/shared/src/hooks/practice.ts`)
- Practice hooks → Exam types: uses types (evidence: `packages/shared/src/hooks/practice.ts`)
- Practice hooks → Practice types: uses types (evidence: `packages/shared/src/hooks/practice.ts`)
- Fetcher context → Practice hooks: provides fetcher (evidence: `packages/shared/src/hooks/practice.ts`)
- Student → Web student practice: practices
- Student → Web exam session: takes exams
- Student → Role dashboards: uses dashboards
- Role dashboards → Admin content and billing: routes by role
- Role dashboards → Contributor workflows: routes by role
- Role dashboards → Parent and teacher views: routes by role
- Web student practice → Web API client: loads learning data