# theleejungyan/mathquiz architecture

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

- Interactive diagram: https://gitdiagram.com/theleejungyan/mathquiz
- Repository: https://github.com/theleejungyan/mathquiz

## Overview

##### Project type and purpose
- This is a front-end single-page application (SPA) built with React and TypeScript.
- Purpose: present multiple-choice math questions (from a local JSON file), let users answer them, and display a score summary.
- Deployed on Vercel; uses Vite as its build tool.

##### File structure
- Top‐level config/build files:
– package.json / package-lock.json (dependencies, scripts)
– vite.config.ts (Vite build config)
– tailwind.config.js / postcss.config.js (styling setup)
– tsconfig*.json (TypeScript settings)
– vercel.json (deployment settings)
- Public assets:
– public/ (favicon, static files)
- Source code in src/:
– src/main.tsx: app entry point (mounts React)
– src/router.tsx: React Router setup (routes → HomePage, Quiz)
– src/pages/: page components (HomePage.tsx, Quiz.tsx)
– src/components/: UI‐level atoms/molecules (DialogBox, Button, ProgressBar, etc.)
– src/components/ui/: headless UI primitives (input, label, alert-dialog)
– src/global/: shared types (dataType.ts, type.ts)
– src/hook/: custom hooks (useIdentifyChange)
– src/lib/: utility functions (utils.ts)
– src/json/quiz.json: the quiz questions data store
– src/assets, src/images, src/fonts, src/css: static assets and styles

##### README for additional insights
- Confirms that quiz.json is the source of questions, and dataType.ts defines the structure.
- Technologies: React, TypeScript, Vercel.

##### Main components and their interactions
a. User’s Browser (Client)
b. React Application
– Entry point: main.tsx
– Router: defines the navigation between HomePage and Quiz pages
– Pages: fetch/ load data, manage high-level state per route
– Components: present UI, dialogs, progress bar, with UI primitives under components/ui
– Hooks & Utils: useIdentifyChange manages state transitions (e.g. current question), utils.ts has helper functions (e.g. shuffle questions)
– Data Layer: quiz.json is read (imported) at build time or fetched at runtime
– Styles: Tailwind CSS + custom CSS (src/css/quiz.css, index.css)
c. Build & Deployment
– Vite: development server and bundler (build pipeline)
– Vercel: hosting platform that serves the static build output

Relationships & data flow:
1. On load, Browser → index.html → main.tsx mounts React app
2. Router reads URL → renders HomePage or Quiz page
3. Quiz page loads quiz.json (via import/fetch) → state initialized (global types)
4. User interactions in Components → triggers Hooks & Utils → updates React state
5. React re-renders components showing next question / score dialog → user sees results
6. Build pipeline (Vite) bundles code + assets → deployed to Vercel → served to users

