# moongchijang/moongchijang-fe architecture

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

- Interactive diagram: https://gitdiagram.com/moongchijang/moongchijang-fe
- Repository: https://github.com/moongchijang/moongchijang-fe

## Overview

1. **Repository purpose**
   - This is a Next.js 16 frontend for a group-buying service (“moongchijang”), built with React 19 and TypeScript.
   - The app is organized around consumer-facing flows such as browsing group buys, viewing item detail, joining a purchase, requesting a new group buy, logging in, and handling payment completion/failure.

2. **Top-level architectural shape**
   - The codebase is split into three main layers:
     - **App/routes** in `src/app` for pages and Route Handlers
     - **API contract layer** in `src/api` for generated clients, schemas, and mocks
     - **Shared UI/platform layer** in `src/components`, `src/hooks`, `src/lib`, and `src/providers`
   - This separation is important: the app UI does not directly own API shapes; those are generated and reused across page components and mock infrastructure.

3. **Route structure and page boundaries**
   - `src/app/(pages)` contains the user-facing screens, grouped by feature:
     - feed/favorites
     - item detail and join flow
     - login/email login
     - request flow
     - payment redirect/complete/fail
     - my page
   - The route-group layout `src/app/(pages)/(gnb)/layout.tsx` suggests a shared “global nav bar” shell for major logged-in/browsing pages.
   - Page-specific UI is kept inside each route’s `_components` directory, which keeps route boundaries clean and makes it easier to diagram page shells versus feature internals.

4. **Feature composition inside pages**
   - Most routes are built from small client components rather than monolithic page logic.
   - The feed page has its own search/filter/location UI, request cards, QR modal, and bottom sheets.
   - The item detail flow is split into detail display, share/toast, join UI, and payment-related interactions.
   - The request flow is a multi-step wizard with store search, map confirmation, request form, and completion state.
   - This means the architecture is highly feature-sliced: each page owns its local interaction model and presentation state.

5. **Shared design system and reusable widgets**
   - `src/components` contains reusable primitives and cross-page widgets such as Button, Input, BottomSheet, Toast, Tooltip, GNB, Header, Footer, and NaverMap.
   - Storybook stories live beside these components, indicating the design system is validated independently from app routes.
   - `src/styles/tokens.css` and Tailwind CSS v4 provide the shared visual language across the app.

6. **API client generation and schema layer**
   - `src/api/generated` contains Orval-generated fetch clients, type definitions, and MSW mock factories, split by backend domain: auth, group-buy, participation, wishlist, notification, owner, my-page, admin, pickup, and group-buy-request.
   - `src/api/zod` mirrors those domains with runtime validation schemas.
   - `src/api/hooks` wraps generated APIs into hook-friendly domain modules, so feature code consumes a stable interface rather than raw request functions.
   - `src/api/schemas` holds additional domain-specific schema definitions where needed.

7. **Runtime API mode switching**
   - The app supports three execution modes via `NEXT_PUBLIC_API_MODE`:
     - **mock**: local dev uses MSW + an Express mock server
     - **static**: the app serves Orval-generated static data through route handlers/static registry
     - **real**: requests go to the actual backend API
   - This is a major architectural boundary: the same frontend code can target mocked, static-demo, or live backend environments without changing feature components.

8. **Mocking and local development flow**
   - `mocks/` contains the MSW runtime setup, request handlers, faker utilities, and fixture JSON for group-buy lists and details.
   - `scripts/generate-msw-index.ts` and `scripts/generate-static-registry.ts` suggest the mock/static registries are derived from generated API assets, not hand-maintained.
   - In `dev:mock`, the Next.js app runs together with a mock server on `:9090`, so the frontend can be exercised against realistic responses without the backend.

9. **Server-side boundaries in `src/app/api`**
   - The app includes Route Handlers for selected backend-adjacent operations:
     - auth status
     - email login
     - group-buy participation creation
     - payment confirmation/failure
   - These routes act as a backend-for-frontend boundary for browser-triggered actions and payment callbacks, especially where redirects or server-side mediation are needed.

