# ankitsharma-at/teachmeai architecture

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

- Interactive diagram: https://gitdiagram.com/ankitsharma-at/teachmeai
- Repository: https://github.com/ankitsharma-at/teachmeai

## Overview

##### Project Type and Purpose
- TeachMe is a full-stack web application:
- Frontend: React + TypeScript SPA (Vite, Tailwind CSS)
- Backend: Node.js + Express API
- AI Integration: Gemini LLM for summarization and quiz generation
- Purpose: Allow users to upload PDFs, extract text, generate summaries and quizzes, and display results interactively.

##### File Structure
- Frontend/
- src/pages: Chat, Quiz, Scorecard, Upload flows
- src/components: UI building blocks (Navbar, PdfUploader, ChatSummary, MarkdownRenderer)
- src/hooks & context: state management (PDF context, chat logic, dark mode)
- src/services/api.ts: HTTP client to backend
- backend/
- src/server.js & index.js: Express application entry points
- src/routes: aiRoutes, chatRoutes, pdfRoutes, quizRoutes—maps HTTP endpoints
- src/services: business logic layers (chatService, pdfService, summaryService, quizService)
- src/utils: errorHandler, promptTemplates, resSplit – utilities and templates
- src/config/gemini.js: LLM client configuration

##### README Insights
- User → Frontend → PDF extraction → Backend → Gemini → summary/quiz → Frontend → User
- Technology stack and key features confirm core components and interactions.

a. Main Components
1. User (Web Browser)
2. Frontend SPA (React + Vite + Tailwind)
3. PDF Extraction Module (react-pdftotext in browser)
4. Backend API (Express)
5. AI Service (Gemini LLM)
6. Data Flow: Summary, Quiz Questions, User Answers, Feedback
b. Relationships & Data Flow
c. Architectural Patterns & Design Principles
- Layered Architecture:
- Presentation Layer (React components & pages)
- Application Layer (frontend services & hooks)
- API Layer (Express routes → controllers)
- Business Logic Layer (service modules: pdfService, chatService, quizService)
- Integration Layer (Gemini LLM client)
- Separation of Concerns: distinct folders for config, routes, services, utils
- Stateless RESTful API design
d. Key Technologies
- Frontend: React, TypeScript, Vite, Tailwind CSS, react-pdftotext, MARKDOWNRENDER
- Backend: Node.js, Express.js, Gemini LLM client
- Dev Tools: ESLint, PostCSS, Tailwind config

