# emmy123222/tutor architecture

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

- Interactive diagram: https://gitdiagram.com/emmy123222/tutor
- Repository: https://github.com/emmy123222/tutor

## Overview

##### Project Type & Purpose
- **Type**: Full-stack, serverless web application
- **Purpose**: AI-powered educational platform that generates lessons, quizzes, flashcards, and PDFs using OpenAI

##### Main Components
a. **Client (Browser / Mobile)**
- React-based UI (Next.js pages & components)
- Pages: index.tsx (home/topic input), dashboard.tsx (results view)
- Components: LessonViewer, QuizComponent, Flashcard, SubjectInput
- Static assets & CSS (global.css, PrismJS)
b. **Frontend Framework**
- Next.js 14 with server-side rendering (SSR) & client-side hydration
- `_app.tsx` for global state & styles
c. **API Layer (Serverless Functions)**
- Next.js API routes under `pages/api/`:
- POST /generate-lessons
- POST /generate-quiz
- POST /generate-flashcards
- POST /export-pdf
- Each handler validates input, invokes backend utils, and returns JSON or PDF
d. **Backend Utilities**
- `backend/utils/ai.ts`: Wraps OpenAI GPT-3.5-turbo calls, builds & parses prompts
- `backend/utils/pdf.ts`: Uses pdf-lib to generate formatted PDF documents
e. **External Services**
- **OpenAI API**: Natural language generation
- (Optionally) Vercel Edge Network / CDN for static asset delivery
f. **Development Tooling**
- Kiro config & hooks (`.kiro/`):
- Auto-test-generation
- PDF & flashcard export hooks
- Jest for unit & integration tests
- CI/CD via Vercel (or alternative platforms)

##### Relationships & Data Flows
- User → Browser UI → Next.js frontend (React)
- Frontend → HTTP(S) → Next.js API route
- API route → Backend utils → External service (OpenAI)
- API route → pdf-lib → returns PDF stream
- API response → Frontend → Render or Trigger Download
- Kiro hooks & tests operate offline: interact with codebase but not runtime

