# mju-likelion/mju-festival-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/mju-likelion/mju-festival-frontend
- Repository: https://github.com/mju-likelion/mju-festival-frontend

## Overview

##### Project Type and Purpose
- This is a front-end, single-page application (SPA) built with React (TypeScript) and Vite.
- It serves as the client for the “MJU Majesty” service, handling landing, authentication, booth QR‐code interactions, lost-and-found, timetable display, notices, and map viewing.
- The codebase is purely UI/UX and client-side logic; all persistent data and business-critical operations occur via RESTful HTTP calls to external/backend services.

##### File Structure Analysis
- Top-level: configuration (ESLint, Prettier, tsconfig, Vite), package.json, public (static assets & redirect rules), index.html.
- src/
- api/  Axios configuration + service modules (booth, lostItem, notice, postLogIn, setting, stamp, weather) → HTTP adapter layer.
- components/ Reusable UI widgets (FloatingButton, Footer, Header, QrBottomSheet, etc.).
- pages/  Feature pages organized per route (BoothList, CreateLostItem, LogIn, Main, Map, Stamp, TimeTable, etc.).
- hooks/  Custom React hooks encapsulating stateful logic (useBottomSheet, useDetermineRole, usePreventRefresh, useRouteTracker, useScreenSize).
- store/  Global state management (auth.ts) and store initialization.
- utils/  Helper modules (date formatting, encryption, error handling, download, openLink).
- styles/ Global styles, themes, fonts.
- types/ TypeScript interfaces for domain models (booth, lostItem, notice, timetable, auth).
- validation/ Validation schemas and messages.

##### Key Architectural Patterns
- “Feature-based” routing/pages.
- “Layered” structure: UI Components → Business Logic (hooks + store) → API Adapter → External Services.
- Centralized state (store/auth.ts) for authentication and likely role‐based routing.
- Separation of concerns: API interfaces isolated under src/api, domain types under src/types.

##### Main Components & Relationships
A. Client Browser
- Hosts the React SPA (index.html + bundled JS/CSS from Vite).
B. UI Layer
- Pages (React Router routes)
- Components (buttons, forms, layouts)
C. Business Logic Layer
- Hooks (custom logic, role determination)
- Store (global state, auth tokens)
D. API Adapter Layer
- Axios instance (src/api/Axios.ts)
- Service modules invoking endpoints (booth, lostItem, notice, stamp, weather, postLogIn, setting)
E. External/Backend Services
- Auth Service (login, token verification)
- Booth Service (QR issuance, booth CRUD)
- LostItem Service (create, edit, list, detail)
- Notice Service (create, edit, list, detail)
- Stamp Service (user stamp board)
- Weather API (external third-party weather data)
- API (external map tile service)
F. Static Assets & CDN
G. Build & Deployment
- Vite build → Bundler
- Hosting (Netlify/S3/Static host) + redirect rules (public/_redirects)