10. **State, data fetching, and client providers**
   - `src/providers/QueryProvider.tsx` indicates React Query-style client data management is centralized at the app level.
   - Feature hooks such as `useFeedList` and `useRecentSearches` encapsulate page state and data access.
   - Utilities in `src/lib` handle shared concerns like custom fetch behavior, token handling, redirects, date/phone formatting, validation, and a static registry.

11. **External services and integration points**
   - The app is clearly integrated with an external backend defined by Swagger and consumed through generated clients.
   - Naver Map is a notable UI integration, used in location-based feed and request flows.
   - Payment flows are explicit first-class flows, with redirect/complete/fail pages and server handlers for confirm/fail coordination.

12. **Quality, docs, and UI verification**
   - Storybook is a parallel UI validation surface for shared components and some feature widgets.
   - Vitest and Playwright are present for unit and end-to-end testing.
   - ESLint, Prettier, Husky, and lint-staged enforce code quality at commit time.
   - `docs/api-architecture.md` likely documents the API generation/runtime model in more detail, which is important because API handling is central to the repo’s architecture.

13. **Deployment and environment**
   - Deployment is configured for AWS Amplify via `amplify.yml`.
   - The environment variables in `.env.example` are architectural inputs, not just configuration: API mode, API base URL, and Swagger source directly influence how the frontend is built and where requests go.

