# nv-duymanh/mathvisionkid architecture

> Architecture diagram of the GitHub repository nv-duymanh/mathvisionkid, 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/nv-duymanh/mathvisionkid
- Repository: https://github.com/nv-duymanh/mathvisionkid

## Overview

MathVision Kids combines student handwriting recognition and arithmetic checking with teacher review, tutoring, and administrative tools. The main student flow prepares a captured image, submits it through the business API, and uses the AI runtime for OCR and analysis before returning a result for confirmation or review. The README documents OCR routing; sampled source shows the AI service’s routes and backend submission dependencies. Other product capabilities are represented at subsystem level where their implementation was not sampled.

Main entry points: [`backend/business-api/src/main/java/com/mathvisionkids/api`](https://github.com/nv-duymanh/mathvisionkid/tree/main/backend/business-api/src/main/java/com/mathvisionkids/api) (Business API), [`apps/student-mobile/src/app/recognition`](https://github.com/nv-duymanh/mathvisionkid/tree/main/apps/student-mobile/src/app/recognition) (Capture and results), [`backend/business-api/src/main/java/com/mathvisionkids/api/submission/SubmissionService.java`](https://github.com/nv-duymanh/mathvisionkid/blob/main/backend/business-api/src/main/java/com/mathvisionkids/api/submission/SubmissionService.java) (Submission handling), [`ai/runtime/app/main.py`](https://github.com/nv-duymanh/mathvisionkid/blob/main/ai/runtime/app/main.py) (AI service routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_student["Student learning"]
  node_mobile_flow["Capture and results"]
  node_image_prep["Image preparation<br/>[imagePipeline.ts]"]
  node_recognition_api["Recognition client"]
  node_tutor_client["Tutor client<br/>[TutorService.ts]"]
end

subgraph group_backend["Business backend"]
  node_business_api["Business API"]
  node_submission["Submission handling"]
  node_storage[("Image storage")]
  node_ai_gateway["AI analysis gateway"]
  node_user_admin["Accounts and classes<br/>[AdminService.java]"]
  node_audit[("Audit records<br/>[AuditEvent.java]")]
end

subgraph group_ai["AI runtime"]
  node_ai_service["AI service routes<br/>[main.py]"]
  node_ocr_api["OCR endpoint<br/>[ocr.py]"]
  node_row_pipeline["Row localization"]
  node_model_engine["Model recognition<br/>[model_engine.py]"]
  node_tutor_runtime["Tutoring runtime<br/>[tutor.py]"]
end

subgraph group_educator["Educator tools"]
  node_teacher_portal["Teacher review<br/>[App.tsx]"]
end

subgraph group_admin["Administration"]
  node_admin_portal["Admin console<br/>[App.tsx]"]
  node_recognition_analytics["Recognition analytics"]
end

node_student_actor(("Student"))

node_student_actor -->|"uses"| node_mobile_flow
node_mobile_flow -->|"prepares image"| node_image_prep
node_mobile_flow -.->|"submits recognition"| node_recognition_api
node_recognition_api -.->|"calls API"| node_business_api
node_business_api -.->|"routes submissions"| node_submission
node_submission -->|"stores images"| node_storage
node_submission -->|"requests analysis"| node_ai_gateway
node_ai_gateway -.->|"dispatches analysis"| node_ai_service
node_ai_service -->|"mounts OCR route"| node_ocr_api
node_business_api -->|"uses OCR routes"| node_ocr_api
node_ai_service -->|"checks readiness"| node_model_engine
node_model_engine -.->|"recognizes rows"| node_row_pipeline
node_mobile_flow -.->|"requests tutoring"| node_tutor_client
node_tutor_client -.->|"calls tutor API"| node_tutor_runtime
node_teacher_portal -.->|"uses business services"| node_business_api
node_admin_portal -.->|"uses business services"| node_business_api
node_admin_portal -->|"routes analytics"| node_recognition_analytics
node_business_api -.->|"administers accounts"| node_user_admin
node_user_admin -->|"records audit events"| node_audit

click node_mobile_flow "https://github.com/nv-duymanh/mathvisionkid/tree/main/apps/student-mobile/src/app/recognition"
click node_image_prep "https://github.com/nv-duymanh/mathvisionkid/blob/main/apps/student-mobile/src/features/recognition/image/imagePipeline.ts"
click node_recognition_api "https://github.com/nv-duymanh/mathvisionkid/blob/main/apps/student-mobile/src/features/recognition/api/RecognitionService.ts"
click node_tutor_client "https://github.com/nv-duymanh/mathvisionkid/blob/main/apps/student-mobile/src/features/tutoring/api/TutorService.ts"
click node_business_api "https://github.com/nv-duymanh/mathvisionkid/tree/main/backend/business-api/src/main/java/com/mathvisionkids/api"
click node_submission "https://github.com/nv-duymanh/mathvisionkid/blob/main/backend/business-api/src/main/java/com/mathvisionkids/api/submission/SubmissionService.java"
click node_storage "https://github.com/nv-duymanh/mathvisionkid/blob/main/backend/business-api/src/main/java/com/mathvisionkids/api/storage/ObjectStorageService.java"
click node_ai_gateway "https://github.com/nv-duymanh/mathvisionkid/blob/main/backend/business-api/src/main/java/com/mathvisionkids/api/analysis/AiAnalysisGateway.java"
click node_user_admin "https://github.com/nv-duymanh/mathvisionkid/blob/main/backend/business-api/src/main/java/com/mathvisionkids/api/admin/AdminService.java"
click node_ai_service "https://github.com/nv-duymanh/mathvisionkid/blob/main/ai/runtime/app/main.py"
click node_ocr_api "https://github.com/nv-duymanh/mathvisionkid/blob/main/ai/runtime/app/api/ocr.py"
click node_row_pipeline "https://github.com/nv-duymanh/mathvisionkid/blob/main/ai/runtime/app/api/generalized_pipeline.py"
click node_model_engine "https://github.com/nv-duymanh/mathvisionkid/blob/main/ai/runtime/app/recognition/model_engine.py"
click node_tutor_runtime "https://github.com/nv-duymanh/mathvisionkid/blob/main/ai/runtime/app/api/tutor.py"
click node_teacher_portal "https://github.com/nv-duymanh/mathvisionkid/blob/main/apps/teacher-web/src/App.tsx"
click node_admin_portal "https://github.com/nv-duymanh/mathvisionkid/blob/main/apps/admin-web/src/App.tsx"
click node_recognition_analytics "https://github.com/nv-duymanh/mathvisionkid/blob/main/apps/admin-web/src/pages/RecognitionAnalyticsPage.tsx"
click node_audit "https://github.com/nv-duymanh/mathvisionkid/blob/main/backend/business-api/src/main/java/com/mathvisionkids/api/audit/AuditEvent.java"

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_flow,node_image_prep,node_recognition_api,node_tutor_client toneBlue
class node_business_api,node_submission,node_storage,node_ai_gateway,node_user_admin,node_audit toneAmber
class node_ai_service,node_ocr_api,node_row_pipeline,node_model_engine,node_tutor_runtime toneMint
class node_teacher_portal toneRose
class node_admin_portal,node_recognition_analytics,node_student_actor toneIndigo
```

## Components

### Student learning

- [Capture and results](https://github.com/nv-duymanh/mathvisionkid/tree/main/apps/student-mobile/src/app/recognition): `apps/student-mobile/src/app/recognition`
- [Image preparation](https://github.com/nv-duymanh/mathvisionkid/blob/main/apps/student-mobile/src/features/recognition/image/imagePipeline.ts): `apps/student-mobile/src/features/recognition/image/imagePipeline.ts`
- [Recognition client](https://github.com/nv-duymanh/mathvisionkid/blob/main/apps/student-mobile/src/features/recognition/api/RecognitionService.ts): `apps/student-mobile/src/features/recognition/api/RecognitionService.ts`
- [Tutor client](https://github.com/nv-duymanh/mathvisionkid/blob/main/apps/student-mobile/src/features/tutoring/api/TutorService.ts): `apps/student-mobile/src/features/tutoring/api/TutorService.ts`

### Business backend

- [Business API](https://github.com/nv-duymanh/mathvisionkid/tree/main/backend/business-api/src/main/java/com/mathvisionkids/api): `backend/business-api/src/main/java/com/mathvisionkids/api`
- [Submission handling](https://github.com/nv-duymanh/mathvisionkid/blob/main/backend/business-api/src/main/java/com/mathvisionkids/api/submission/SubmissionService.java): `backend/business-api/src/main/java/com/mathvisionkids/api/submission/SubmissionService.java`
- [Image storage](https://github.com/nv-duymanh/mathvisionkid/blob/main/backend/business-api/src/main/java/com/mathvisionkids/api/storage/ObjectStorageService.java): `backend/business-api/src/main/java/com/mathvisionkids/api/storage/ObjectStorageService.java`
- [AI analysis gateway](https://github.com/nv-duymanh/mathvisionkid/blob/main/backend/business-api/src/main/java/com/mathvisionkids/api/analysis/AiAnalysisGateway.java): `backend/business-api/src/main/java/com/mathvisionkids/api/analysis/AiAnalysisGateway.java`
- [Accounts and classes](https://github.com/nv-duymanh/mathvisionkid/blob/main/backend/business-api/src/main/java/com/mathvisionkids/api/admin/AdminService.java): `backend/business-api/src/main/java/com/mathvisionkids/api/admin/AdminService.java`
- [Audit records](https://github.com/nv-duymanh/mathvisionkid/blob/main/backend/business-api/src/main/java/com/mathvisionkids/api/audit/AuditEvent.java): `backend/business-api/src/main/java/com/mathvisionkids/api/audit/AuditEvent.java`

### AI runtime

- [AI service routes](https://github.com/nv-duymanh/mathvisionkid/blob/main/ai/runtime/app/main.py): `ai/runtime/app/main.py`
- [OCR endpoint](https://github.com/nv-duymanh/mathvisionkid/blob/main/ai/runtime/app/api/ocr.py): `ai/runtime/app/api/ocr.py`
- [Row localization](https://github.com/nv-duymanh/mathvisionkid/blob/main/ai/runtime/app/api/generalized_pipeline.py): `ai/runtime/app/api/generalized_pipeline.py`
- [Model recognition](https://github.com/nv-duymanh/mathvisionkid/blob/main/ai/runtime/app/recognition/model_engine.py): `ai/runtime/app/recognition/model_engine.py`
- [Tutoring runtime](https://github.com/nv-duymanh/mathvisionkid/blob/main/ai/runtime/app/api/tutor.py): `ai/runtime/app/api/tutor.py`

### Educator tools

- [Teacher review](https://github.com/nv-duymanh/mathvisionkid/blob/main/apps/teacher-web/src/App.tsx): `apps/teacher-web/src/App.tsx`

### Administration

- [Admin console](https://github.com/nv-duymanh/mathvisionkid/blob/main/apps/admin-web/src/App.tsx): `apps/admin-web/src/App.tsx`
- [Recognition analytics](https://github.com/nv-duymanh/mathvisionkid/blob/main/apps/admin-web/src/pages/RecognitionAnalyticsPage.tsx): `apps/admin-web/src/pages/RecognitionAnalyticsPage.tsx`

### Other components

- **Student**

## Connections

- Student → Capture and results: uses (evidence: `README.md`)
- Capture and results → Image preparation: prepares image (evidence: `apps/student-mobile/src/features/recognition/image/imagePipeline.ts`)
- Capture and results → Recognition client: submits recognition
- Recognition client → Business API: calls API
- Business API → Submission handling: routes submissions (evidence: `backend/business-api/src/main/java/com/mathvisionkids/api/submission/SubmissionService.java`)
- Submission handling → Image storage: stores images (evidence: `backend/business-api/src/main/java/com/mathvisionkids/api/submission/SubmissionService.java`)
- Submission handling → AI analysis gateway: requests analysis (evidence: `backend/business-api/src/main/java/com/mathvisionkids/api/submission/SubmissionService.java`)
- AI analysis gateway → AI service routes: dispatches analysis
- AI service routes → OCR endpoint: mounts OCR route (evidence: `ai/runtime/app/main.py`)
- Business API → OCR endpoint: uses OCR routes (evidence: `README.md`)
- AI service routes → Model recognition: checks readiness (evidence: `ai/runtime/app/main.py`)
- Model recognition → Row localization: recognizes rows
- Capture and results → Tutor client: requests tutoring
- Tutor client → Tutoring runtime: calls tutor API
- Teacher review → Business API: uses business services
- Admin console → Business API: uses business services
- Admin console → Recognition analytics: routes analytics (evidence: `apps/admin-web/src/App.tsx`)
- Business API → Accounts and classes: administers accounts (evidence: `backend/business-api/src/main/java/com/mathvisionkids/api/admin/AdminService.java`)
- Accounts and classes → Audit records: records audit events (evidence: `backend/business-api/src/main/java/com/mathvisionkids/api/admin/AdminService.java`)