##### Detailed Capture of Architectural Elements
- Express route and the service it invokes
- Frontend page flow: Upload → Chat → Quiz → Scorecard
- Context providers and custom hooks managing state
- Config files (vite.config.ts, gemini.js) to indicate build & integration points

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User (Web Browser)"]:::external

    %% Frontend Layer
    subgraph "Frontend (React SPA)" 
        direction TB
        SPA["Frontend SPA"]:::frontend
        Pages["Pages"]:::frontend
        subgraph "Pages"
            direction TB
            Upload["Upload.tsx"]:::frontend
            ChatPage["Chat.tsx"]:::frontend
            QuizPage["Quiz.tsx"]:::frontend
            ScorecardPage["Scorecard.tsx"]:::frontend
        end
        Components["Components"]:::frontend
        subgraph "Components"
            direction TB
            Navbar["Navbar.tsx"]:::frontend
            PdfUploader["PdfUploader.tsx"]:::frontend
            ChatSummary["ChatSummary.tsx"]:::frontend
            MarkdownRenderer["MarkdownRenderer.tsx"]:::frontend
            ToggleButton["ToggleButton.tsx"]:::frontend
        end
        ServicesFE["API Service (api.ts)"]:::frontend
        Contexts["Context & Hooks"]:::frontend
        subgraph "Context & Hooks"
            direction TB
            PdfContext["PdfContext.tsx"]:::frontend
            ChatHook["useChat.ts"]:::frontend
            DarkModeHook["useDarkMode.ts"]:::frontend
        end
        ConfigFE["Config Files"]:::frontend
        subgraph "Config"
            direction TB
            ViteConfig["vite.config.ts"]:::frontend
            TailwindConfig["tailwind.config.js"]:::frontend
            PostCSSConfig["postcss.config.js"]:::frontend
        end
    end

    %% API Layer
    SPA -->|Uses| Pages
    Pages -->|Renders| Components
    Pages -->|Calls| ServicesFE
    Components -->|State| Contexts
    ServicesFE -->|HTTP| BackendAPI

    %% Backend Layer
    subgraph "Backend (Express API)" 
        direction TB
        Entry["server.js / index.js"]:::backend
        Routes["Routes"]:::backend
        subgraph "Routes"
            direction TB
            AiRoutes["aiRoutes.js"]:::backend
            ChatRoutes["chatRoutes.js"]:::backend
            PdfRoutes["pdfRoutes.js"]:::backend
            QuizRoutes["quizRoutes.js"]:::backend
        end
        ServicesBE["Services"]:::backend
        subgraph "Services"
            direction TB
            ChatService["chatService.js"]:::backend
            PdfService["pdfService.js"]:::backend
            SummaryService["summaryService.js"]:::backend
            QuizService["quizService.js"]:::backend
        end
        Utils["Utils"]:::backend
        subgraph "Utils"
            direction TB
            ErrorHandler["errorHandler.js"]:::backend
            PromptTemplates["promptTemplates.js"]:::backend
            ResSplit["resSplit.js"]:::backend
        end
        ConfigBE["gemini.js"]:::backend
    end

    %% External Services
    Gemini["Gemini LLM"]:::external

    %% Data Store Placeholder
    Cache["Cache/DB (future)"]:::datastore

    %% Connections
    User -->|Uploads PDF| Upload
    Upload -->|Select File| PdfUploader
    PdfUploader -->|Extract Text| ServicesFE
    ServicesFE -->|POST /api/pdf| PdfRoutes
    PdfRoutes -->|invoke| PdfService
    PdfService -->|calls| SummaryService
    SummaryService -->|request| Gemini
    Gemini -->|response| SummaryService
    SummaryService -->|data| PdfRoutes
    PdfRoutes -->|JSON summary| ServicesFE
    ServicesFE -->|data| ChatPage

    ChatPage -->|Ask Summary| ServicesFE
    ServicesFE -->|POST /api/chat| ChatRoutes
    ChatRoutes -->|invoke| ChatService
    ChatService -->|calls| Gemini
    Gemini -->|response| ChatService
    ChatService -->|data| ChatRoutes
    ChatRoutes -->|JSON chat| ServicesFE
    ServicesFE -->|data| ChatSummary

    QuizPage -->|Start Quiz| ServicesFE
    ServicesFE -->|POST /api/quiz| QuizRoutes
    QuizRoutes -->|invoke| QuizService
    QuizService -->|calls| Gemini
    Gemini -->|response| QuizService
    QuizService -->|data| QuizRoutes
    QuizRoutes -->|JSON quiz| ServicesFE
    ServicesFE -->|data| QuizPage

    ScorecardPage -->|View Results| ServicesFE
    ServicesFE -->|GET /api/score| AiRoutes
    AiRoutes -->|invoke| QuizService
    QuizService -->|data| AiRoutes
    AiRoutes -->|JSON score| ServicesFE
    ServicesFE -->|data| ScorecardPage

    %% Future Cache/DB Flow
    PdfService -->|store| Cache
    ChatService -->|store| Cache
    QuizService -->|store| Cache

    %% Click Events Frontend
    click SPA "https://github.com/ankitsharma-at/teachmeai/tree/master/Frontend/src"
    click PdfUploader "https://github.com/ankitsharma-at/teachmeai/blob/master/Frontend/src/components/PdfUploader.tsx"
    click ChatSummary "https://github.com/ankitsharma-at/teachmeai/blob/master/Frontend/src/components/ChatSummary.tsx"
    click MarkdownRenderer "https://github.com/ankitsharma-at/teachmeai/blob/master/Frontend/src/components/MarkdownRenderer.tsx"
    click Navbar "https://github.com/ankitsharma-at/teachmeai/blob/master/Frontend/src/components/Navbar.tsx"
    click ToggleButton "https://github.com/ankitsharma-at/teachmeai/blob/master/Frontend/src/components/ToggleButton.tsx"
    click Upload "https://github.com/ankitsharma-at/teachmeai/blob/master/Frontend/src/pages/Upload.tsx"
    click ChatPage "https://github.com/ankitsharma-at/teachmeai/blob/master/Frontend/src/pages/Chat.tsx"
    click QuizPage "https://github.com/ankitsharma-at/teachmeai/blob/master/Frontend/src/pages/Quiz.tsx"
    click ScorecardPage "https://github.com/ankitsharma-at/teachmeai/blob/master/Frontend/src/pages/Scorecard.tsx"
    click ServicesFE "https://github.com/ankitsharma-at/teachmeai/blob/master/Frontend/src/services/api.ts"
    click PdfContext "https://github.com/ankitsharma-at/teachmeai/blob/master/Frontend/src/context/PdfContext.tsx"
    click ChatHook "https://github.com/ankitsharma-at/teachmeai/blob/master/Frontend/src/hooks/useChat.ts"
    click DarkModeHook "https://github.com/ankitsharma-at/teachmeai/blob/master/Frontend/src/hooks/useDarkMode.ts"
    click ViteConfig "https://github.com/ankitsharma-at/teachmeai/blob/master/Frontend/vite.config.ts"
    click TailwindConfig "https://github.com/ankitsharma-at/teachmeai/blob/master/Frontend/tailwind.config.js"
    click PostCSSConfig "https://github.com/ankitsharma-at/teachmeai/blob/master/Frontend/postcss.config.js"

    %% Click Events Backend
    click Entry "https://github.com/ankitsharma-at/teachmeai/blob/master/backend/src/server.js"
    click ConfigBE "https://github.com/ankitsharma-at/teachmeai/blob/master/backend/src/config/gemini.js"
    click AiRoutes "https://github.com/ankitsharma-at/teachmeai/blob/master/backend/src/routes/aiRoutes.js"
    click ChatRoutes "https://github.com/ankitsharma-at/teachmeai/blob/master/backend/src/routes/chatRoutes.js"
    click PdfRoutes "https://github.com/ankitsharma-at/teachmeai/blob/master/backend/src/routes/pdfRoutes.js"
    click QuizRoutes "https://github.com/ankitsharma-at/teachmeai/blob/master/backend/src/routes/quizRoutes.js"
    click ChatService "https://github.com/ankitsharma-at/teachmeai/blob/master/backend/src/services/chatService.js"
    click PdfService "https://github.com/ankitsharma-at/teachmeai/blob/master/backend/src/services/pdfService.js"
    click SummaryService "https://github.com/ankitsharma-at/teachmeai/blob/master/backend/src/services/summaryService.js"
    click QuizService "https://github.com/ankitsharma-at/teachmeai/blob/master/backend/src/services/quizService.js"
    click ErrorHandler "https://github.com/ankitsharma-at/teachmeai/blob/master/backend/src/utils/errorHandler.js"
    click PromptTemplates "https://github.com/ankitsharma-at/teachmeai/blob/master/backend/src/utils/promptTemplates.js"
    click ResSplit "https://github.com/ankitsharma-at/teachmeai/blob/master/backend/src/utils/resSplit.js"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1
    classDef backend fill:#E8F6EF,stroke:#66BB6A,color:#2E7D32
    classDef external fill:#FFF3E0,stroke:#FFA726,color:#E65100
    classDef datastore fill:#E8F0FE,stroke:#5C6BC0,color:#1A237E
```