Main entry points: [`src/api/generated`](https://github.com/moongchijang/moongchijang-fe/tree/develop/src/api/generated) (Generated API), [`src/api/hooks`](https://github.com/moongchijang/moongchijang-fe/tree/develop/src/api/hooks) (API hooks), [`src/app/api`](https://github.com/moongchijang/moongchijang-fe/tree/develop/src/app/api) (Route handlers), [`src/app/(pages)/(gnb)/layout.tsx`](https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/(gnb)/layout.tsx) (GNB shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App routes"]
  node_app_root["App shell<br/>next app<br/>[layout.tsx]"]
  node_app_pages_gnb["GNB shell<br/>route group<br/>[layout.tsx]"]
  node_app_feed["Feed<br/>page<br/>[page.tsx]"]
  node_app_favorite["Favorites<br/>page<br/>[page.tsx]"]
  node_app_item_detail["Item detail<br/>page<br/>[page.tsx]"]
  node_app_item_join["Join flow<br/>page<br/>[page.tsx]"]
  node_app_login["Login<br/>page<br/>[page.tsx]"]
  node_app_login_email["Email login<br/>page<br/>[page.tsx]"]
  node_app_request["Request flow<br/>page<br/>[page.tsx]"]
  node_app_pay_redirect["Payment redirect<br/>page<br/>[page.tsx]"]
  node_app_pay_complete["Payment complete<br/>page<br/>[page.tsx]"]
  node_app_pay_fail["Payment fail<br/>page<br/>[page.tsx]"]
  node_app_api_routes["Route handlers<br/>bff routes"]
end

subgraph group_group_api["API layer"]
  node_api_generated["Generated API<br/>orval clients"]
  node_api_hooks["API hooks<br/>domain hooks"]
  node_api_zod["Zod schemas<br/>validation"]
end

subgraph group_group_shared["Shared UI"]
  node_shared_components["UI kit<br/>components"]
  node_shared_provider["Query provider<br/>[QueryProvider.tsx]"]
  node_shared_lib["Shared lib<br/>utils"]
  node_shared_hooks["Client hooks<br/>ui hooks"]
end

subgraph group_group_runtime["Mock/runtime"]
  node_runtime_mock["Mock server<br/>msw runtime<br/>[dev-server.ts]"]
  node_runtime_registry["Static registry<br/>mode switching<br/>[static-registry.ts]"]
end

subgraph group_group_tooling["Tooling"]
  node_tool_storybook["Storybook<br/>ui docs<br/>[main.ts]"]
  node_tool_tests["Tests<br/>test config<br/>[vitest.config.ts]"]
  node_tool_docs["API docs"]
  node_tool_deploy["Deploy<br/>amplify<br/>[amplify.yml]"]
end

node_app_root -->|"wraps"| node_app_pages_gnb
node_app_pages_gnb -->|"hosts"| node_app_feed
node_app_pages_gnb -->|"hosts"| node_app_favorite
node_app_pages_gnb -->|"navigates"| node_app_item_detail
node_app_item_detail -->|"leads to"| node_app_item_join
node_app_login -->|"includes"| node_app_login_email
node_app_request -->|"submits via"| node_app_api_routes
node_app_item_join -->|"submits via"| node_app_api_routes
node_app_pay_redirect -->|"confirms via"| node_app_api_routes
node_app_pay_complete -->|"reads via"| node_app_api_routes
node_app_pay_fail -->|"reads via"| node_app_api_routes
node_app_feed -->|"fetches"| node_api_hooks
node_app_item_detail -->|"fetches"| node_api_hooks
node_app_login_email -->|"fetches"| node_api_hooks
node_app_request -->|"fetches"| node_api_hooks
node_api_hooks -->|"wraps"| node_api_generated
node_api_generated -->|"validates"| node_api_zod
node_shared_provider -->|"enables"| node_api_hooks
node_shared_lib -->|"supports"| node_api_generated
node_shared_lib -->|"loads"| node_runtime_registry
node_runtime_mock -->|"mocks"| node_api_generated
node_runtime_registry -->|"mirrors"| node_api_generated
node_tool_storybook -->|"validates"| node_shared_components
node_tool_tests -->|"checks"| node_shared_components
node_tool_docs -->|"documents"| node_api_generated
node_tool_deploy -->|"deploys"| node_app_root

click node_app_root "https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/layout.tsx"
click node_app_pages_gnb "https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/(gnb)/layout.tsx"
click node_app_feed "https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/(gnb)/feed/page.tsx"
click node_app_favorite "https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/(gnb)/favorite/page.tsx"
click node_app_item_detail "https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/item/[groupBuyId]/page.tsx"
click node_app_item_join "https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/item/[groupBuyId]/join/page.tsx"
click node_app_login "https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/login/page.tsx"
click node_app_login_email "https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/login/email/page.tsx"
click node_app_request "https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/request/page.tsx"
click node_app_pay_redirect "https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/payment/redirect/page.tsx"
click node_app_pay_complete "https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/payment/complete/page.tsx"
click node_app_pay_fail "https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/payment/fail/page.tsx"
click node_app_api_routes "https://github.com/moongchijang/moongchijang-fe/tree/develop/src/app/api"
click node_api_generated "https://github.com/moongchijang/moongchijang-fe/tree/develop/src/api/generated"
click node_api_hooks "https://github.com/moongchijang/moongchijang-fe/tree/develop/src/api/hooks"
click node_api_zod "https://github.com/moongchijang/moongchijang-fe/tree/develop/src/api/zod"
click node_shared_components "https://github.com/moongchijang/moongchijang-fe/tree/develop/src/components"
click node_shared_provider "https://github.com/moongchijang/moongchijang-fe/blob/develop/src/providers/QueryProvider.tsx"
click node_shared_lib "https://github.com/moongchijang/moongchijang-fe/tree/develop/src/lib"
click node_shared_hooks "https://github.com/moongchijang/moongchijang-fe/tree/develop/src/hooks"
click node_runtime_mock "https://github.com/moongchijang/moongchijang-fe/blob/develop/mocks/dev-server.ts"
click node_runtime_registry "https://github.com/moongchijang/moongchijang-fe/blob/develop/src/lib/static-registry.ts"
click node_tool_storybook "https://github.com/moongchijang/moongchijang-fe/blob/develop/.storybook/main.ts"
click node_tool_tests "https://github.com/moongchijang/moongchijang-fe/blob/develop/vitest.config.ts"
click node_tool_docs "https://github.com/moongchijang/moongchijang-fe/blob/develop/docs/api-architecture.md"
click node_tool_deploy "https://github.com/moongchijang/moongchijang-fe/blob/develop/amplify.yml"

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_app_root,node_app_pages_gnb,node_app_feed,node_app_favorite,node_app_item_detail,node_app_item_join,node_app_login,node_app_login_email,node_app_request,node_app_pay_redirect,node_app_pay_complete,node_app_pay_fail,node_app_api_routes toneBlue
class node_api_generated,node_api_hooks,node_api_zod toneAmber
class node_shared_components,node_shared_provider,node_shared_lib,node_shared_hooks toneMint
class node_runtime_mock,node_runtime_registry toneRose
class node_tool_storybook,node_tool_tests,node_tool_docs,node_tool_deploy toneIndigo
```

## Components

### App routes

Next.js pages, route groups, and server handlers.

- [App shell](https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/layout.tsx): next app · Root layout and entry surface for the frontend. · `src/app/layout.tsx`
- [GNB shell](https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/(gnb)/layout.tsx): route group · Shared navigation shell for primary browsing flows. · `src/app/(pages)/(gnb)/layout.tsx`
- [Feed](https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/(gnb)/feed/page.tsx): page · Browse and filter group-buy listings. · `src/app/(pages)/(gnb)/feed/page.tsx`
- [Favorites](https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/(gnb)/favorite/page.tsx): page · User wishlist and saved items view. · `src/app/(pages)/(gnb)/favorite/page.tsx`
- [Item detail](https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/item/[groupBuyId]/page.tsx): page · Group-buy detail, sharing, and join entrypoint. · `src/app/(pages)/item/[groupBuyId]/page.tsx`
- [Join flow](https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/item/[groupBuyId]/join/page.tsx): page · Purchase join form and payment initiation. · `src/app/(pages)/item/[groupBuyId]/join/page.tsx`
- [Login](https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/login/page.tsx): page · Login entry and email-based authentication. · `src/app/(pages)/login/page.tsx`
- [Email login](https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/login/email/page.tsx): page · Email login form and lookup flow. · `src/app/(pages)/login/email/page.tsx`
- [Request flow](https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/request/page.tsx): page · Multi-step group-buy request wizard. · `src/app/(pages)/request/page.tsx`
- [Payment redirect](https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/payment/redirect/page.tsx): page · Client-side payment callback handoff. · `src/app/(pages)/payment/redirect/page.tsx`
- [Payment complete](https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/payment/complete/page.tsx): page · Success confirmation after payment. · `src/app/(pages)/payment/complete/page.tsx`
- [Payment fail](https://github.com/moongchijang/moongchijang-fe/blob/develop/src/app/(pages)/payment/fail/page.tsx): page · Failure handling and retry surface. · `src/app/(pages)/payment/fail/page.tsx`
- [Route handlers](https://github.com/moongchijang/moongchijang-fe/tree/develop/src/app/api): bff routes · Backend-for-frontend endpoints for auth, participation, and payments. · `src/app/api`

### API layer

Generated clients, hooks, schemas, and runtime adapters.

- [Generated API](https://github.com/moongchijang/moongchijang-fe/tree/develop/src/api/generated): orval clients · Backend-domain clients and generated transport artifacts. · `src/api/generated`
- [API hooks](https://github.com/moongchijang/moongchijang-fe/tree/develop/src/api/hooks): domain hooks · Hook-friendly wrappers around generated clients. · `src/api/hooks`
- [Zod schemas](https://github.com/moongchijang/moongchijang-fe/tree/develop/src/api/zod): validation · Runtime schemas mirroring backend domains. · `src/api/zod`

### Shared UI

Reusable components, providers, hooks, and utilities.

- [UI kit](https://github.com/moongchijang/moongchijang-fe/tree/develop/src/components): components · Reusable primitives and cross-page widgets. · `src/components`
- [Query provider](https://github.com/moongchijang/moongchijang-fe/blob/develop/src/providers/QueryProvider.tsx): provider · App-wide client data and caching setup. · `src/providers/QueryProvider.tsx`
- [Shared lib](https://github.com/moongchijang/moongchijang-fe/tree/develop/src/lib): utils · Fetch, auth, formatting, redirect, and registry helpers. · `src/lib`
- [Client hooks](https://github.com/moongchijang/moongchijang-fe/tree/develop/src/hooks): ui hooks · Shared browser interaction hooks. · `src/hooks`

### Mock/runtime

Local API mode switching, mock server, and static registry support.

- [Mock server](https://github.com/moongchijang/moongchijang-fe/blob/develop/mocks/dev-server.ts): msw runtime · Local mocked backend runtime and fixtures. · `mocks/dev-server.ts`
- [Static registry](https://github.com/moongchijang/moongchijang-fe/blob/develop/src/lib/static-registry.ts): mode switching · Generated registry for static API mode. · `src/lib/static-registry.ts`

### Tooling

Stories, tests, docs, and build/deploy support.

- [Storybook](https://github.com/moongchijang/moongchijang-fe/blob/develop/.storybook/main.ts): ui docs · Component and page stories for visual validation. · `.storybook/main.ts`
- [Tests](https://github.com/moongchijang/moongchijang-fe/blob/develop/vitest.config.ts): test config · Vitest and Playwright-backed validation surface. · `vitest.config.ts`
- [API docs](https://github.com/moongchijang/moongchijang-fe/blob/develop/docs/api-architecture.md): docs · Architecture notes for API generation and runtime modes. · `docs/api-architecture.md`
- [Deploy](https://github.com/moongchijang/moongchijang-fe/blob/develop/amplify.yml): amplify · AWS Amplify deployment configuration. · `amplify.yml`

## Connections

- App shell → GNB shell: wraps · Root layout provides the main application shell.
- GNB shell → Feed: hosts · Shared nav shell wraps browsing pages.
- GNB shell → Favorites: hosts · Shared nav shell wraps browsing pages.
- GNB shell → Item detail: navigates · Browsing shell links into item detail.
- Item detail → Join flow: leads to · Detail page hands off to the join flow.
- Login → Email login: includes · Login surface offers email login path.
- Request flow → Route handlers: submits via · Wizard actions are mediated through server routes when needed.
- Join flow → Route handlers: submits via · Join and payment initiation rely on backend-for-frontend routes.
- Payment redirect → Route handlers: confirms via · Payment callback flow uses route handlers for mediation.
- Payment complete → Route handlers: reads via · Completion page consumes server-side payment state.
- Payment fail → Route handlers: reads via · Failure page consumes server-side payment state.
- Feed → API hooks: fetches · Feed uses domain hooks for list and search state.
- Item detail → API hooks: fetches · Detail and join surfaces consume domain hooks.
- Email login → API hooks: fetches · Email login uses auth-related hooks.
- Request flow → API hooks: fetches · Request wizard uses group-buy request hooks.
- API hooks → Generated API: wraps · Hooks adapt generated request clients into feature-friendly APIs.
- Generated API → Zod schemas: validates · Generated domain contracts are paired with runtime schemas.
- Query provider → API hooks: enables · Central query provider supports hook-based data fetching.
- Shared lib → Generated API: supports · Shared fetch and token helpers underpin API calls.
- Shared lib → Static registry: loads · Library layer provides the static API registry.
- Mock server → Generated API: mocks · Mock runtime serves generated mock handlers and fixtures.
- Static registry → Generated API: mirrors · Static mode reuses generated API artifacts.
- Storybook → UI kit: validates · Stories verify shared UI components independently.
- Tests → UI kit: checks · Unit and end-to-end tests cover component and flow behavior.
- API docs → Generated API: documents · Docs explain the generated API and runtime model.
- Deploy → App shell: deploys · Amplify serves the Next.js frontend.