##### Architectural patterns & design principles
- Component-based decomposition (atoms → molecules → pages)
- Single source of truth for question data (quiz.json + TypeScript types)
- Unidirectional data flow (React state → UI)
- Separation of concerns: UI primitives, business logic (utils/hooks), data types

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["Browser / index.html"]:::frontend
    click Browser "https://github.com/theleejungyan/mathquiz/blob/main/index.html"

    App["React App (main.tsx)"]:::frontend
    click App "https://github.com/theleejungyan/mathquiz/blob/main/src/main.tsx"
    
    Browser -->|"loads"| App

    Router["Router (src/router.tsx)"]:::frontend
    click Router "https://github.com/theleejungyan/mathquiz/blob/main/src/router.tsx"
    App --> Router

    subgraph "Pages"
        Home["HomePage"]:::frontend
        click Home "https://github.com/theleejungyan/mathquiz/blob/main/src/pages/HomePage.tsx"
        Quiz["Quiz Page"]:::frontend
        click Quiz "https://github.com/theleejungyan/mathquiz/blob/main/src/pages/Quiz.tsx"
    end
    Router -->|"route to"| Home
    Router -->|"route to"| Quiz

    subgraph "UI Components"
        DBox["DialogBox"]:::component
        click DBox "https://github.com/theleejungyan/mathquiz/blob/main/src/components/DialogBox.tsx"
        ExitD["ExitDialog"]:::component
        click ExitD "https://github.com/theleejungyan/mathquiz/blob/main/src/components/ExitDialog.tsx"
        RegD["RegisterDialog"]:::component
        click RegD "https://github.com/theleejungyan/mathquiz/blob/main/src/components/RegisterDialog.tsx"
        ScoreD["ScoreDialog"]:::component
        click ScoreD "https://github.com/theleejungyan/mathquiz/blob/main/src/components/ScoreDialog.tsx"
        Header["Header"]:::component
        click Header "https://github.com/theleejungyan/mathquiz/blob/main/src/components/Header.tsx"
        Footer["Footer"]:::component
        click Footer "https://github.com/theleejungyan/mathquiz/blob/main/src/components/Footer.tsx"
        Layout["Layout"]:::component
        click Layout "https://github.com/theleejungyan/mathquiz/blob/main/src/components/Layout.tsx"
        Option["Option"]:::component
        click Option "https://github.com/theleejungyan/mathquiz/blob/main/src/components/Option.tsx"
        PBar["ProgressBar"]:::component
        click PBar "https://github.com/theleejungyan/mathquiz/blob/main/src/components/ProgressBar.tsx"
        Robot["Robot"]:::component
        click Robot "https://github.com/theleejungyan/mathquiz/blob/main/src/components/Robot.tsx"
    end

    subgraph "UI Primitives"
        Alert["AlertDialog"]:::primitive
        click Alert "https://github.com/theleejungyan/mathquiz/blob/main/src/components/ui/alert-dialog.tsx"
        Btn["Button"]:::primitive
        click Btn "https://github.com/theleejungyan/mathquiz/blob/main/src/components/ui/button.tsx"
        Dialog["Dialog"]:::primitive
        click Dialog "https://github.com/theleejungyan/mathquiz/blob/main/src/components/ui/dialog.tsx"
        Input["Input"]:::primitive
        click Input "https://github.com/theleejungyan/mathquiz/blob/main/src/components/ui/input.tsx"
        Label["Label"]:::primitive
        click Label "https://github.com/theleejungyan/mathquiz/blob/main/src/components/ui/label.tsx"
    end

    Home --> Layout
    Quiz --> Layout
    Layout --> Header
    Layout --> Footer

    Quiz --> Option
    Quiz --> PBar
    Quiz --> DBox
    DBox --> ExitD
    DBox --> RegD
    DBox --> ScoreD

    subgraph "Logic"
        Hooks["useIdentifyChange"]:::util
        click Hooks "https://github.com/theleejungyan/mathquiz/blob/main/src/hook/useIdentifyChange.tsx"
        Utils["utils.ts"]:::util
        click Utils "https://github.com/theleejungyan/mathquiz/blob/main/src/lib/utils.ts"
    end

    Quiz --> Hooks
    Quiz --> Utils

    subgraph "Data Layer"
        JSON["quiz.json"]:::data
        click JSON "https://github.com/theleejungyan/mathquiz/blob/main/src/json/quiz.json"
        DT1["dataType.ts"]:::data
        click DT1 "https://github.com/theleejungyan/mathquiz/blob/main/src/global/dataType.ts"
        DT2["type.ts"]:::data
        click DT2 "https://github.com/theleejungyan/mathquiz/blob/main/src/global/type.ts"
    end

    Utils --> JSON
    Quiz --> JSON
    Quiz --> DT1
    Quiz --> DT2

    subgraph "Styles & Assets"
        TConfig["tailwind.config.js"]:::config
        click TConfig "https://github.com/theleejungyan/mathquiz/blob/main/tailwind.config.js"
        PConfig["postcss.config.js"]:::config
        click PConfig "https://github.com/theleejungyan/mathquiz/blob/main/postcss.config.js"
        GCSS["Global CSS (index.css)"]:::config
        click GCSS "https://github.com/theleejungyan/mathquiz/blob/main/src/index.css"
        QCSS["Quiz CSS (src/css/quiz.css)"]:::config
        click QCSS "https://github.com/theleejungyan/mathquiz/blob/main/src/css/quiz.css"
        Fonts["Fonts (src/fonts/Montserrat)"]:::config
        click Fonts "https://github.com/theleejungyan/mathquiz/tree/main/src/fonts/Montserrat"
        Assets["Images & Assets"]:::config
        click Assets "https://github.com/theleejungyan/mathquiz/tree/main/src/assets"
    end

    App --> GCSS
    App --> QCSS
    App --> Fonts
    App --> Assets

    subgraph "Build & Deployment"
        Vite["Vite (vite.config.ts)"]:::deploy
        click Vite "https://github.com/theleejungyan/mathquiz/blob/main/vite.config.ts"
        TS1["tsconfig.json"]:::deploy
        click TS1 "https://github.com/theleejungyan/mathquiz/blob/main/tsconfig.json"
        TS2["tsconfig.app.json"]:::deploy
        click TS2 "https://github.com/theleejungyan/mathquiz/blob/main/tsconfig.app.json"
        TS3["tsconfig.node.json"]:::deploy
        click TS3 "https://github.com/theleejungyan/mathquiz/blob/main/tsconfig.node.json"
        Vercel["Vercel (vercel.json)"]:::deploy
        click Vercel "https://github.com/theleejungyan/mathquiz/blob/main/vercel.json"
        Build[/"Static Build"/]:::deploy
    end

    App --> Vite
    Vite -->|"bundles"| Build
    Build --> Vercel
    Vercel --> Browser

    classDef frontend fill:#D6EAF8,stroke:#21618C,color:#1B4F72
    classDef component fill:#D1F2EB,stroke:#0E6251,color:#145A32
    classDef primitive fill:#FCF3CF,stroke:#B7950B,color:#7D6608
    classDef util fill:#FADBD8,stroke:#C0392B,color:#78281F
    classDef data fill:#E8DAEF,stroke:#6C3483,color:#4A235A
    classDef config fill:#F5B7B1,stroke:#AF601A,color:#784212
    classDef deploy fill:#ABEBC6,stroke:#196F3D,color:#145A32
```
