# harrypeter07/aievaluator architecture

> Architecture diagram of the GitHub repository harrypeter07/aievaluator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harrypeter07/aievaluator
- Repository: https://github.com/harrypeter07/aievaluator

## Overview

##### Project type and purpose
- This is a full-stack web application built with Next.js (React) on the frontend and Next.js API routes (Node.js) on the backend, using MongoDB for data persistence.
- Its purpose is to automate assignment evaluation and grading via Google Gemini AI, integrate with Google Classroom, and provide an intuitive dashboard and analytics.

##### File structure
- **Frontend (app & components)**
- app/layout.tsx, app/page.tsx, app/login, app/signup, app/dashboard, app/classroom, etc.
- app/api – Next.js route handlers under app/api/assignments/* and app/api/auth/*
- components and components/ui – reusable presentational components (Navbar, FileHandler, typewriter effect)
- styles: globals.css, tailwind.config.js, postcss.config.mjs
- **Backend & Services (lib & models)**
- lib/authOptions.js, lib/cache.js, lib/classroomGemini.js, lib/gemini.js, lib/db.js, lib/logger.js, lib/rateLimit.js, lib/utils.js
- lib/models/Evaluation.js (Mongoose schema)
- models/Assignment.js, models/User.js (data definitions)
- **Configuration & Deployment**
- next.config.js/.ts, tsconfig.json, folder-alias.json, eslint.config.mjs, package.json, .gitignore
- **Public & Static assets**
- public/manifest.json, public/folder-alias.json

##### README for additional insights
- Tech stack: Next.js 14, TypeScript, TailwindCSS, Shadcn UI on front; Node.js/Express.js (via Next API), MongoDB, WebSocket on back.
- Integrations: Google OAuth2, Google Classroom API, Google Drive API, Gemini AI API.
- System Architecture summary:
Client Layer → API Layer (REST + WebSocket) → Authentication (OAuth) → Service Layer → Database Layer

##### Main components and interactions
a. **Client (User’s Browser / Mobile)**
- Next.js pages (SSR/CSR), React components, WebSocket connections (real-time updates)
b. **API Layer (Next.js API Routes)**
- /api/auth (signup, NextAuth)
- /api/assignments/* (analyze, compare, fetch, count, evaluateClassroomSubmissions, getEvaluations, saveEvaluation, updateCount)
- Real-time events via WebSocket (if implemented)
c. **Service Layer / Business Logic (lib/**)**
- Authentication (NextAuth + Google OAuth)
- Classroom & Gemini integration (lib/classroomGemini.js, lib/gemini.js)
- Assignment processing pipelines (analyze, compare, score)
- Caching, rate limiting, logging utilities
d. **Data Layer (MongoDB)**
- Collections: users, assignments, evaluations
- Access via Mongoose models in lib/models and models/
e. **External Services**
- Google OAuth2 (authentication)
- Google Classroom API (fetch course work, sync grades)
- Google Drive API (if attachments stored)
- Gemini AI API (content analysis & feedback generation)

##### Architectural patterns & design principles
- **Separation of concerns**: clear divide between presentation (Next.js pages/components), API routing, business logic (lib/), and data models.
- **Modular service functions**: each assignment operation is its own route + service method.
- **Third-party integration layer**: encapsulated in lib/classroomGemini.js and lib/gemini.js.
- **Scalability considerations**: stateless API routes, MongoDB Atlas for persistence, caching & rate-limiting middleware.

##### Essential elements
- Component names (e.g., “/api/assignments/analyze Route Handler”)
- Data flow directions (e.g., “POST /api/assignments/analyze → lib/gemini.analyze()”)
- Tech labels (Next.js 14, TailwindCSS, Mongoose, Google APIs)
- Authentication flow (User → Google OAuth → NextAuth)
- Error handling / logging (lib/logger.js) and rate-limit (lib/rateLimit.js) middleware if desired

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Swimlanes
    subgraph "Client Layer" 
        direction TB
        Layout["app/layout.tsx"]:::frontend
        HomePage["app/page.tsx"]:::frontend
        LoginPage["app/login/page.jsx"]:::frontend
        SignupPage["app/signup/page.jsx"]:::frontend
        DashboardPage["app/dashboard/page.jsx"]:::frontend
        ComparePage["app/dashboard/compare/page.jsx"]:::frontend
        SinglePage["app/dashboard/single/page.jsx"]:::frontend
        ClassroomPage["app/classroom/page.jsx"]:::frontend
        CoursePage["app/classroom/[courseId]/page.jsx"]:::frontend
        CourseWorkPage["app/classroom/[courseId]/[courseWorkId]/page.jsx"]:::frontend
        AboutPage["app/about/page.jsx"]:::frontend
        Navbar["components/Navbar.jsx"]:::frontend
        FileHandler["components/FileHandler.jsx"]:::frontend
        ComparisonResult["components/ComparisonResult.jsx"]:::frontend
        EvaluationPreview["components/EvaluationResultPreview.jsx"]:::frontend
        ResultPreview["components/ResultPreview.jsx"]:::frontend
        LoginForm["components/LoginForm.jsx"]:::frontend
        SignupForm["components/SignupForm.jsx"]:::frontend
        Footer["components/Footer.jsx"]:::frontend
        FileUploadUI["components/ui/file-upload.jsx"]:::frontend
        TypewriterUI["components/ui/typewriter-effect.jsx"]:::frontend
    end

    subgraph "Backend Layer"
        direction TB
        subgraph "API Layer"
            direction TB
            AuthRoute["app/api/auth/[...nextauth]/route.js"]:::api
            SignupRoute["app/api/auth/signup/route.js"]:::api
            AnalyzeRoute["app/api/assignments/analyze/route.js"]:::api
            CompareRoute["app/api/assignments/compare/route.js"]:::api
            CountRoute["app/api/assignments/count/route.js"]:::api
            EvalClassroomRoute["app/api/assignments/evaluateClassroomSubmissions/route.js"]:::api
            FetchRoute["app/api/assignments/fetch/route.js"]:::api
            FetchCourseWorkRoute["app/api/assignments/fetchCourseWork/route.js"]:::api
            FetchCourseWorkDetailsRoute["app/api/assignments/fetchCourseWorkDetails/route.js"]:::api
            GetEvalsRoute["app/api/assignments/getEvaluations/route.js"]:::api
            SaveEvalRoute["app/api/assignments/saveEvaluation/route.js"]:::api
            UpdateCountRoute["app/api/assignments/updateCount/route.js"]:::api
        end

        subgraph "Service Layer"
            direction TB
            AuthOptions["lib/authOptions.js"]:::service
            ClassroomGemini["lib/classroomGemini.js"]:::service
            GeminiAPI["lib/gemini.js"]:::service
            CacheUtil["lib/cache.js"]:::service
            RateLimit["lib/rateLimit.js"]:::service
            Logger["lib/logger.js"]:::service
            Utils["lib/utils.js"]:::service
        end

        subgraph "Data Layer"
            direction TB
            DBConn["lib/db.js"]:::db
            EvalModel["lib/models/Evaluation.js"]:::db
            AssignmentModel["models/Assignment.js"]:::db
            UserModel["models/User.js"]:::db
        end
    end

    subgraph "External Services"
        direction TB
        GoogleOAuth["Google OAuth2"]:::external
        GoogleClassroom["Google Classroom API"]:::external
        GoogleDrive["Google Drive API"]:::external
        GeminiService["Gemini AI API"]:::external
    end

    %% Connections
    %% Client to API
    HomePage -->|HTTP| AuthRoute
    LoginPage -->|HTTP| SignupRoute
    DashboardPage -->|REST| AnalyzeRoute
    DashboardPage -->|REST| CompareRoute
    DashboardPage -->|REST| CountRoute
    DashboardPage -->|REST| EvalClassroomRoute
    DashboardPage -->|REST| FetchRoute
    ClassroomPage -->|REST| FetchCourseWorkRoute
    CoursePage -->|REST| FetchCourseWorkDetailsRoute
    DashboardPage -->|REST| GetEvalsRoute
    DashboardPage -->|REST| SaveEvalRoute
    DashboardPage -->|REST| UpdateCountRoute

    %% API to Service
    AnalyzeRoute -->|"analyze() REST"| GeminiAPI
    CompareRoute -->|"compare() REST"| Utils
    EvalClassroomRoute -->|"evaluateClassroomSubmissions() REST"| ClassroomGemini
    AuthRoute -->|"NextAuth"| AuthOptions
    SignupRoute -->|"signup() REST"| AuthOptions

    %% Service to DB
    AuthOptions -->|"Mongoose"| UserModel
    Utils -->|"Mongoose"| AssignmentModel
    ClassroomGemini -->|"Mongoose"| EvalModel
    DBConn --> EvalModel
    DBConn --> AssignmentModel
    DBConn --> UserModel

    %% Service to External
    AuthOptions -->|"OAuth token exchange"| GoogleOAuth
    ClassroomGemini -->|"Classroom API calls"| GoogleClassroom
    ClassroomGemini -->|"Drive API calls"| GoogleDrive
    GeminiAPI -->|"analysis request"| GeminiService

    %% Click Events
    click Layout "https://github.com/harrypeter07/aievaluator/blob/main/app/layout.tsx"
    click HomePage "https://github.com/harrypeter07/aievaluator/blob/main/app/page.tsx"
    click LoginPage "https://github.com/harrypeter07/aievaluator/blob/main/app/login/page.jsx"
    click SignupPage "https://github.com/harrypeter07/aievaluator/blob/main/app/signup/page.jsx"
    click DashboardPage "https://github.com/harrypeter07/aievaluator/blob/main/app/dashboard/page.jsx"
    click ComparePage "https://github.com/harrypeter07/aievaluator/blob/main/app/dashboard/compare/page.jsx"
    click SinglePage "https://github.com/harrypeter07/aievaluator/blob/main/app/dashboard/single/page.jsx"
    click ClassroomPage "https://github.com/harrypeter07/aievaluator/blob/main/app/classroom/page.jsx"
    click CoursePage "https://github.com/harrypeter07/aievaluator/blob/main/app/classroom/[courseId]/page.jsx"
    click CourseWorkPage "https://github.com/harrypeter07/aievaluator/blob/main/app/classroom/[courseId]/[courseWorkId]/page.jsx"
    click AboutPage "https://github.com/harrypeter07/aievaluator/blob/main/app/about/page.jsx"
    click AuthRoute "https://github.com/harrypeter07/aievaluator/blob/main/app/api/auth/[...nextauth]/route.js"
    click SignupRoute "https://github.com/harrypeter07/aievaluator/blob/main/app/api/auth/signup/route.js"
    click AnalyzeRoute "https://github.com/harrypeter07/aievaluator/blob/main/app/api/assignments/analyze/route.js"
    click CompareRoute "https://github.com/harrypeter07/aievaluator/blob/main/app/api/assignments/compare/route.js"
    click CountRoute "https://github.com/harrypeter07/aievaluator/blob/main/app/api/assignments/count/route.js"
    click EvalClassroomRoute "https://github.com/harrypeter07/aievaluator/blob/main/app/api/assignments/evaluateClassroomSubmissions/route.js"
    click FetchRoute "https://github.com/harrypeter07/aievaluator/blob/main/app/api/assignments/fetch/route.js"
    click FetchCourseWorkRoute "https://github.com/harrypeter07/aievaluator/blob/main/app/api/assignments/fetchCourseWork/route.js"
    click FetchCourseWorkDetailsRoute "https://github.com/harrypeter07/aievaluator/blob/main/app/api/assignments/fetchCourseWorkDetails/route.js"
    click GetEvalsRoute "https://github.com/harrypeter07/aievaluator/blob/main/app/api/assignments/getEvaluations/route.js"
    click SaveEvalRoute "https://github.com/harrypeter07/aievaluator/blob/main/app/api/assignments/saveEvaluation/route.js"
    click UpdateCountRoute "https://github.com/harrypeter07/aievaluator/blob/main/app/api/assignments/updateCount/route.js"
    click AuthOptions "https://github.com/harrypeter07/aievaluator/blob/main/lib/authOptions.js"
    click ClassroomGemini "https://github.com/harrypeter07/aievaluator/blob/main/lib/classroomGemini.js"
    click GeminiAPI "https://github.com/harrypeter07/aievaluator/blob/main/lib/gemini.js"
    click CacheUtil "https://github.com/harrypeter07/aievaluator/blob/main/lib/cache.js"
    click RateLimit "https://github.com/harrypeter07/aievaluator/blob/main/lib/rateLimit.js"
    click Logger "https://github.com/harrypeter07/aievaluator/blob/main/lib/logger.js"
    click Utils "https://github.com/harrypeter07/aievaluator/blob/main/lib/utils.js"
    click DBConn "https://github.com/harrypeter07/aievaluator/blob/main/lib/db.js"
    click EvalModel "https://github.com/harrypeter07/aievaluator/blob/main/lib/models/Evaluation.js"
    click AssignmentModel "https://github.com/harrypeter07/aievaluator/blob/main/models/Assignment.js"
    click UserModel "https://github.com/harrypeter07/aievaluator/blob/main/models/User.js"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#3B82F6,color:#000
    classDef api fill:#D1FAE5,stroke:#10B981,color:#000
    classDef service fill:#FFEDD5,stroke:#FB923C,color:#000
    classDef db fill:#E5E7EB,stroke:#6B7280,color:#000
    classDef external fill:#EDE9FE,stroke:#8B5CF6,color:#000
```
