How moongchijang/moongchijang-fe works
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: generated Generated API · hooks API hooks · api Route handlers · layout.tsx GNB shell
Components 26
App routes
Next.js pages, route groups, and server handlers.
- App shell · Root layout and entry surface for the frontend.
src/app/layout.tsx - GNB shell · Shared navigation shell for primary browsing flows.
src/app/(pages)/(gnb)/layout.tsx - Feed · Browse and filter group-buy listings.
src/app/(pages)/(gnb)/feed/page.tsx - Favorites · User wishlist and saved items view.
src/app/(pages)/(gnb)/favorite/page.tsx - Item detail · Group-buy detail, sharing, and join entrypoint.
src/app/(pages)/item/[groupBuyId]/page.tsx - Join flow · Purchase join form and payment initiation.
src/app/(pages)/item/[groupBuyId]/join/page.tsx - Login · Login entry and email-based authentication.
src/app/(pages)/login/page.tsx - Email login · Email login form and lookup flow.
src/app/(pages)/login/email/page.tsx - Request flow · Multi-step group-buy request wizard.
src/app/(pages)/request/page.tsx - Payment redirect · Client-side payment callback handoff.
src/app/(pages)/payment/redirect/page.tsx - Payment complete · Success confirmation after payment.
src/app/(pages)/payment/complete/page.tsx - Payment fail · Failure handling and retry surface.
src/app/(pages)/payment/fail/page.tsx - Route handlers · Backend-for-frontend endpoints for auth, participation, and payments.
src/app/api
API layer
Generated clients, hooks, schemas, and runtime adapters.
- Generated API · Backend-domain clients and generated transport artifacts.
src/api/generated - API hooks · Hook-friendly wrappers around generated clients.
src/api/hooks - Zod schemas · Runtime schemas mirroring backend domains.
src/api/zod
Shared UI
Reusable components, providers, hooks, and utilities.
- UI kit · Reusable primitives and cross-page widgets.
src/components - Query provider · App-wide client data and caching setup.
src/providers/QueryProvider.tsx - Shared lib · Fetch, auth, formatting, redirect, and registry helpers.
src/lib - Client hooks · Shared browser interaction hooks.
src/hooks
Mock/runtime
Local API mode switching, mock server, and static registry support.
- Mock server · Local mocked backend runtime and fixtures.
mocks/dev-server.ts - Static registry · Generated registry for static API mode.
src/lib/static-registry.ts
Tooling
Stories, tests, docs, and build/deploy support.
- Storybook · Component and page stories for visual validation.
.storybook/main.ts - Tests · Vitest and Playwright-backed validation surface.
vitest.config.ts - API docs · Architecture notes for API generation and runtime modes.
docs/api-architecture.md - Deploy · AWS Amplify deployment configuration.
amplify.yml
Connections 26
- 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.