# dharshan2208/examgenius architecture

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

- Interactive diagram: https://gitdiagram.com/dharshan2208/examgenius
- Repository: https://github.com/dharshan2208/examgenius

## Overview

##### Project Type & Purpose
- ExamGenius is a full-stack web application designed for assisting students in exam preparation through automatic syllabus analysis, resource curation, and personalized study plan generation.
- The system uses AI integrations (Gemini, Tavily, Langchain) to analyze documents and provide recommendations.
- The frontend is built with React/TypeScript and the backend with FastAPI (Python), containerized using Docker and Docker Compose.

##### Analyzing the File Structure
- The file tree shows distinct folders for “backend” and “frontend”, indicating a clear separation of concerns.
- In the backend, look at the “app/api/routes” which holds various endpoints (exam papers, study plans, syllabus, and resources). This layers the API controller part of the architecture.
- The “services” directory includes key files like gemini_service.py, langchain_service.py, and study_plan_generator.py, which encapsulate business logic and interactions with external APIs.
- The “models” directory holds domain entities (exam paper, study plan, syllabus, etc.) and illustrates the data aspect of the application.
- The frontend contains a typical React/Vite application structure with components (UI features, layout), context, hooks, and pages for different functionalities.

a. Main Components:
- Frontend Application:
- Built with React & TypeScript.
- Contains UI components, routing (React Router), theme (Material UI), and context/hook layers.
- Acts as the presentation layer from which users interact with the system.
- Backend API Server:
- Built using FastAPI.
- API Routes: Endpoints for exam papers, study plans, syllabus processing, resources.
- Core Business Logic: Organized into “services” (Gemini, Tavily, Langchain, study plan generator) and “utils” (file processing, Pareto analysis, etc.).
- Models and Config: Represent the domain and configuration for the application (security, config settings).
- External AI Services:
- Gemini API and Tavily API are integrated via the backend services.
- Containerization:
- Dockerfiles for both frontend and backend.
- Docker Compose configuration that orchestrates the multi-container setup.

b. Relationships & Interactions:
- The Frontend communicates with the Backend API over HTTP(s) (via defined endpoints).
- The Backend API routes delegate tasks to various services (e.g., language processing, resource curation).
- Business logic modules in the services layer invoke external APIs (Gemini, Tavily) and use utility functions for processing.
- The containerization layer (Docker/Docker Compose) coordinates starting both parts and linking them in a network.

##### Architectural Patterns & Key Technologies
- MVC / API Controller Pattern: Clear separation between API routes (controllers), models (domain entities), and services (business logic).
- Containerized Deployment: Both frontend and backend are built into separate Docker images and managed with Docker Compose.
- Microservice-Like Service Layer: Even though contained in one backend, the separation of services (Gemini, Langchain, etc.) hints at loosely-coupled functionalities.
- Use of modern web technologies such as Vite for frontend bundling and FastAPI (with Uvicorn) for async backend processing.

- Under the Backend section, subdivide it into:
- API Routes: Represent routes like exam papers, study plans, etc.
- Service Layer: Represent Gemini Service, Langchain Service, Resource Curation, and Study Plan Generator.
- Utility Module: Include supportive roles such as file processing and outline any core configurations (security, config).
- Docker and Docker Compose as an encompassing layer managing both the frontend and backend deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::user

    subgraph "Frontend Application"
        FE["React/TypeScript App"]:::frontend
    end

    subgraph "Backend API Server"
        BS["Backend Server"]:::backend
        subgraph "API & Business Layers"
            APIRoutes["API Routes (exam_papers,resources,study_plans,syllabus)"]:::api
            ServiceLayer["Service Layer (Gemini,Tavily,Langchain,StudyPlanGen,ResourceCuration)"]:::service
            Models["Models (Domain Entities)"]:::models
            Utils["Utility Modules (FileProcessing,ParetoAnalyzer)"]:::utils
        end
    end

    subgraph "External AI Services"
        Gemini["Gemini API"]:::external
        Tavily["Tavily API"]:::external
    end

    subgraph "Containerization / Deployment"
        BackendDocker["Backend Dockerfile"]:::container
        FrontendDocker["Frontend Dockerfile"]:::container
        Compose["Docker Compose"]:::container
    end

    User -->|"Interacts"| FE
    FE -->|"HTTP_Request"| BS
    BS -->|"Forwards"| APIRoutes
    BS -->|"ExecutesLogic"| ServiceLayer
    BS -->|"UsesModels"| Models
    BS -->|"UtilizesUtils"| Utils
    APIRoutes -->|"Delegates"| ServiceLayer
    APIRoutes -->|"MapsTo"| Models
    ServiceLayer -->|"Calls"| Gemini
    ServiceLayer -->|"Calls"| Tavily
    Compose -->|"Deploys"| FE
    Compose -->|"Deploys"| BS
    Compose -->|"Contains"| BackendDocker
    Compose -->|"Contains"| FrontendDocker

    click FE "https://github.com/dharshan2208/examgenius/tree/main/frontend/"
    click BS "https://github.com/dharshan2208/examgenius/blob/main/backend/app/main.py"
    click APIRoutes "https://github.com/dharshan2208/examgenius/tree/main/backend/app/api/routes/"
    click ServiceLayer "https://github.com/dharshan2208/examgenius/tree/main/backend/app/services/"
    click Models "https://github.com/dharshan2208/examgenius/tree/main/backend/app/models/"
    click Utils "https://github.com/dharshan2208/examgenius/tree/main/backend/app/utils/"
    click BackendDocker "https://github.com/dharshan2208/examgenius/tree/main/backend/Dockerfile"
    click FrontendDocker "https://github.com/dharshan2208/examgenius/tree/main/frontend/Dockerfile"
    click Compose "https://github.com/dharshan2208/examgenius/blob/main/docker-compose.yml"

    classDef user fill:#FAD7A0,stroke:#000,stroke-width:1px;
    classDef frontend fill:#AED6F1,stroke:#000,stroke-width:1px;
    classDef backend fill:#A9DFBF,stroke:#000,stroke-width:1px;
    classDef api fill:#F9E79F,stroke:#000,stroke-width:1px;
    classDef service fill:#D7BDE2,stroke:#000,stroke-width:1px;
    classDef models fill:#F5B7B1,stroke:#000,stroke-width:1px;
    classDef utils fill:#D5F5E3,stroke:#000,stroke-width:1px;
    classDef external fill:#FADBD8,stroke:#000,stroke-width:1px;
    classDef container fill:#D6EAF8,stroke:#000,stroke-width:1px;
```
