# oz841119/quiz-mint-ai architecture

> Architecture diagram of the GitHub repository oz841119/quiz-mint-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oz841119/quiz-mint-ai
- Repository: https://github.com/oz841119/quiz-mint-ai

## Overview

##### Project type and purpose
- Quiz Mint AI is a full-stack web application built with Next.js (App Router) and TypeScript.
- Purpose: provide a user interface to configure and generate quizzes using AI models (OpenAI-compatible or custom providers). It uses a single monolithic codebase to serve both client and server logic.

##### File structure
Top-level files and folders reveal key layers:
- Dockerfile, docker-compose.yml – containerization/development environment
- next.config.ts – Next.js build configuration
- src/app – Next.js App Router pages and API routes (UI + backend endpoints)
- src/AIService – domain layer handling AI-provider integration (OpenAI or custom)
- src/components – reusable React components (UI library, dialogs, sidebars, cards)
- src/configs – static lists (models, languages, quiz types)
- src/contexts – React Contexts for state management (exams, storage)
- src/hooks – custom React hooks (e.g., mobile detection)
- src/lib – utility modules and storage implementation (IndexedDB)
- Environment files (.env.local) – secrets and base URLs

##### Additional insights from README
- Describes development flow (Docker vs. npm dev server)
- Configuration of AI models and providers via src/configs/models.ts and AIService
- API route at src/app/api/generate-quiz/route.ts connects frontend requests to AIService

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Docker Container" 
    direction TB
    Dockerfile["Dockerfile"]:::infra
    DockerCompose["docker-compose.yml"]:::infra
  end

  subgraph "Client (Browser UI)" 
    direction TB
    subgraph "Next.js App Router Pages" 
      direction TB
      Layout["Root Layout & Global Styles"]:::ui
      Landing["Landing Page"]:::ui
      DashboardLayout["Dashboard Layout"]:::ui
      DashboardOverview["Dashboard Overview"]:::ui
      ExamLayout["Exam Layout"]:::ui
      ExamList["Exam List & Default Exam"]:::ui
      ExamDynLayout["Dynamic Exam Layout"]:::ui
      ExamDynPage["Dynamic Exam Page"]:::ui
      Layout --> Landing
      Layout --> DashboardLayout
      DashboardLayout --> DashboardOverview
      DashboardLayout --> ExamLayout
      ExamLayout --> ExamList
      ExamLayout --> ExamDynLayout
      ExamDynLayout --> ExamDynPage
    end

    subgraph "UI Components" 
      direction TB
      AddDialog["Add Exam Dialog"]:::ui
      Sidebar["Application Sidebar"]:::ui
      QuizCard["Quiz Card Display"]:::ui
      ExamMgr["Exam Manager Controls"]:::ui
      ModeSwitch["Exam Mode Switcher"]:::ui
      Collapser["Collapser Utility"]:::ui
      PingAnim["Ping Animation"]:::ui
      Logo["Logo Component"]:::ui
      Shadcn["shadcn-ui Primitives"]:::ui
    end

    subgraph "Context & Hooks" 
      direction TB
      ExamsCtx["Exams Context"]:::ui
      StorageCtx["Storage Context"]:::ui
      MobileHook["Mobile Detection Hook"]:::ui
    end

    subgraph "Client Storage & Utils" 
      direction TB
      IndexedDB["IndexedDB Storage"]:::storage
      StorageIndex["Storage Interface"]:::storage
      StorageTypes["Storage Types"]:::storage
      Utils["General Utilities"]:::storage
    end

    Landing -->|uses| AddDialog
    Landing -->|uses| Sidebar
    Landing -->|displays| QuizCard
    DashboardOverview -->|uses| ExamMgr
    DashboardOverview -->|toggles| ModeSwitch
    AddDialog -->|connects| ExamsCtx
    Sidebar -->|connects| ExamsCtx
    ExamMgr -->|connects| ExamsCtx
    StorageCtx -->|manages| IndexedDB
    StorageCtx --> StorageIndex
    StorageCtx --> StorageTypes
    IndexedDB --> Utils
  end

  subgraph "Server (Next.js Runtime)" 
    direction TB
    NextConfig["next.config.ts"]:::server
    API["generate-quiz API Route"]:::server
    AIService["AIService"]:::server
    Providers["Provider Definitions"]:::server
    Types["Provider Types"]:::server
    CreateOpenAI["createOpenAIProvider"]:::server
    AIUtils["AIService Utils"]:::server
    NextConfig --> API
    API -->|invokes| AIService
    AIService --> Providers
    AIService --> Types
    AIService --> AIUtils
    Providers --> CreateOpenAI
    CreateOpenAI -->|calls| ExternalAPI
  end

  ExternalAPI["External AI API"]:::external
  Browser["User Browser"]:::external

  Browser -->|HTTP Request| API
  Browser -->|Storage R/W| IndexedDB

  Dockerfile --> Layout
  DockerCompose --> Layout

  click Dockerfile "https://github.com/oz841119/quiz-mint-ai/tree/main/Dockerfile"
  click DockerCompose "https://github.com/oz841119/quiz-mint-ai/blob/main/docker-compose.yml"
  click NextConfig "https://github.com/oz841119/quiz-mint-ai/blob/main/next.config.ts"
  click API "https://github.com/oz841119/quiz-mint-ai/blob/main/src/app/api/generate-quiz/route.ts"
  click AIService "https://github.com/oz841119/quiz-mint-ai/blob/main/src/AIService/index.ts"
  click Providers "https://github.com/oz841119/quiz-mint-ai/blob/main/src/AIService/providers/index.ts"
  click Types "https://github.com/oz841119/quiz-mint-ai/blob/main/src/AIService/types.ts"
  click CreateOpenAI "https://github.com/oz841119/quiz-mint-ai/blob/main/src/AIService/utils/createOpenAIProvider.ts"
  click AIUtils "https://github.com/oz841119/quiz-mint-ai/blob/main/src/AIService/utils/index.ts"
  click Layout "https://github.com/oz841119/quiz-mint-ai/blob/main/src/app/layout.tsx"
  click Landing "https://github.com/oz841119/quiz-mint-ai/blob/main/src/app/page.tsx"
  click DashboardOverview "https://github.com/oz841119/quiz-mint-ai/blob/main/src/app/dashboard/page.tsx"
  click DashboardLayout "https://github.com/oz841119/quiz-mint-ai/blob/main/src/app/dashboard/layout.tsx"
  click ExamList "https://github.com/oz841119/quiz-mint-ai/blob/main/src/app/dashboard/exam/page.tsx"
  click ExamLayout "https://github.com/oz841119/quiz-mint-ai/blob/main/src/app/dashboard/exam/layout.tsx"
  click ExamDynPage "https://github.com/oz841119/quiz-mint-ai/blob/main/src/app/dashboard/exam/[examName]/page.tsx"
  click ExamDynLayout "https://github.com/oz841119/quiz-mint-ai/blob/main/src/app/dashboard/exam/[examName]/layout.tsx"
  click AddDialog "https://github.com/oz841119/quiz-mint-ai/blob/main/src/components/AddExamDialog/index.tsx"
  click Sidebar "https://github.com/oz841119/quiz-mint-ai/blob/main/src/components/AppSidebar/index.tsx"
  click QuizCard "https://github.com/oz841119/quiz-mint-ai/blob/main/src/components/QuizCard/index.tsx"
  click ExamMgr "https://github.com/oz841119/quiz-mint-ai/blob/main/src/components/ExamManager/index.tsx"
  click ModeSwitch "https://github.com/oz841119/quiz-mint-ai/blob/main/src/components/ExamModeSwitch/index.tsx"
  click Collapser "https://github.com/oz841119/quiz-mint-ai/blob/main/src/components/Collapser/index.tsx"
  click PingAnim "https://github.com/oz841119/quiz-mint-ai/blob/main/src/components/PingAnimation/index.tsx"
  click Logo "https://github.com/oz841119/quiz-mint-ai/blob/main/src/components/Logo.tsx"
  click Shadcn "https://github.com/oz841119/quiz-mint-ai/tree/main/src/components/shadcn-ui"
  click ExamsCtx "https://github.com/oz841119/quiz-mint-ai/blob/main/src/contexts/examsContext.tsx"
  click StorageCtx "https://github.com/oz841119/quiz-mint-ai/blob/main/src/contexts/storageContext.tsx"
  click MobileHook "https://github.com/oz841119/quiz-mint-ai/blob/main/src/hooks/use-mobile.ts"
  click IndexedDB "https://github.com/oz841119/quiz-mint-ai/blob/main/src/lib/storage/indexedDBStorage.ts"
  click StorageIndex "https://github.com/oz841119/quiz-mint-ai/blob/main/src/lib/storage/index.ts"
  click StorageTypes "https://github.com/oz841119/quiz-mint-ai/blob/main/src/lib/storage/types.ts"
  click Utils "https://github.com/oz841119/quiz-mint-ai/blob/main/src/lib/utils.ts"

  classDef ui fill:#D0E8FF,stroke:#0366D6,color:#0366D6
  classDef server fill:#DFFFE0,stroke:#237804,color:#237804
  classDef external fill:#FFEFD5,stroke:#FA8C16,color:#C75F00
  classDef storage fill:#F0F0F0,stroke:#8C8C8C,color:#595959
  classDef infra fill:#F5F5F5,stroke:#666666,color:#333333
  class Dockerfile,DockerCompose infra
  class Layout,Landing,DashboardOverview,DashboardLayout,ExamLayout,ExamList,ExamDynLayout,ExamDynPage,AddDialog,Sidebar,QuizCard,ExamMgr,ModeSwitch,Collapser,PingAnim,Logo,Shadcn,ExamsCtx,StorageCtx,MobileHook ui
  class IndexedDB,StorageIndex,StorageTypes,Utils storage
  class NextConfig,API,AIService,Providers,Types,CreateOpenAI,AIUtils server
  class ExternalAPI,Browser external
```
