# angelperezcastro/ai_agent_for_auto-grading architecture

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

- Interactive diagram: https://gitdiagram.com/angelperezcastro/ai_agent_for_auto-grading
- Repository: https://github.com/angelperezcastro/ai_agent_for_auto-grading

## Overview

This is a full-stack academic auto-grading platform. Students browse courses, enroll in projects, submit four sequential deliverables, and receive rubric-based AI scores and feedback; professors manage coursework, monitor progress, and override scores. The backend also handles role-based authentication, Gmail OAuth and routed notifications, with relational persistence and email-attempt logging. The graph reflects README capabilities and sampled entry points; several backend workflow details are documented but their implementation was not sampled, so uncertain internal call wiring is omitted.

Main entry points: [`backend/app/main.py`](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/main.py) (REST API), [`backend/app/database.py`](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/database.py) (Relational data), [`frontend/src/App.jsx`](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/frontend/src/App.jsx) (React application), [`frontend/src/pages/professor/ProfessorDashboard.jsx`](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/frontend/src/pages/professor/ProfessorDashboard.jsx) (Professor console)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web experience"]
  node_webapp["React application<br/>[App.jsx]"]
  node_authui["Auth context<br/>[AuthContext.jsx]"]
  node_studentui["Student workspace<br/>[WorkspacePage.jsx]"]
  node_profui["Professor console"]
  node_profdetail["Student detail"]
end

subgraph group_academic["Academic workflows"]
  node_subjects["Subjects and projects<br/>[subjects.py]"]
  node_projects["Project management<br/>[projects.py]"]
  node_enrollments["Enrollment progress<br/>[enrollments.py]"]
  node_submissions["Submission workflow<br/>[submissions.py]"]
  node_rules["Sequence rules"]
  node_professorapi["Professor operations<br/>[professor.py]"]
end

subgraph group_evaluation["Evaluation and messaging"]
  node_evaluation["AI evaluation<br/>[evaluator.py]"]
  node_dispatcher["AI dispatcher<br/>[dispatcher.py]"]
  node_evaluationapi["Evaluation endpoints<br/>[evaluations.py]"]
  node_gmailauth["Gmail OAuth<br/>[gmail_auth.py]"]
  node_emaildispatch["Email dispatch<br/>[email_dispatch.py]"]
  node_emailservice["Gmail sender<br/>[email_service.py]"]
  node_emaillog["Email audit"]
end

