# faiqimran589/evalassist-ai architecture

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

- Interactive diagram: https://gitdiagram.com/faiqimran589/evalassist-ai
- Repository: https://github.com/faiqimran589/evalassist-ai

## Overview

EvalAssist AI serves teachers creating and reviewing assessments and students taking timed attempts, uploading answers, and receiving feedback and learning recommendations. The principal flow runs from assessment setup through student submission, AI grading, teacher review, and student-facing results. The README documents image/PDF extraction, analytics, growth plans, and learning paths; these are represented by their endpoint and service modules even where implementation excerpts were unavailable. Grading and session behavior are sampled; wiring for unsampled features is limited to documented API boundaries.

Main entry points: [`backend/app/api/v1/router.py`](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/router.py) (API router), [`backend/app/core/database.py`](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/core/database.py) (SQLite database), [`frontend/lib/api.ts`](https://github.com/faiqimran589/evalassist-ai/blob/main/frontend/lib/api.ts) (API client), [`backend/app/api/v1/endpoints/assessment_session.py`](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/endpoints/assessment_session.py) (Session endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Web experience"]
  node_teacher_ui["Teacher workspace<br/>[page.tsx]"]
  node_assessment_ui["Assessment wizard<br/>[page.tsx]"]
  node_teacher_review_ui["Submission review<br/>[page.tsx]"]
  node_student_ui["Student assessment<br/>[page.tsx]"]
  node_student_results["Student results<br/>[page.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["Application API"]
  node_app["FastAPI application<br/>[main.py]"]
  node_router["API router<br/>[router.py]"]
  node_auth["Authentication<br/>[auth.py]"]
end

subgraph group_assessment["Assessment workflow"]
  node_assessments["Assessment endpoints<br/>[assessments.py]"]
  node_sessions["Session endpoints"]
  node_submissions["Submission endpoints<br/>[submissions.py]"]
  node_storage["Upload storage<br/>[storage.py]"]
  node_grading["Grading engine<br/>[grading_engine.py]"]
  node_extraction["Image extraction"]
  node_attempt_manager["Attempt manager<br/>[session_manager.py]"]
end

subgraph group_insights["Learning insights"]
  node_performance["Performance analytics<br/>[performance.py]"]
  node_growth["Growth plans<br/>[growth_plans.py]"]
  node_learning["Learning path<br/>[learning_path.py]"]
  node_dashboard["Student dashboard"]
end

subgraph group_runtime["Core services"]
  node_vision["Vision service<br/>[gemini_vision.py]"]
  node_ocr["OCR service<br/>[ocr_service.py]"]
  node_semantic["Semantic evaluator"]
  node_database[("SQLite database<br/>[database.py]")]
end

node_teacher(("Teacher"))
node_student(("Student"))
node_ai_provider{{"Gemini AI"}}
node_local_ocr{{"EasyOCR"}}

node_teacher -->|"uses"| node_teacher_ui
node_student -->|"uses"| node_student_ui
node_teacher_ui -->|"requests"| node_api_client
node_assessment_ui -->|"requests"| node_api_client
node_teacher_review_ui -->|"requests"| node_api_client
node_student_ui -->|"requests"| node_api_client
node_student_results -->|"requests"| node_api_client
node_api_client -->|"calls API"| node_app
node_app -->|"mounts"| node_router
node_router -->|"dispatches"| node_auth
node_router -->|"dispatches"| node_assessments
node_router -->|"dispatches"| node_sessions
node_router -->|"dispatches"| node_submissions
node_router -->|"dispatches"| node_performance
node_router -->|"dispatches"| node_growth
node_router -->|"dispatches"| node_learning
node_router -->|"dispatches"| node_dashboard
node_sessions -->|"calls"| node_attempt_manager
node_sessions -->|"saves uploads"| node_storage
node_sessions -->|"grades submission"| node_grading
node_grading -->|"grades answers"| node_vision
node_grading -->|"fallback evaluates"| node_semantic
node_vision -->|"extracts text"| node_ocr
node_ocr -.->|"requests OCR"| node_ai_provider
node_ocr -.->|"fallback OCR"| node_local_ocr
node_extraction -.->|"extracts content"| node_ai_provider
node_assessments -.->|"extracts papers"| node_extraction
node_assessments -->|"reads/writes"| node_database
node_auth -->|"reads/writes"| node_database
node_attempt_manager -->|"reads/writes"| node_database
node_sessions -->|"writes records"| node_database
node_grading -->|"reads/writes"| node_database
node_submissions -->|"reads/writes"| node_database
node_performance -->|"reads results"| node_database
node_growth -->|"reads performance"| node_database
node_learning -->|"reads performance"| node_database
node_dashboard -->|"reads dashboard data"| node_database

click node_teacher_ui "https://github.com/faiqimran589/evalassist-ai/blob/main/frontend/app/dashboard/page.tsx"
click node_assessment_ui "https://github.com/faiqimran589/evalassist-ai/blob/main/frontend/app/assessments/new/page.tsx"
click node_teacher_review_ui "https://github.com/faiqimran589/evalassist-ai/blob/main/frontend/app/submissions/%5Bid%5D/page.tsx"
click node_student_ui "https://github.com/faiqimran589/evalassist-ai/blob/main/frontend/app/student/assessments/%5Bid%5D/take/page.tsx"
click node_student_results "https://github.com/faiqimran589/evalassist-ai/blob/main/frontend/app/student/submissions/%5Bid%5D/page.tsx"
click node_api_client "https://github.com/faiqimran589/evalassist-ai/blob/main/frontend/lib/api.ts"
click node_app "https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/main.py"
click node_router "https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/router.py"
click node_auth "https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/endpoints/auth.py"
click node_assessments "https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/endpoints/assessments.py"
click node_sessions "https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/endpoints/assessment_session.py"
click node_submissions "https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/endpoints/submissions.py"
click node_storage "https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/services/storage.py"
click node_grading "https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/services/grading_engine.py"
click node_extraction "https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/services/diagram_extractor.py"
click node_vision "https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/services/gemini_vision.py"
click node_ocr "https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/services/ocr_service.py"
click node_semantic "https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/services/semantic_evaluator.py"
click node_attempt_manager "https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/services/session_manager.py"
click node_database "https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/core/database.py"
click node_performance "https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/endpoints/performance.py"
click node_growth "https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/endpoints/growth_plans.py"
click node_learning "https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/endpoints/learning_path.py"
click node_dashboard "https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/endpoints/student_dashboard.py"

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_teacher_ui,node_assessment_ui,node_teacher_review_ui,node_student_ui,node_student_results,node_api_client toneBlue
class node_app,node_router,node_auth toneAmber
class node_assessments,node_sessions,node_submissions,node_storage,node_grading,node_extraction,node_attempt_manager toneMint
class node_performance,node_growth,node_learning,node_dashboard toneRose
class node_vision,node_ocr,node_semantic,node_database,node_teacher,node_student,node_ai_provider,node_local_ocr toneIndigo
```

## Components

### Web experience

- [Teacher workspace](https://github.com/faiqimran589/evalassist-ai/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Assessment wizard](https://github.com/faiqimran589/evalassist-ai/blob/main/frontend/app/assessments/new/page.tsx): `frontend/app/assessments/new/page.tsx`
- [Submission review](https://github.com/faiqimran589/evalassist-ai/blob/main/frontend/app/submissions/%5Bid%5D/page.tsx): `frontend/app/submissions/[id]/page.tsx`
- [Student assessment](https://github.com/faiqimran589/evalassist-ai/blob/main/frontend/app/student/assessments/%5Bid%5D/take/page.tsx): `frontend/app/student/assessments/[id]/take/page.tsx`
- [Student results](https://github.com/faiqimran589/evalassist-ai/blob/main/frontend/app/student/submissions/%5Bid%5D/page.tsx): `frontend/app/student/submissions/[id]/page.tsx`
- [API client](https://github.com/faiqimran589/evalassist-ai/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### Application API

- [FastAPI application](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [API router](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Authentication](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/endpoints/auth.py): `backend/app/api/v1/endpoints/auth.py`

### Assessment workflow

- [Assessment endpoints](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/endpoints/assessments.py): `backend/app/api/v1/endpoints/assessments.py`
- [Session endpoints](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/endpoints/assessment_session.py): `backend/app/api/v1/endpoints/assessment_session.py`
- [Submission endpoints](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/endpoints/submissions.py): `backend/app/api/v1/endpoints/submissions.py`
- [Upload storage](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/services/storage.py): `backend/app/services/storage.py`
- [Grading engine](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/services/grading_engine.py): `backend/app/services/grading_engine.py`
- [Image extraction](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/services/diagram_extractor.py): `backend/app/services/diagram_extractor.py`
- [Attempt manager](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/services/session_manager.py): `backend/app/services/session_manager.py`

### Learning insights

- [Performance analytics](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/endpoints/performance.py): `backend/app/api/v1/endpoints/performance.py`
- [Growth plans](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/endpoints/growth_plans.py): `backend/app/api/v1/endpoints/growth_plans.py`
- [Learning path](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/endpoints/learning_path.py): `backend/app/api/v1/endpoints/learning_path.py`
- [Student dashboard](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/api/v1/endpoints/student_dashboard.py): `backend/app/api/v1/endpoints/student_dashboard.py`

### Core services

- [Vision service](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/services/gemini_vision.py): `backend/app/services/gemini_vision.py`
- [OCR service](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/services/ocr_service.py): `backend/app/services/ocr_service.py`
- [Semantic evaluator](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/services/semantic_evaluator.py): `backend/app/services/semantic_evaluator.py`
- [SQLite database](https://github.com/faiqimran589/evalassist-ai/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Other components

- **Teacher**
- **Student**
- **Gemini AI**
- **EasyOCR**

## Connections

- Teacher → Teacher workspace: uses
- Student → Student assessment: uses
- Teacher workspace → API client: requests
- Assessment wizard → API client: requests
- Submission review → API client: requests
- Student assessment → API client: requests
- Student results → API client: requests
- API client → FastAPI application: calls API
- FastAPI application → API router: mounts
- API router → Authentication: dispatches
- API router → Assessment endpoints: dispatches
- API router → Session endpoints: dispatches
- API router → Submission endpoints: dispatches
- API router → Performance analytics: dispatches
- API router → Growth plans: dispatches
- API router → Learning path: dispatches
- API router → Student dashboard: dispatches
- Session endpoints → Attempt manager: calls
- Session endpoints → Upload storage: saves uploads
- Session endpoints → Grading engine: grades submission
- Grading engine → Vision service: grades answers
- Grading engine → Semantic evaluator: fallback evaluates
- Vision service → OCR service: extracts text
- OCR service → Gemini AI: requests OCR
- OCR service → EasyOCR: fallback OCR
- Image extraction → Gemini AI: extracts content
- Assessment endpoints → Image extraction: extracts papers
- Assessment endpoints → SQLite database: reads/writes
- Authentication → SQLite database: reads/writes
- Attempt manager → SQLite database: reads/writes
- Session endpoints → SQLite database: writes records
- Grading engine → SQLite database: reads/writes
- Submission endpoints → SQLite database: reads/writes
- Performance analytics → SQLite database: reads results
- Growth plans → SQLite database: reads performance
- Learning path → SQLite database: reads performance
- Student dashboard → SQLite database: reads dashboard data