# dokpami/frontend architecture

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

- Interactive diagram: https://gitdiagram.com/dokpami/frontend
- Repository: https://github.com/dokpami/frontend

## Overview

1. **Overall shape**
   - This is a client-side React + TypeScript app built with Vite.
   - The repository is organized as a single frontend SPA with multiple feature areas rather than a backend/service split.

2. **App bootstrapping and shell**
   - `src/main.tsx` is the entry point and mounts the React app.
   - `src/App.tsx`, `src/Layout.tsx`, and `src/Routers.tsx` form the top-level shell: app-wide layout plus client-side route definition.
   - Global styles come from `src/index.css` and the Slick carousel styles in `src/styles/`.

3. **Routing and page boundaries**
   - The app is divided into route-level pages under `src/pages/`.
   - Main routes appear to be:
     - `Landing`
     - `Home`
     - `Event`
     - `BalanceGame`
     - `QRTreasure`
     - `TestBE`
     - `NotFound`
   - This makes the architecture strongly page-driven, with each route owning its own subcomponents and local data flow.

4. **Landing/Home content layer**
   - `src/pages/Landing/` and `src/pages/Home/` look like the public-facing entry pages.
   - These pages likely provide navigation/intro content and funnel users into the interactive features.

5. **Event subsystem**
   - `src/pages/Event/` contains the event experience, with a `characters.ts` module suggesting the event is driven by character metadata.
   - Static character assets live in `public/characters/images` and `public/characters/names`, so the page is likely assembled from bundled metadata plus public media files.

6. **Balance Game subsystem**
   - `src/pages/BalanceGame/` is a self-contained interactive flow.
   - It is data-driven through `src/data/BalanceGameQuestions.tsx` and `src/data/BalanceGameResult.tsx`.
   - The UI is split into smaller pieces for choice buttons, result capture, result display, and QR output.
   - `src/pages/BalanceGame/api.ts` and `src/hooks/useBuyProduct.tsx` suggest the game may trigger an external API or commerce-related action as part of the experience.

7. **QR Treasure subsystem**
   - `src/pages/QRTreasure/` is another feature area with its own landing, result, admin, and container pages.
   - `_KakaoMap.tsx` indicates map-based interaction, likely for location discovery or treasure placement.
   - `_QRHeader.tsx` and `QRMapData.ts` imply a QR-centric flow backed by structured location/map data.
   - The separate `QRAdmin.tsx` page suggests an operational/admin boundary distinct from the end-user experience.

8. **Shared data model**
   - `src/data/LegacyData.tsx`, `QRMapData.ts`, and the Balance Game data modules act as the app’s content/data layer.
   - These modules likely centralize static configuration, mappings, and result definitions so the pages stay presentation-focused.

9. **Shared libraries and integrations**
   - `src/lib/firebase.ts` is the main backend integration point and likely encapsulates Firebase initialization/services.
   - `src/lib/share.ts` handles sharing behavior, and `src/lib/zksend.ts` suggests an external payment/transfer or wallet-related integration.
   - `src/lib/utils.ts` contains shared utility functions.

10. **Reusable UI and design system**
   - `src/components/ui/` contains reusable primitives such as accordion, dropdown menu, and toast/sonner.
   - The presence of `components.json` suggests a shadcn/ui-style component setup.
   - These components are shared across pages to keep interaction patterns consistent while feature pages remain isolated.

11. **External-facing infrastructure boundaries**
   - The most important external dependencies are Firebase, Kakao Map, and the zksend integration.
   - The app itself remains frontend-only, but several routes depend on remote services or externally hosted assets for dynamic behavior.

12. **Key architectural takeaway**
   - The repo is best diagrammed as a routed SPA with a thin global shell and four major feature domains: Landing/Home, Event, Balance Game, and QR Treasure.
   - Each feature owns its own components and data modules, while cross-cutting concerns are centralized in `lib/`, `hooks/`, and the shared UI layer.

