# edric2412/q-a architecture

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

- Interactive diagram: https://gitdiagram.com/edric2412/q-a
- Repository: https://github.com/edric2412/q-a

## Overview

This is an AI assessment and adaptive-learning product: faculty create and export question papers, grade student submissions, and review analytics; students review results and practice through an adaptive tutor. The frontend is a set of role-specific pages backed by a FastAPI application, PostgreSQL, and a Neo4j syllabus graph. The README documents additional exports, analytics, OCR, and tutoring capabilities that are not fully visible in the sampled code; those branches are represented at subsystem level. Arrows follow shown calls or documented workflows; unsampled internal details are omitted.

Main entry points: [`frontend/lib/api.ts`](https://github.com/edric2412/q-a/blob/main/frontend/lib/api.ts) (API client), [`frontend/app/dashboard/page.tsx`](https://github.com/edric2412/q-a/blob/main/frontend/app/dashboard/page.tsx) (Faculty dashboard), [`backend/app/main.py`](https://github.com/edric2412/q-a/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/routers/learning.py`](https://github.com/edric2412/q-a/blob/main/backend/app/routers/learning.py) (Tutor session routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web experience"]
  node_login["Sign in<br/>[page.tsx]"]
  node_faculty_dash["Faculty dashboard<br/>[page.tsx]"]
  node_generator_ui["Paper generator<br/>[page.tsx]"]
  node_paper_view["Saved paper view<br/>[page.tsx]"]
  node_evaluator_ui["Evaluation setup<br/>[page.tsx]"]
  node_results_ui["Exam results<br/>[page.tsx]"]
  node_analytics_ui["Performance analytics<br/>[page.tsx]"]
  node_student_dash["Student dashboard<br/>[page.tsx]"]
  node_learning_ui["Learning interface<br/>[page.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_assessment["Assessment workflows"]
  node_api["FastAPI application<br/>[main.py]"]
  node_question_gen["Question generation"]
  node_grading["Answer evaluation<br/>[evaluator.py]"]
  node_vision["PDF vision grading<br/>[vision_utils.py]"]
end

subgraph group_learning["Adaptive learning"]
  node_learning_routes["Tutor session routes<br/>[learning.py]"]
  node_rl["Topic selection<br/>[rl_agent.py]"]
  node_graph_service["Prerequisite reasoning<br/>[graph_service.py]"]
end

subgraph group_data["Persistence and graphs"]
  node_postgres[("PostgreSQL<br/>[database.py]")]
  node_neo4j[("Syllabus knowledge graph")]
end

node_faculty(("Faculty"))
node_student(("Student"))
node_gemini{{"Google Gemini"}}

node_faculty -->|"signs in"| node_login
node_student -->|"signs in"| node_login
node_login -->|"authenticates via"| node_api_client
node_faculty -.->|"manages assessments"| node_faculty_dash
node_faculty_dash -->|"opens generator"| node_generator_ui
node_generator_ui -->|"requests generation"| node_api_client
node_api_client -.->|"calls API"| node_api
node_api -->|"generates questions"| node_question_gen
node_question_gen -.->|"generates with"| node_gemini
node_question_gen -->|"syncs prerequisites"| node_neo4j
node_api -.->|"reads and writes"| node_postgres
node_faculty_dash -.->|"opens evaluator"| node_evaluator_ui
node_evaluator_ui -->|"uploads submissions"| node_api_client
node_api -->|"routes evaluation"| node_grading
node_grading -->|"stores evaluations"| node_postgres
node_grading -->|"grades scanned PDFs"| node_vision
node_grading -.->|"grades with AI"| node_gemini
node_student -.->|"reviews progress"| node_student_dash
node_student_dash -->|"loads evaluations"| node_api_client
node_faculty_dash -.->|"reviews results"| node_results_ui
node_faculty_dash -.->|"opens analytics"| node_analytics_ui
node_student -.->|"practices topics"| node_learning_ui
node_learning_ui -.->|"requests tutor session"| node_api_client
node_api -->|"mounts tutor routes"| node_learning_routes
node_learning_routes -->|"tracks mastery"| node_postgres
node_learning_routes -->|"selects topic"| node_rl
node_learning_routes -->|"gets graph context"| node_graph_service
node_graph_service -->|"queries prerequisites"| node_neo4j
node_graph_service -->|"checks mastery"| node_postgres
node_learning_routes -.->|"evaluates answers"| node_gemini

click node_login "https://github.com/edric2412/q-a/blob/main/frontend/app/page.tsx"
click node_faculty_dash "https://github.com/edric2412/q-a/blob/main/frontend/app/dashboard/page.tsx"
click node_generator_ui "https://github.com/edric2412/q-a/blob/main/frontend/app/generator/page.tsx"
click node_paper_view "https://github.com/edric2412/q-a/blob/main/frontend/app/paper/%5Bid%5D/page.tsx"
click node_evaluator_ui "https://github.com/edric2412/q-a/blob/main/frontend/app/evaluate/page.tsx"
click node_results_ui "https://github.com/edric2412/q-a/blob/main/frontend/app/results/%5Bexam_id%5D/page.tsx"
click node_analytics_ui "https://github.com/edric2412/q-a/blob/main/frontend/app/visualizations/%5Bexam_id%5D/page.tsx"
click node_student_dash "https://github.com/edric2412/q-a/blob/main/frontend/app/student-dashboard/page.tsx"
click node_learning_ui "https://github.com/edric2412/q-a/blob/main/frontend/app/learning/page.tsx"
click node_api_client "https://github.com/edric2412/q-a/blob/main/frontend/lib/api.ts"
click node_api "https://github.com/edric2412/q-a/blob/main/backend/app/main.py"
click node_question_gen "https://github.com/edric2412/q-a/blob/main/backend/app/services/question_generator.py"
click node_grading "https://github.com/edric2412/q-a/blob/main/backend/app/routers/evaluator.py"
click node_vision "https://github.com/edric2412/q-a/blob/main/backend/app/utils/vision_utils.py"
click node_learning_routes "https://github.com/edric2412/q-a/blob/main/backend/app/routers/learning.py"
click node_rl "https://github.com/edric2412/q-a/blob/main/backend/app/services/rl_agent.py"
click node_graph_service "https://github.com/edric2412/q-a/blob/main/backend/app/services/graph_service.py"
click node_postgres "https://github.com/edric2412/q-a/blob/main/backend/app/core/database.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_login,node_faculty_dash,node_generator_ui,node_paper_view,node_evaluator_ui,node_results_ui,node_analytics_ui,node_student_dash,node_learning_ui,node_api_client toneBlue
class node_api,node_question_gen,node_grading,node_vision toneAmber
class node_learning_routes,node_rl,node_graph_service toneMint
class node_postgres,node_neo4j toneRose
class node_faculty,node_student,node_gemini toneIndigo
```

## Components

### Web experience

- [Sign in](https://github.com/edric2412/q-a/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Faculty dashboard](https://github.com/edric2412/q-a/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Paper generator](https://github.com/edric2412/q-a/blob/main/frontend/app/generator/page.tsx): `frontend/app/generator/page.tsx`
- [Saved paper view](https://github.com/edric2412/q-a/blob/main/frontend/app/paper/%5Bid%5D/page.tsx): `frontend/app/paper/[id]/page.tsx`
- [Evaluation setup](https://github.com/edric2412/q-a/blob/main/frontend/app/evaluate/page.tsx): `frontend/app/evaluate/page.tsx`
- [Exam results](https://github.com/edric2412/q-a/blob/main/frontend/app/results/%5Bexam_id%5D/page.tsx): `frontend/app/results/[exam_id]/page.tsx`
- [Performance analytics](https://github.com/edric2412/q-a/blob/main/frontend/app/visualizations/%5Bexam_id%5D/page.tsx): `frontend/app/visualizations/[exam_id]/page.tsx`
- [Student dashboard](https://github.com/edric2412/q-a/blob/main/frontend/app/student-dashboard/page.tsx): `frontend/app/student-dashboard/page.tsx`
- [Learning interface](https://github.com/edric2412/q-a/blob/main/frontend/app/learning/page.tsx): `frontend/app/learning/page.tsx`
- [API client](https://github.com/edric2412/q-a/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### Assessment workflows

- [FastAPI application](https://github.com/edric2412/q-a/blob/main/backend/app/main.py): `backend/app/main.py`
- [Question generation](https://github.com/edric2412/q-a/blob/main/backend/app/services/question_generator.py): `backend/app/services/question_generator.py`
- [Answer evaluation](https://github.com/edric2412/q-a/blob/main/backend/app/routers/evaluator.py): `backend/app/routers/evaluator.py`
- [PDF vision grading](https://github.com/edric2412/q-a/blob/main/backend/app/utils/vision_utils.py): `backend/app/utils/vision_utils.py`

### Adaptive learning

- [Tutor session routes](https://github.com/edric2412/q-a/blob/main/backend/app/routers/learning.py): `backend/app/routers/learning.py`
- [Topic selection](https://github.com/edric2412/q-a/blob/main/backend/app/services/rl_agent.py): `backend/app/services/rl_agent.py`
- [Prerequisite reasoning](https://github.com/edric2412/q-a/blob/main/backend/app/services/graph_service.py): `backend/app/services/graph_service.py`

### Persistence and graphs

- [PostgreSQL](https://github.com/edric2412/q-a/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- **Syllabus knowledge graph**

### Other components

- **Faculty**
- **Student**
- **Google Gemini**

## Connections

- Faculty → Sign in: signs in (evidence: `frontend/app/page.tsx`)
- Student → Sign in: signs in (evidence: `frontend/app/page.tsx`)
- Sign in → API client: authenticates via (evidence: `frontend/app/page.tsx`)
- Faculty → Faculty dashboard: manages assessments
- Faculty dashboard → Paper generator: opens generator (evidence: `frontend/app/dashboard/page.tsx`)
- Paper generator → API client: requests generation (evidence: `frontend/app/generator/page.tsx`)
- API client → FastAPI application: calls API
- FastAPI application → Question generation: generates questions (evidence: `backend/app/main.py`)
- Question generation → Google Gemini: generates with
- Question generation → Syllabus knowledge graph: syncs prerequisites (evidence: `backend/app/services/question_generator.py`)
- FastAPI application → PostgreSQL: reads and writes (evidence: `backend/app/main.py`)
- Faculty dashboard → Evaluation setup: opens evaluator
- Evaluation setup → API client: uploads submissions (evidence: `frontend/app/evaluate/page.tsx`)
- FastAPI application → Answer evaluation: routes evaluation (evidence: `backend/app/main.py`)
- Answer evaluation → PostgreSQL: stores evaluations (evidence: `backend/app/routers/evaluator.py`)
- Answer evaluation → PDF vision grading: grades scanned PDFs (evidence: `backend/app/routers/evaluator.py`)
- Answer evaluation → Google Gemini: grades with AI
- Student → Student dashboard: reviews progress
- Student dashboard → API client: loads evaluations (evidence: `frontend/app/student-dashboard/page.tsx`)
- Faculty dashboard → Exam results: reviews results
- Faculty dashboard → Performance analytics: opens analytics
- Student → Learning interface: practices topics
- Learning interface → API client: requests tutor session
- FastAPI application → Tutor session routes: mounts tutor routes (evidence: `backend/app/main.py`)
- Tutor session routes → PostgreSQL: tracks mastery (evidence: `backend/app/routers/learning.py`)
- Tutor session routes → Topic selection: selects topic (evidence: `backend/app/routers/learning.py`)
- Tutor session routes → Prerequisite reasoning: gets graph context (evidence: `backend/app/routers/learning.py`)
- Prerequisite reasoning → Syllabus knowledge graph: queries prerequisites (evidence: `backend/app/services/graph_service.py`)
- Prerequisite reasoning → PostgreSQL: checks mastery (evidence: `backend/app/services/graph_service.py`)
- Tutor session routes → Google Gemini: evaluates answers