- Related modules in containers (e.g., “src/api”, “src/hooks + store”).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Browser
    subgraph "Client Browser"
        Browser["User Browser"]:::external
        Entry["SPA Entry (index.html + src/main.tsx)"]:::external
    end

    %% UI Layer
    subgraph "UI Layer"
        direction TB
        Pages["Pages (src/pages)"]:::ui
        Components["Components (src/components)"]:::ui
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        Hooks["Custom Hooks (src/hooks)"]:::logic
        Store["Global Store (src/store)"]:::logic
    end

    %% API Adapter Layer
    subgraph "API Adapter Layer"
        direction TB
        Axios["Axios Instance (src/api/Axios.ts)"]:::api
        Services["Service Modules (src/api)"]:::api
    end

    %% Types, Utils, Validation, Styles
    subgraph "Support Modules"
        direction TB
        Types["Domain Types (src/types)"]:::support
        Utils["Utilities (src/utils)"]:::support
        Validation["Validation (src/validation)"]:::support
        Styles["Styles & Themes (src/styles)"]:::support
    end

    %% Static Assets & CDN
    subgraph "Static Assets & CDN"
        Assets["Assets (src/assets)"]:::asset
        Redirects["Redirect Rules (public/_redirects)"]:::asset
    end

    %% External Services
    subgraph "External / Backend Services"
        AuthService["Auth Service"]:::ext
        BoothService["Booth Service"]:::ext
        LostService["LostItem Service"]:::ext
        NoticeService["Notice Service"]:::ext
        StampService["Stamp Service"]:::ext
        WeatherAPI["Weather API"]:::ext
        MapAPI["Map API"]:::ext
    end

    %% Build & Tooling
    subgraph "Build & Tooling"
        direction TB
        Vite["Vite Config (vite.config.ts, vite.config.dev.ts)"]:::tool
        TSConfig["TypeScript Configs (tsconfig*.json)"]:::tool
        Lint["ESLint/Prettier (.eslintrc.cjs, .prettierrc)"]:::tool
    end

    %% Data Flows
    Browser -->|"Loads SPA"| Entry
    Entry -->|"Render Routes"| Pages
    Entry -->|"Render UI"| Components
    Pages -->|"Use UI Widgets"| Components
    Pages -->|"Call Hooks & Store"| Hooks
    Components -->|"Call Hooks & Store"| Hooks
    Hooks -->|"Dispatch Actions / Read State"| Store
    Hooks -->|"Invoke HTTP"| Axios
    Store -->|"Attach Token / Config"| Axios
    Axios -->|"GET/POST etc."| Services
    Services -->|"HTTP Requests"| AuthService
    Services -->|"HTTP Requests"| BoothService
    Services -->|"HTTP Requests"| LostService
    Services -->|"HTTP Requests"| NoticeService
    Services -->|"HTTP Requests"| StampService
    Services -->|"HTTP Requests"| WeatherAPI
    Services -->|"HTTP Requests"| MapAPI
    Pages -->|"Load Icons & Images"| Assets

    Vite -->|"Bundle TS→JS"| Entry
    Vite --> BuildCompletion["Deploy Bundle"]:::tool
    BuildCompletion -->|"Hosted on CDN"| Assets
    BuildCompletion -->|"Hosted on Netlify/S3"| Browser

    %% Click Events
    click Entry "https://github.com/mju-likelion/mju-festival-frontend/blob/main/index.html"
    click Entry "https://github.com/mju-likelion/mju-festival-frontend/blob/main/src/main.tsx"
    click Pages "https://github.com/mju-likelion/mju-festival-frontend/tree/main/src/pages"
    click Components "https://github.com/mju-likelion/mju-festival-frontend/tree/main/src/components"
    click Hooks "https://github.com/mju-likelion/mju-festival-frontend/tree/main/src/hooks"
    click Store "https://github.com/mju-likelion/mju-festival-frontend/tree/main/src/store"
    click Axios "https://github.com/mju-likelion/mju-festival-frontend/blob/main/src/api/Axios.ts"
    click Services "https://github.com/mju-likelion/mju-festival-frontend/tree/main/src/api"
    click Types "https://github.com/mju-likelion/mju-festival-frontend/tree/main/src/types"
    click Utils "https://github.com/mju-likelion/mju-festival-frontend/tree/main/src/utils"
    click Validation "https://github.com/mju-likelion/mju-festival-frontend/tree/main/src/validation"
    click Styles "https://github.com/mju-likelion/mju-festival-frontend/tree/main/src/styles"
    click Assets "https://github.com/mju-likelion/mju-festival-frontend/tree/main/src/assets"
    click Redirects "https://github.com/mju-likelion/mju-festival-frontend/tree/main/public/_redirects"
    click Vite "https://github.com/mju-likelion/mju-festival-frontend/blob/main/vite.config.ts"
    click Vite "https://github.com/mju-likelion/mju-festival-frontend/blob/main/vite.config.dev.ts"
    click TSConfig "https://github.com/mju-likelion/mju-festival-frontend/blob/main/tsconfig.json"
    click TSConfig "https://github.com/mju-likelion/mju-festival-frontend/blob/main/tsconfig.app.json"
    click Lint "https://github.com/mju-likelion/mju-festival-frontend/blob/main/.eslintrc.cjs"
    click Lint "https://github.com/mju-likelion/mju-festival-frontend/blob/main/.prettierrc"

    %% Styles
    classDef ui fill:#e0f7fa,stroke:#006064,color:#006064
    classDef logic fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
    classDef api fill:#fff3e0,stroke:#ef6c00,color:#ef6c00
    classDef ext fill:#ffebee,stroke:#c62828,color:#c62828
    classDef asset fill:#eceff1,stroke:#455a64,color:#455a64
    classDef support fill:#f3e5f5,stroke:#6a1b9a,color:#6a1b9a
    classDef tool fill:#eeeeee,stroke:#424242,color:#424242
    classDef external fill:#ffffff,stroke:#000000,color:#000000
```