Main entry points: [`src/Routers.tsx`](https://github.com/dokpami/frontend/blob/main/src/Routers.tsx) (Routers), [`src/pages/BalanceGame/BalanceGame.tsx`](https://github.com/dokpami/frontend/blob/main/src/pages/BalanceGame/BalanceGame.tsx) (Balance Game), [`src/pages/QRTreasure/QRTreasure.tsx`](https://github.com/dokpami/frontend/blob/main/src/pages/QRTreasure/QRTreasure.tsx) (QR Treasure), [`src/components/ui`](https://github.com/dokpami/frontend/tree/main/src/components/ui) (UI kit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App shell"]
  node_node_main["main<br/>entrypoint<br/>[main.tsx]"]
  node_node_app["App<br/>shell<br/>[App.tsx]"]
  node_node_layout["Layout<br/>[Layout.tsx]"]
  node_node_routers["Routers<br/>routing<br/>[Routers.tsx]"]
end

subgraph group_group_pages["Route pages"]
  node_node_landing["Landing<br/>public page<br/>[Landing.tsx]"]
  node_node_home["Home<br/>public page<br/>[Home.tsx]"]
  node_node_event["Event<br/>feature page<br/>[Event.tsx]"]
  node_node_balance["Balance Game<br/>feature page<br/>[BalanceGame.tsx]"]
  node_node_qr["QR Treasure<br/>feature page<br/>[QRTreasure.tsx]"]
  node_node_notfound["NotFound<br/>route fallback<br/>[NotFound.tsx]"]
  node_node_testbe["TestBE<br/>test page<br/>[TestBE.tsx]"]
  node_node_characters["Characters<br/>feature data<br/>[characters.ts]"]
end

subgraph group_group_shared["Shared layer"]
  node_node_balance_data["Game data<br/>content model"]
  node_node_legacy_data["Legacy data<br/>content model<br/>[LegacyData.tsx]"]
  node_node_qr_data["QR map data<br/>content model<br/>[QRMapData.ts]"]
  node_node_balance_hook["Buy hook<br/>[useBuyProduct.tsx]"]
  node_node_firebase["Firebase<br/>integration<br/>[firebase.ts]"]
  node_node_share["Share<br/>[share.ts]"]
  node_node_zksend["zksend<br/>integration<br/>[zksend.ts]"]
  node_node_ui["UI kit<br/>component library"]
end

subgraph group_group_assets["Public assets"]
  node_node_public_chars[("Char assets<br/>static assets")]
end

node_node_main -->|"boots"| node_node_app
node_node_app -->|"wraps"| node_node_layout
node_node_layout -->|"hosts"| node_node_routers
node_node_routers -->|"route"| node_node_landing
node_node_routers -->|"route"| node_node_home
node_node_routers -->|"route"| node_node_event
node_node_routers -->|"route"| node_node_balance
node_node_routers -->|"route"| node_node_qr
node_node_routers -->|"route"| node_node_testbe
node_node_routers -->|"fallback"| node_node_notfound
node_node_landing -->|"funnel"| node_node_home
node_node_event -->|"uses"| node_node_characters
node_node_event -->|"loads"| node_node_public_chars
node_node_balance -->|"drives"| node_node_balance_data
node_node_balance -->|"triggers"| node_node_balance_hook
node_node_balance -->|"syncs"| node_node_firebase
node_node_balance -->|"shares"| node_node_share
node_node_balance -->|"connects"| node_node_zksend
node_node_qr -->|"drives"| node_node_qr_data
node_node_qr -->|"syncs"| node_node_firebase
node_node_qr -->|"shares"| node_node_share
node_node_qr -->|"renders"| node_node_ui
node_node_home -->|"renders"| node_node_ui
node_node_landing -->|"renders"| node_node_ui
node_node_balance -->|"renders"| node_node_ui
node_node_event -->|"renders"| node_node_ui
node_node_qr -->|"renders"| node_node_ui
node_node_legacy_data -.->|"feeds"| node_node_event

click node_node_main "https://github.com/dokpami/frontend/blob/main/src/main.tsx"
click node_node_app "https://github.com/dokpami/frontend/blob/main/src/App.tsx"
click node_node_layout "https://github.com/dokpami/frontend/blob/main/src/Layout.tsx"
click node_node_routers "https://github.com/dokpami/frontend/blob/main/src/Routers.tsx"
click node_node_landing "https://github.com/dokpami/frontend/blob/main/src/pages/Landing/Landing.tsx"
click node_node_home "https://github.com/dokpami/frontend/blob/main/src/pages/Home/Home.tsx"
click node_node_event "https://github.com/dokpami/frontend/blob/main/src/pages/Event/Event.tsx"
click node_node_balance "https://github.com/dokpami/frontend/blob/main/src/pages/BalanceGame/BalanceGame.tsx"
click node_node_qr "https://github.com/dokpami/frontend/blob/main/src/pages/QRTreasure/QRTreasure.tsx"
click node_node_notfound "https://github.com/dokpami/frontend/blob/main/src/pages/NotFound.tsx"
click node_node_testbe "https://github.com/dokpami/frontend/blob/main/src/pages/TestBE.tsx"
click node_node_balance_data "https://github.com/dokpami/frontend/blob/main/src/data/BalanceGameQuestions.tsx"
click node_node_legacy_data "https://github.com/dokpami/frontend/blob/main/src/data/LegacyData.tsx"
click node_node_qr_data "https://github.com/dokpami/frontend/blob/main/src/data/QRMapData.ts"
click node_node_balance_hook "https://github.com/dokpami/frontend/blob/main/src/hooks/useBuyProduct.tsx"
click node_node_firebase "https://github.com/dokpami/frontend/blob/main/src/lib/firebase.ts"
click node_node_share "https://github.com/dokpami/frontend/blob/main/src/lib/share.ts"
click node_node_zksend "https://github.com/dokpami/frontend/blob/main/src/lib/zksend.ts"
click node_node_ui "https://github.com/dokpami/frontend/tree/main/src/components/ui"
click node_node_characters "https://github.com/dokpami/frontend/blob/main/src/pages/Event/characters.ts"
click node_node_public_chars "https://github.com/dokpami/frontend/tree/main/public/characters"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_main,node_node_app,node_node_layout,node_node_routers toneBlue
class node_node_landing,node_node_home,node_node_event,node_node_balance,node_node_qr,node_node_notfound,node_node_testbe,node_node_characters toneAmber
class node_node_balance_data,node_node_legacy_data,node_node_qr_data,node_node_balance_hook,node_node_firebase,node_node_share,node_node_zksend,node_node_ui toneMint
class node_node_public_chars toneRose
```

## Components

### App shell

Bootstrap, routing, and global layout for the SPA.

- [main](https://github.com/dokpami/frontend/blob/main/src/main.tsx): entrypoint · Vite entry that mounts the React app. · `src/main.tsx`
- [App](https://github.com/dokpami/frontend/blob/main/src/App.tsx): shell · Top-level application component. · `src/App.tsx`
- [Layout](https://github.com/dokpami/frontend/blob/main/src/Layout.tsx): layout · Global page chrome and shared structure. · `src/Layout.tsx`
- [Routers](https://github.com/dokpami/frontend/blob/main/src/Routers.tsx): routing · Client-side route definitions and page mapping. · `src/Routers.tsx`

### Route pages

Top-level route boundaries and feature areas.

- [Landing](https://github.com/dokpami/frontend/blob/main/src/pages/Landing/Landing.tsx): public page · Public entry page and introduction flow. · `src/pages/Landing/Landing.tsx`
- [Home](https://github.com/dokpami/frontend/blob/main/src/pages/Home/Home.tsx): public page · Primary landing/home experience after entry. · `src/pages/Home/Home.tsx`
- [Event](https://github.com/dokpami/frontend/blob/main/src/pages/Event/Event.tsx): feature page · Event experience driven by character metadata. · `src/pages/Event/Event.tsx`
- [Balance Game](https://github.com/dokpami/frontend/blob/main/src/pages/BalanceGame/BalanceGame.tsx): feature page · Interactive balance-game flow with result handling. · `src/pages/BalanceGame/BalanceGame.tsx`
- [QR Treasure](https://github.com/dokpami/frontend/blob/main/src/pages/QRTreasure/QRTreasure.tsx): feature page · QR treasure hunt experience and admin boundary. · `src/pages/QRTreasure/QRTreasure.tsx`
- [NotFound](https://github.com/dokpami/frontend/blob/main/src/pages/NotFound.tsx): route fallback · Fallback page for unknown routes. · `src/pages/NotFound.tsx`
- [TestBE](https://github.com/dokpami/frontend/blob/main/src/pages/TestBE.tsx): test page · Standalone page for backend or integration testing. · `src/pages/TestBE.tsx`
- [Characters](https://github.com/dokpami/frontend/blob/main/src/pages/Event/characters.ts): feature data · Character metadata used by the event page. · `src/pages/Event/characters.ts`

### Shared layer

Reusable data, hooks, UI primitives, and integrations.

- [Game data](https://github.com/dokpami/frontend/blob/main/src/data/BalanceGameQuestions.tsx): content model · Questions and result definitions for the balance game. · `src/data/BalanceGameQuestions.tsx`
- [Legacy data](https://github.com/dokpami/frontend/blob/main/src/data/LegacyData.tsx): content model · Shared legacy configuration and mappings. · `src/data/LegacyData.tsx`
- [QR map data](https://github.com/dokpami/frontend/blob/main/src/data/QRMapData.ts): content model · Structured location and map data for the QR flow. · `src/data/QRMapData.ts`
- [Buy hook](https://github.com/dokpami/frontend/blob/main/src/hooks/useBuyProduct.tsx): hook · Encapsulates product purchase or related game action. · `src/hooks/useBuyProduct.tsx`
- [Firebase](https://github.com/dokpami/frontend/blob/main/src/lib/firebase.ts): integration · App-wide Firebase initialization and service access. · `src/lib/firebase.ts`
- [Share](https://github.com/dokpami/frontend/blob/main/src/lib/share.ts): utility · Sharing behavior and platform-specific share helpers. · `src/lib/share.ts`
- [zksend](https://github.com/dokpami/frontend/blob/main/src/lib/zksend.ts): integration · External transfer or wallet-related integration. · `src/lib/zksend.ts`
- [UI kit](https://github.com/dokpami/frontend/tree/main/src/components/ui): component library · Reusable UI primitives shared across pages. · `src/components/ui`

### Public assets

Static media consumed by feature pages.

- [Char assets](https://github.com/dokpami/frontend/tree/main/public/characters): static assets · Character images and name assets served from public. · `public/characters`

## Connections

- main → App: boots · Application entry renders the root app.
- App → Layout: wraps · App shell composes the shared layout.
- Layout → Routers: hosts · Layout delegates page selection to the router.
- Routers → Landing: route · Routes to the landing page.
- Routers → Home: route · Routes to the home page.
- Routers → Event: route · Routes to the event experience.
- Routers → Balance Game: route · Routes to the balance game.
- Routers → QR Treasure: route · Routes to the QR treasure flow.
- Routers → TestBE: route · Routes to the test page.
- Routers → NotFound: fallback · Unknown routes fall back to not found.
- Landing → Home: funnel · Landing directs users into the main experience.
- Event → Characters: uses · Event page renders from character metadata.
- Event → Char assets: loads · Event page consumes public character assets.
- Balance Game → Game data: drives · Game flow is driven by questions and results.
- Balance Game → Buy hook: triggers · Interactive choices can invoke purchase/action logic.
- Balance Game → Firebase: syncs · Balance flow may persist or read remote state.
- Balance Game → Share: shares · Results can be shared externally.
- Balance Game → zksend: connects · Game flow may invoke wallet or transfer integration.
- QR Treasure → QR map data: drives · QR treasure flow is backed by map/location data.
- QR Treasure → Firebase: syncs · QR flow may use backend services.
- QR Treasure → Share: shares · QR results or invites can be shared.
- QR Treasure → UI kit: renders · Feature pages reuse shared UI primitives.
- Home → UI kit: renders · Home page composes shared components.
- Landing → UI kit: renders · Landing page composes shared components.
- Balance Game → UI kit: renders · Balance game composes shared components.
- Event → UI kit: renders · Event page composes shared components.
- QR Treasure → UI kit: renders · QR treasure page composes shared components.
- Legacy data → Event: feeds · Shared legacy data supports feature content.
