# siddartha-p99soft/ai-exam-portal architecture

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

- Interactive diagram: https://gitdiagram.com/siddartha-p99soft/ai-exam-portal
- Repository: https://github.com/siddartha-p99soft/ai-exam-portal

## Overview

AI Exam Portal supports admin exam creation from PDFs, student exam sessions and grading, and admin analytics. Admin and student pages call a shared API client; FastAPI routes handle authentication, exam operations, and analytics. Exam creation is orchestrated through content, question, website, and exam-management agents, while submission routes trigger evaluation and anti-cheat processing. MongoDB stores application data, and LLM calls support generation and semantic grading. Some subsystem links rely on README or source-index references because their implementations were not excerpted.

Main entry points: [`frontend/src/App.jsx`](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/App.jsx) (App routing), [`frontend/src/services/api.js`](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/services/api.js) (API client), [`backend/main.py`](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/main.py) (FastAPI app), [`backend/routes/exam.py`](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/routes/exam.py) (Exam routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_app["App routing<br/>[App.jsx]"]
  node_admin_pages["Admin exam pages<br/>[AdminDashboard.jsx]"]
  node_create_page["Exam creation<br/>[CreateExam.jsx]"]
  node_analytics_page["Analytics page<br/>[Analytics.jsx]"]
  node_student_page["Student dashboard"]
  node_exam_page["Exam portal<br/>[ExamPortal.jsx]"]
  node_results_page["Results page<br/>[Results.jsx]"]
  node_auth_pages["Login and register<br/>[Login.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API and persistence"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_admin_routes["Admin routes<br/>[admin.py]"]
  node_exam_routes["Exam routes<br/>[exam.py]"]
  node_analytics_routes["Analytics routes<br/>[analytics.py]"]
  node_auth_utils["JWT and passwords<br/>[auth.py]"]
  node_mongo[("MongoDB data<br/>[database.py]")]
end

subgraph group_agents["AI exam agents"]
  node_orchestrator["Exam pipeline<br/>[orchestrator.py]"]
  node_content_agent["Content understanding<br/>[content_agent.py]"]
  node_question_agent["Question generation<br/>[question_agent.py]"]
  node_website_agent["Exam configuration<br/>[website_agent.py]"]
  node_manager_agent["Exam manager"]
  node_evaluation_agent["Answer evaluation"]
  node_anti_cheat_agent["Anti-cheat analysis"]
  node_analytics_agent["Exam analytics<br/>[analytics_agent.py]"]
end

subgraph group_services["AI services"]
  node_pdf_service["PDF extraction<br/>[pdf_service.py]"]
  node_vector_store["Vector indexing<br/>[vector_store.py]"]
  node_llm_service["LLM service<br/>[llm_service.py]"]
end

node_admin_actor(("Admin"))
node_student_actor(("Student"))
node_llm_provider{{"LLM provider"}}

node_admin_actor -->|"uses"| node_app
node_student_actor -->|"uses"| node_app
node_app -->|"routes to"| node_admin_pages
node_app -->|"routes to"| node_create_page
node_app -->|"routes to"| node_analytics_page
node_app -->|"routes to"| node_student_page
node_app -->|"routes to"| node_exam_page
node_app -->|"routes to"| node_results_page
node_app -->|"routes to"| node_auth_pages
node_admin_pages -->|"requests data"| node_api_client
node_create_page -->|"uploads and creates"| node_api_client
node_analytics_page -->|"fetches analytics"| node_api_client
node_student_page -->|"fetches history"| node_api_client
node_exam_page -->|"starts and submits"| node_api_client
node_results_page -->|"fetches results"| node_api_client
node_auth_pages -->|"authenticates"| node_api_client
node_api_client -->|"calls API"| node_api_app
node_api_app -->|"registers routes"| node_auth_routes
node_api_app -->|"registers routes"| node_admin_routes
node_api_app -->|"registers routes"| node_exam_routes
node_api_app -->|"registers routes"| node_analytics_routes
node_auth_routes -->|"reads and writes"| node_mongo
node_auth_routes -->|"hashes and signs"| node_auth_utils
node_admin_routes -->|"accesses data"| node_mongo
node_admin_routes -->|"starts generation"| node_orchestrator
node_exam_routes -->|"reads and writes"| node_mongo
node_exam_routes -->|"checks identity"| node_auth_utils
node_exam_routes -->|"evaluates answers"| node_evaluation_agent
node_exam_routes -->|"analyzes events"| node_anti_cheat_agent
node_analytics_routes -->|"requests analytics"| node_analytics_agent
node_orchestrator -->|"dispatches first"| node_content_agent
node_orchestrator -->|"dispatches next"| node_question_agent
node_orchestrator -->|"dispatches next"| node_website_agent
node_orchestrator -->|"dispatches next"| node_manager_agent
node_content_agent -->|"extracts text"| node_pdf_service
node_content_agent -->|"indexes content"| node_vector_store
node_content_agent -->|"extracts topics"| node_llm_service
node_question_agent -->|"retrieves content"| node_vector_store
node_question_agent -->|"generates questions"| node_llm_service
node_manager_agent -->|"stores exam"| node_mongo
node_manager_agent -.->|"uses generated data"| node_llm_service
node_evaluation_agent -->|"scores responses"| node_llm_service
node_llm_service -->|"invokes model"| node_llm_provider
node_analytics_agent -.->|"reads submissions"| node_mongo

click node_app "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/App.jsx"
click node_admin_pages "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/pages/AdminDashboard.jsx"
click node_create_page "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/pages/CreateExam.jsx"
click node_analytics_page "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/pages/Analytics.jsx"
click node_student_page "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/pages/StudentDashboard.jsx"
click node_exam_page "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/pages/ExamPortal.jsx"
click node_results_page "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/pages/Results.jsx"
click node_auth_pages "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/pages/Login.jsx"
click node_api_client "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/services/api.js"
click node_api_app "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/main.py"
click node_auth_routes "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/routes/auth.py"
click node_admin_routes "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/routes/admin.py"
click node_exam_routes "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/routes/exam.py"
click node_analytics_routes "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/routes/analytics.py"
click node_auth_utils "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/utils/auth.py"
click node_mongo "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/database.py"
click node_orchestrator "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/agents/orchestrator.py"
click node_content_agent "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/agents/content_agent.py"
click node_question_agent "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/agents/question_agent.py"
click node_website_agent "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/agents/website_agent.py"
click node_manager_agent "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/agents/exam_manager_agent.py"
click node_evaluation_agent "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/agents/evaluation_agent.py"
click node_anti_cheat_agent "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/agents/anti_cheat_agent.py"
click node_analytics_agent "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/agents/analytics_agent.py"
click node_pdf_service "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/services/pdf_service.py"
click node_vector_store "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/services/vector_store.py"
click node_llm_service "https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/services/llm_service.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_app,node_admin_pages,node_create_page,node_analytics_page,node_student_page,node_exam_page,node_results_page,node_auth_pages,node_api_client toneBlue
class node_api_app,node_auth_routes,node_admin_routes,node_exam_routes,node_analytics_routes,node_auth_utils,node_mongo toneAmber
class node_orchestrator,node_content_agent,node_question_agent,node_website_agent,node_manager_agent,node_evaluation_agent,node_anti_cheat_agent,node_analytics_agent toneMint
class node_pdf_service,node_vector_store,node_llm_service toneRose
class node_admin_actor,node_student_actor,node_llm_provider toneIndigo
```

## Components

### Web application

- [App routing](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Admin exam pages](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/pages/AdminDashboard.jsx): `frontend/src/pages/AdminDashboard.jsx`
- [Exam creation](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/pages/CreateExam.jsx): `frontend/src/pages/CreateExam.jsx`
- [Analytics page](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/pages/Analytics.jsx): `frontend/src/pages/Analytics.jsx`
- [Student dashboard](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/pages/StudentDashboard.jsx): `frontend/src/pages/StudentDashboard.jsx`
- [Exam portal](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/pages/ExamPortal.jsx): `frontend/src/pages/ExamPortal.jsx`
- [Results page](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/pages/Results.jsx): `frontend/src/pages/Results.jsx`
- [Login and register](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/pages/Login.jsx): `frontend/src/pages/Login.jsx`
- [API client](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### API and persistence

- [FastAPI app](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/main.py): `backend/main.py`
- [Authentication routes](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/routes/auth.py): `backend/routes/auth.py`
- [Admin routes](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/routes/admin.py): `backend/routes/admin.py`
- [Exam routes](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/routes/exam.py): `backend/routes/exam.py`
- [Analytics routes](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/routes/analytics.py): `backend/routes/analytics.py`
- [JWT and passwords](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/utils/auth.py): `backend/utils/auth.py`
- [MongoDB data](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/database.py): `backend/database.py`

### AI exam agents

- [Exam pipeline](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/agents/orchestrator.py): `backend/agents/orchestrator.py`
- [Content understanding](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/agents/content_agent.py): `backend/agents/content_agent.py`
- [Question generation](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/agents/question_agent.py): `backend/agents/question_agent.py`
- [Exam configuration](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/agents/website_agent.py): `backend/agents/website_agent.py`
- [Exam manager](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/agents/exam_manager_agent.py): `backend/agents/exam_manager_agent.py`
- [Answer evaluation](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/agents/evaluation_agent.py): `backend/agents/evaluation_agent.py`
- [Anti-cheat analysis](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/agents/anti_cheat_agent.py): `backend/agents/anti_cheat_agent.py`
- [Exam analytics](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/agents/analytics_agent.py): `backend/agents/analytics_agent.py`

### AI services

- [PDF extraction](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/services/pdf_service.py): `backend/services/pdf_service.py`
- [Vector indexing](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/services/vector_store.py): `backend/services/vector_store.py`
- [LLM service](https://github.com/siddartha-p99soft/ai-exam-portal/blob/main/backend/services/llm_service.py): `backend/services/llm_service.py`

### Other components

- **Admin**
- **Student**
- **LLM provider**

## Connections

- Admin → App routing: uses (evidence: `README.md`)
- Student → App routing: uses (evidence: `README.md`)
- App routing → Admin exam pages: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Exam creation: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Analytics page: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Student dashboard: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Exam portal: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Results page: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Login and register: routes to (evidence: `frontend/src/App.jsx`)
- Admin exam pages → API client: requests data (evidence: `frontend/src/pages/AdminDashboard.jsx`)
- Exam creation → API client: uploads and creates (evidence: `frontend/src/pages/CreateExam.jsx`)
- Analytics page → API client: fetches analytics (evidence: `frontend/src/pages/Analytics.jsx`)
- Student dashboard → API client: fetches history (evidence: `frontend/src/pages/StudentDashboard.jsx`)
- Exam portal → API client: starts and submits (evidence: `frontend/src/pages/ExamPortal.jsx`)
- Results page → API client: fetches results (evidence: `frontend/src/pages/Results.jsx`)
- Login and register → API client: authenticates (evidence: `frontend/src/pages/Login.jsx`)
- API client → FastAPI app: calls API (evidence: `frontend/src/services/api.js`)
- FastAPI app → Authentication routes: registers routes (evidence: `backend/main.py`)
- FastAPI app → Admin routes: registers routes (evidence: `backend/main.py`)
- FastAPI app → Exam routes: registers routes (evidence: `backend/main.py`)
- FastAPI app → Analytics routes: registers routes (evidence: `backend/main.py`)
- Authentication routes → MongoDB data: reads and writes (evidence: `backend/routes/auth.py`)
- Authentication routes → JWT and passwords: hashes and signs (evidence: `backend/routes/auth.py`)
- Admin routes → MongoDB data: accesses data (evidence: `backend/routes/admin.py`)
- Admin routes → Exam pipeline: starts generation (evidence: `backend/routes/admin.py`)
- Exam routes → MongoDB data: reads and writes (evidence: `backend/routes/exam.py`)
- Exam routes → JWT and passwords: checks identity (evidence: `backend/routes/exam.py`)
- Exam routes → Answer evaluation: evaluates answers (evidence: `backend/routes/exam.py`)
- Exam routes → Anti-cheat analysis: analyzes events (evidence: `backend/routes/exam.py`)
- Analytics routes → Exam analytics: requests analytics (evidence: `backend/routes/analytics.py`)
- Exam pipeline → Content understanding: dispatches first (evidence: `backend/agents/orchestrator.py`)
- Exam pipeline → Question generation: dispatches next (evidence: `backend/agents/orchestrator.py`)
- Exam pipeline → Exam configuration: dispatches next (evidence: `backend/agents/orchestrator.py`)
- Exam pipeline → Exam manager: dispatches next (evidence: `backend/agents/orchestrator.py`)
- Content understanding → PDF extraction: extracts text (evidence: `backend/agents/content_agent.py`)
- Content understanding → Vector indexing: indexes content (evidence: `backend/agents/content_agent.py`)
- Content understanding → LLM service: extracts topics (evidence: `backend/agents/content_agent.py`)
- Question generation → Vector indexing: retrieves content (evidence: `backend/agents/question_agent.py`)
- Question generation → LLM service: generates questions (evidence: `backend/agents/question_agent.py`)
- Exam manager → MongoDB data: stores exam (evidence: `backend/agents/exam_manager_agent.py`)
- Exam manager → LLM service: uses generated data
- Answer evaluation → LLM service: scores responses (evidence: `backend/agents/evaluation_agent.py`)
- LLM service → LLM provider: invokes model (evidence: `backend/services/llm_service.py`)
- Exam analytics → MongoDB data: reads submissions