##### Key Architectural Patterns
- **Serverless functions** for scaling API routes
- **Separation of concerns**: UI vs. API vs. AI logic vs. PDF logic
- **Stateless** API handlers (no persistent database)
- **Modular utilities** (ai.ts, pdf.ts) for single-responsibility
- **CI/CD automation** with Kiro and Vercel

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Path
    U["User"]:::external

    subgraph "Frontend (React/Next.js)"
        direction TB
        UI_Index["Home Page\nindex.tsx"]:::frontend
        UI_Dash["Dashboard Page\ndashboard.tsx"]:::frontend
        Comp_Subject["SubjectInput"]:::frontend
        Comp_Lesson["LessonViewer"]:::frontend
        Comp_Quiz["QuizComponent"]:::frontend
        Comp_Flash["Flashcard"]:::frontend
        Styles_CSS["global.css"]:::frontend
        Styles_Prism["prismjs.d.ts"]:::frontend
        AppEntry["_app.tsx"]:::frontend
        NextConfig["next.config.js"]:::frontend
        NextEnv["next-env.d.ts"]:::frontend
    end

    subgraph "Backend/API (Serverless)"
        direction TB
        API_GenLessons["POST /api/generate-lessons"]:::backend
        API_GenQuiz["POST /api/generate-quiz"]:::backend
        API_GenFlash["POST /api/generate-flashcards"]:::backend
        API_ExportPDF["POST /api/export-pdf"]:::backend
        Util_AI["OpenAI Wrapper\nai.ts"]:::backend
        Util_PDF["PDF Generator\npdf.ts"]:::backend
    end

    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::external
        CDN["CDN / Vercel Edge"]:::external
    end

    subgraph "Dev Tooling (Offline)"
        direction TB
        Kiro_Hook["auto-test-generation.hook.ts"]:::devtools
        Kiro_Settings[".kiro/settings"]:::devtools
        Kiro_Specs[".kiro/specs"]:::devtools
        Hooks_Flash["flashcardExport.hook.ts"]:::devtools
        Hooks_PDF["summarizeAndGeneratePDF.hook.ts"]:::devtools
        Jest_Config["jest.config.js"]:::devtools
        Jest_Setup["jest.setup.js"]:::devtools
        Env[".env.example"]:::devtools
    end

    %% Data Flows
    U -->|"interacts"| UI_Index
    UI_Index -->|uses| Comp_Subject
    UI_Index -->|"HTTP POST (JSON)"| API_GenLessons
    API_GenLessons -->|"calls"| Util_AI
    Util_AI -->|"REST API"| OpenAI
    OpenAI -->|"JSON response"| Util_AI
    Util_AI -->|"returns JSON"| API_GenLessons
    API_GenLessons -->|"JSON"| UI_Dash

    UI_Dash -->|"HTTP POST (JSON)"| API_GenQuiz
    API_GenQuiz -->|"calls"| Util_AI
    API_GenQuiz -->|"JSON"| UI_Dash

    UI_Dash -->|"HTTP POST (JSON)"| API_GenFlash
    API_GenFlash -->|"calls"| Util_AI
    API_GenFlash -->|"JSON"| UI_Dash

    UI_Dash -->|"Export PDF"| API_ExportPDF
    API_ExportPDF -->|"uses"| Util_PDF
    Util_PDF -->|"PDF stream"| API_ExportPDF
    API_ExportPDF -->|"PDF"| UI_Dash

    AppEntry -->|loads| UI_Index
    AppEntry -->|loads| UI_Dash
    AppEntry -->|applies styles| Styles_CSS
    AppEntry -->|applies types| Styles_Prism
    AppEntry -->|config| NextConfig
    AppEntry -->|env| NextEnv

    UI_Index -->|served via| CDN
    UI_Dash -->|served via| CDN

    %% Dev Tooling (not in runtime)
    Kiro_Hook -.-> Kiro_Settings
    Kiro_Specs -.-> Kiro_Hook
    Hooks_Flash -.-> Kiro_Hook
    Hooks_PDF -.-> Kiro_Hook
    Jest_Config -.-> Jest_Setup
    Env -.-> NextConfig

    %% Click Events
    click Comp_Subject "https://github.com/emmy123222/tutor/blob/main/frontend/components/SubjectInput.tsx"
    click Comp_Lesson "https://github.com/emmy123222/tutor/blob/main/frontend/components/LessonViewer.tsx"
    click Comp_Quiz "https://github.com/emmy123222/tutor/blob/main/frontend/components/QuizComponent.tsx"
    click Comp_Flash "https://github.com/emmy123222/tutor/blob/main/frontend/components/Flashcard.tsx"
    click UI_Index "https://github.com/emmy123222/tutor/blob/main/frontend/pages/index.tsx"
    click UI_Dash "https://github.com/emmy123222/tutor/blob/main/frontend/pages/dashboard.tsx"
    click Styles_CSS "https://github.com/emmy123222/tutor/blob/main/frontend/styles/global.css"
    click Styles_Prism "https://github.com/emmy123222/tutor/blob/main/frontend/styles/prismjs.d.ts"
    click AppEntry "https://github.com/emmy123222/tutor/blob/main/pages/_app.tsx"
    click NextConfig "https://github.com/emmy123222/tutor/blob/main/next.config.js"
    click NextEnv "https://github.com/emmy123222/tutor/blob/main/next-env.d.ts"
    click API_GenLessons "https://github.com/emmy123222/tutor/blob/main/pages/api/generate-lessons.ts"
    click API_GenQuiz "https://github.com/emmy123222/tutor/blob/main/pages/api/generate-quiz.ts"
    click API_GenFlash "https://github.com/emmy123222/tutor/blob/main/pages/api/generate-flashcards.ts"
    click API_ExportPDF "https://github.com/emmy123222/tutor/blob/main/pages/api/export-pdf.ts"
    click Util_AI "https://github.com/emmy123222/tutor/blob/main/backend/utils/ai.ts"
    click Util_PDF "https://github.com/emmy123222/tutor/blob/main/backend/utils/pdf.ts"
    click Kiro_Hook "https://github.com/emmy123222/tutor/blob/main/.kiro/hooks/auto-test-generation.hook.ts"
    click Kiro_Settings "https://github.com/emmy123222/tutor/tree/main/.kiro/settings"
    click Kiro_Specs "https://github.com/emmy123222/tutor/tree/main/.kiro/specs"
    click Hooks_Flash "https://github.com/emmy123222/tutor/blob/main/hooks/flashcardExport.hook.ts"
    click Hooks_PDF "https://github.com/emmy123222/tutor/blob/main/hooks/summarizeAndGeneratePDF.hook.ts"
    click Jest_Config "https://github.com/emmy123222/tutor/blob/main/jest.config.js"
    click Jest_Setup "https://github.com/emmy123222/tutor/blob/main/jest.setup.js"
    click Env "https://github.com/emmy123222/tutor/blob/main/.env.example"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#036b81,color:#000
    classDef backend fill:#e8f5e9,stroke:#2e7d32,color:#000
    classDef external fill:#fff9c4,stroke:#f9a825,color:#000
    classDef devtools fill:#eeeeee,stroke:#616161,stroke-dasharray: 5 5,color:#000
```