subgraph group_platform["Backend platform"]
  node_api["REST API<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_database[("Relational data<br/>[database.py]")]
end

node_student(("Student"))
node_professor(("Professor"))
node_gemini{{"Google Gemini"}}
node_gmail{{"Gmail API"}}
node_postgres[("PostgreSQL")]
node_recipients(("Email recipients"))

node_student -->|"uses"| node_webapp
node_professor -->|"uses"| node_webapp
node_webapp -->|"provides auth"| node_authui
node_webapp -->|"routes students"| node_studentui
node_webapp -->|"routes professors"| node_profui
node_profui -->|"opens details"| node_profdetail
node_webapp -->|"REST requests"| node_api
node_api -->|"dispatches"| node_auth
node_api -->|"dispatches"| node_subjects
node_api -->|"dispatches"| node_projects
node_api -->|"dispatches"| node_enrollments
node_api -->|"dispatches"| node_submissions
node_api -->|"dispatches"| node_evaluationapi
node_api -->|"dispatches"| node_professorapi
node_api -->|"dispatches"| node_gmailauth
node_studentui -->|"enrolls and tracks"| node_enrollments
node_studentui -->|"submits deliverables"| node_submissions
node_profui -->|"manages courses"| node_subjects
node_profui -->|"manages projects"| node_projects
node_profui -->|"views progress"| node_professorapi
node_profdetail -->|"reviews and overrides"| node_evaluationapi
node_submissions -->|"checks sequence"| node_rules
node_submissions -->|"triggers grading"| node_evaluation
node_dispatcher -->|"dispatches evaluation"| node_evaluation
node_evaluation -.->|"requests grading"| node_gemini
node_evaluationapi -->|"loads and saves"| node_database
node_submissions -->|"stores submissions"| node_database
node_enrollments -->|"reads progress"| node_database
node_subjects -->|"persists courses"| node_database
node_projects -->|"persists projects"| node_database
node_auth -->|"reads and writes users"| node_database
node_database -->|"SQL access"| node_postgres
node_gmailauth -->|"stores account"| node_database
node_gmailauth -.->|"OAuth connection"| node_gmail
node_emaildispatch -->|"sends messages"| node_emailservice
node_emailservice -->|"sends email"| node_gmail
node_emaildispatch -->|"records attempts"| node_emaillog
node_emaillog -->|"writes logs"| node_database
node_emailservice -->|"loads credentials"| node_database
node_emaildispatch -->|"delivers notices"| node_recipients

click node_webapp "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/frontend/src/App.jsx"
click node_authui "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/frontend/src/context/AuthContext.jsx"
click node_studentui "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/frontend/src/pages/WorkspacePage.jsx"
click node_profui "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/frontend/src/pages/professor/ProfessorDashboard.jsx"
click node_profdetail "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/frontend/src/pages/professor/StudentDetailPage.jsx"
click node_api "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/main.py"
click node_auth "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/routers/auth.py"
click node_subjects "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/routers/subjects.py"
click node_projects "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/routers/projects.py"
click node_enrollments "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/routers/enrollments.py"
click node_submissions "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/routers/submissions.py"
click node_rules "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/services/submission_rules.py"
click node_evaluation "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/ai/evaluator.py"
click node_dispatcher "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/ai/dispatcher.py"
click node_evaluationapi "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/routers/evaluations.py"
click node_professorapi "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/routers/professor.py"
click node_gmailauth "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/routers/gmail_auth.py"
click node_emaildispatch "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/services/email_dispatch.py"
click node_emailservice "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/services/email_service.py"
click node_emaillog "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/services/email_log_service.py"
click node_database "https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/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_webapp,node_authui,node_studentui,node_profui,node_profdetail toneBlue
class node_subjects,node_projects,node_enrollments,node_submissions,node_rules,node_professorapi,node_postgres toneAmber
class node_evaluation,node_dispatcher,node_evaluationapi,node_gmailauth,node_emaildispatch,node_emailservice,node_emaillog,node_gmail toneMint
class node_api,node_auth,node_database toneRose
class node_student,node_professor,node_gemini,node_recipients toneIndigo
```

## Components

### Web experience

- [React application](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Auth context](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Student workspace](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/frontend/src/pages/WorkspacePage.jsx): `frontend/src/pages/WorkspacePage.jsx`
- [Professor console](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/frontend/src/pages/professor/ProfessorDashboard.jsx): `frontend/src/pages/professor/ProfessorDashboard.jsx`
- [Student detail](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/frontend/src/pages/professor/StudentDetailPage.jsx): `frontend/src/pages/professor/StudentDetailPage.jsx`

### Academic workflows

- [Subjects and projects](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/routers/subjects.py): `backend/app/routers/subjects.py`
- [Project management](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/routers/projects.py): `backend/app/routers/projects.py`
- [Enrollment progress](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/routers/enrollments.py): `backend/app/routers/enrollments.py`
- [Submission workflow](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/routers/submissions.py): `backend/app/routers/submissions.py`
- [Sequence rules](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/services/submission_rules.py): `backend/app/services/submission_rules.py`
- [Professor operations](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/routers/professor.py): `backend/app/routers/professor.py`

### Evaluation and messaging

- [AI evaluation](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/ai/evaluator.py): `backend/app/ai/evaluator.py`
- [AI dispatcher](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/ai/dispatcher.py): `backend/app/ai/dispatcher.py`
- [Evaluation endpoints](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/routers/evaluations.py): `backend/app/routers/evaluations.py`
- [Gmail OAuth](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/routers/gmail_auth.py): `backend/app/routers/gmail_auth.py`
- [Email dispatch](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/services/email_dispatch.py): `backend/app/services/email_dispatch.py`
- [Gmail sender](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/services/email_service.py): `backend/app/services/email_service.py`
- [Email audit](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/services/email_log_service.py): `backend/app/services/email_log_service.py`

### Backend platform

- [REST API](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Relational data](https://github.com/angelperezcastro/ai_agent_for_auto-grading/blob/main/backend/app/database.py): `backend/app/database.py`

### Other components

- **Student**
- **Professor**
- **Google Gemini**
- **Gmail API**
- **PostgreSQL**
- **Email recipients**

## Connections

- Student → React application: uses
- Professor → React application: uses
- React application → Auth context: provides auth
- React application → Student workspace: routes students
- React application → Professor console: routes professors
- Professor console → Student detail: opens details
- React application → REST API: REST requests
- REST API → Authentication: dispatches
- REST API → Subjects and projects: dispatches
- REST API → Project management: dispatches
- REST API → Enrollment progress: dispatches
- REST API → Submission workflow: dispatches
- REST API → Evaluation endpoints: dispatches
- REST API → Professor operations: dispatches
- REST API → Gmail OAuth: dispatches
- Student workspace → Enrollment progress: enrolls and tracks
- Student workspace → Submission workflow: submits deliverables
- Professor console → Subjects and projects: manages courses
- Professor console → Project management: manages projects
- Professor console → Professor operations: views progress
- Student detail → Evaluation endpoints: reviews and overrides
- Submission workflow → Sequence rules: checks sequence
- Submission workflow → AI evaluation: triggers grading
- AI dispatcher → AI evaluation: dispatches evaluation
- AI evaluation → Google Gemini: requests grading
- Evaluation endpoints → Relational data: loads and saves
- Submission workflow → Relational data: stores submissions
- Enrollment progress → Relational data: reads progress
- Subjects and projects → Relational data: persists courses
- Project management → Relational data: persists projects
- Authentication → Relational data: reads and writes users
- Relational data → PostgreSQL: SQL access
- Gmail OAuth → Relational data: stores account
- Gmail OAuth → Gmail API: OAuth connection
- Email dispatch → Gmail sender: sends messages
- Gmail sender → Gmail API: sends email
- Email dispatch → Email audit: records attempts
- Email audit → Relational data: writes logs
- Gmail sender → Relational data: loads credentials
- Email dispatch → Email recipients: delivers notices