frontend/app/APP.md

App Routes & Pages Documentation

Tài liệu chi tiết về Next.js App Router structure, routes, và layouts

---

Route Structure Overview

app/
├── layout.tsx                  # Root layout - Header + Footer wrapper
├── globals.css                 # CSS tokens + Tailwind imports
├── providers.tsx               # Context providers (Auth, Menu, Cart)
├── (main)/
│   ├── layout.tsx             # Main layout for authenticated routes
│   ├── page.tsx               # Main page - Duyệt thực đơn (/)
│   ├── login/
│   │   └── page.tsx           # Trang đăng nhập (/login)
│   ├── register/
│   │   └── page.tsx           # Trang đăng ký (/register)
│   └── payment/
│       └── page.tsx           # Trang thanh toán (/payment)
├── (feed)/
│   ├── layout.tsx             # Feed layout
│   └── feed/
│       └── page.tsx           # Trang khám phá quán (/feed)
└── (manager)/
    ├── layout.tsx             # Manager layout - auth guard + ManagerProvider
    └── manager/
        ├── page.tsx           # Manager Dashboard - quản lý thực đơn (/manager)
        └── analytics/
            └── page.tsx       # Financial Analytics (/manager/analytics)

---

Root Layout (app/layout.tsx)

Description: Root layout wrapping entire application. Loads providers, fonts, and common layouts (header/footer).

Structure

• Imports providers (AuthProvider, MenuProvider, CartProvider)
• Renders Header component (sticky top)
• Renders page content via {children}
• Renders Footer component

Metadata

• Title: "Coffee Shop"
• Charset: UTF-8
• Viewport: responsive

Key Features

• Global CSS variables loaded here
• Header remains sticky across all pages
• Footer always present

---

Providers (app/providers.tsx)

Description: Client component that wraps all context providers for the application.

Providers Included

1. AuthProvider (lib/auth-context.tsx)

   • Manages user authentication state
   • Persists user in localStorage
   • Enables login/logout/register flows

2. MenuProvider (lib/menu-context.tsx)

   • Shares active category state
   • Syncs Header mobile menu and Navbar sidebar

3. CartProvider (lib/cart-context.tsx)

   • Manages shopping cart state
   • Persists cart items in localStorage
   • Provides add/remove/update operations

Usage in Root Layout

<Providers>
  <Header />
  {children}
  <Footer />
</Providers>

---

(main) Route Group

Layout (app/(main)/layout.tsx)

Description: Layout for authenticated/main routes. Can include route-specific UI (e.g., sidebar navigation).

Usage

• Wraps all pages under (main)/ route group
• Inherits root layout above it
• Can add additional styling or structure specific to main pages

---

Pages

1. Main Page - Duyệt Thực Đơn (app/(main)/page.tsx)

Route: / (default) or /(main) Type: Client component Description: Main shopping interface. Shows product grid with sidebar category filter.

Key Features

• Sidebar (Navbar):

  • Collapsible (64px collapsed / 240px expanded)
  • Category list with icons
  • Sticky, full viewport height minus header
  • Responsive: desktop (expanded) vs mobile (collapsed)

• Product Grid:

  • Responsive columns (1/2/3/4/5 depending on sidebar state and screen size)
  • Filter by: availability, active category, search query
  • Search bar with clear button
  • Empty state when no products match

• Mobile Category Menu:

  • Visible only on screens < md (768px)
  • Sticky scrollable tabs below search
  • Allows category selection on mobile

Context Usage

• useMenu() - Get/set active category
• useCart() - Add products to cart
• MenuContext - Shares category state with Header

State Management

isSidebarOpen: boolean; // Sidebar expanded/collapsed
searchQuery: string; // Search input value
activeCategory: string; // From MenuContext

Responsive Behavior

• Mobile (<480px): 1 col, sidebar collapsed
• Small phone (480px): 2 cols, sidebar collapsed
• Tablet (768px): Mobile menu tabs appear
• Desktop (1024px): Sidebar expands, 2-4 cols depending on sidebar
• Large screen (1280px+): 3-5 cols

---

2. Login Page (app/(main)/login/page.tsx)

Route: /login Type: Client component Description: User authentication form. Supports login for Manager, Staff, and Customer roles.

Key Features

• Form Fields:

  • Username input (with icon)
  • Password input (with show/hide toggle)
  • "Dang nhap" button
  • "Dang ky tai khoan" link to register

• Validation:

  • Username: required, non-empty
  • Password: required, min 4 characters
  • Error messages displayed inline

• Demo Credentials:

  • Shows example accounts for testing:
    • Manager: admin / admin
    • Staff: Nguyễn Văn An / Nguyễn Văn An
    • Customer: 0987654321 / user1

• UI:

  • Centered card (max-width: 448px)
  • Shop logo and name at top
  • Error messages with icons
  • Responsive design

Context Usage

• useAuth() - Login function

Navigation

• Success: redirect to / (main page)
• Register link: go to /register

---

3. Register Page (app/(main)/register/page.tsx)

Route: /register Type: Client component Description: User registration flow. Two-step process: phone verification → account creation.

Key Features

• Step 1: Phone Verification

  • Input phone number
  • "Request OTP" button
  • Mock OTP validation (no real SMS)

• Step 2: Account Creation (after OTP)

  • Confirm phone number
  • "Create Account" button
  • Auto-login after registration

• Validation:

  • Phone format validation
  • OTP code validation

• UI:

  • Centered card layout
  • Step indicator
  • Progress feedback

Context Usage

• useAuth() - completeRegistration()

Navigation

• Success: redirect to / (main page)
• Login link: go to /login

---

4. Payment Page (app/(main)/payment/page.tsx)

Route: /payment Type: Client component Description: Payment/checkout page. Shows cart items in a table with quantity controls and a summary aside with payment actions.

Key Features

• Cart Table:

  • Lists all cart items (name, price, description, quantity controls, delete)
  • Quantity input with +/- buttons and direct number input
  • Empty state message when cart is empty
  • Horizontal scroll on small screens (min-w-190)

• Invoice Aside:

  • Sticky on desktop (top offset = header height + 1rem)
  • Shows total price
  • Payment buttons: Tiền mặt, QR Code (UI-only; trigger review modal for customers)
  • "Đánh giá" button — only visible when user.role === "customer"; opens ReviewModal
  • "Quay về" button — links back to /; spans full width when review button is absent

• Review Modal (ReviewModal):

  • Opened when a customer clicks "Đánh giá" OR clicks a payment button (Tiền mặt/QR)
  • Closed via "Quay lại" button, backdrop click, or after submitting and closing
  • See components/ReviewModal.tsx for full documentation

Context Usage

• useCart() — items, totalPrice, increaseQty, decreaseQty, removeFromCart, setQuantity
• useAuth() — user (to check user.role === "customer" for review button visibility)

State Management

isReviewOpen: boolean; // Controls ReviewModal visibility
isCustomer: boolean; // Derived from user.role === "customer"

Responsive Behavior

• Mobile: Single column layout, table scrolls horizontally, button labels hidden (icon only)
• Desktop (lg+): Button labels visible, aside becomes sticky sidebar (xl: w-85)
• Review button grid: When customer is logged in, 3 buttons in 2-column grid; "Quay về" occupies remaining space. Otherwise 2-column grid with "Quay về" spanning full width.

---

(feed) Route Group

Layout (app/(feed)/layout.tsx)

Description: Layout for feed routes. Can have specific styling for discovery/exploration pages.

---

Feed Page - Khám Phá Quán (app/(feed)/feed/page.tsx)

Route: /feed Type: Client component Description: Discover coffee shops. Browse and search available shops with their location and details.

Key Features

• Shop Cards:

  • Shop image (responsive height)
  • Name and location
  • "Xem menu" button (links to /)
  • Hover effects with shadow/lift animation

• Search & Filter:

  • Sticky bottom filter bar
  • Search by shop name
  • Search by address
  • Clear buttons for each field

• Grid Layout:

  • Responsive (1/2/3 columns)
  • Adjusts to screen size

• Empty State:

  • Icon and message when no shops match
  • Clear filter button

Context Usage

• useAuth() - Optional: check user role

State Management

searchName: string      // Shop name search
searchAddress: string   // Shop address search
filteredShops: Shop[]   // Filtered results

Data Source

• MOCK_SHOPS from lib/constants.ts

---

CSS & Styling

Global Styles (app/globals.css)

Description: Root CSS file. Imports Tailwind CSS, defines design tokens (CSS variables), and global styles.

Design Tokens (CSS Variables)

Defined at :root for light mode, with dark mode variants:

Colors

• --color-primary - Main brand color (brown)
• --color-primary-dark - Darker shade for hover
• --color-accent - Secondary accent color
• --color-bg-* - Background colors (main, card, sidebar)
• --color-border-* - Border colors
• --color-text-* - Text colors (primary, secondary, muted)
• --color-shadow-* - Shadow colors (sm, md)

Spacing

• --spacing-header-height - Header component height
• Standard Tailwind spacing (via Tailwind)

Typography

• Font stack defined via Google Fonts (Geist)

Tailwind Config Integration

• v4 with custom properties support
• Extends with CSS variables
• Dark mode: CSS variable override

---

Key Concepts

Route Groups

• (main) and (feed) are route groups (don't appear in URL)
• Allow different layouts/providers per route group
• Used for organization and flexibility

SSR vs Client Components

• Most pages are "use client" (need interactivity)
• Context providers must be client components
• Layout.tsx can be server component

Responsive Design

• Breakpoints: sm (640px), md (768px), lg (1024px), xl (1280px), 2xl (1536px)
• Sidebar width affects grid columns
• Mobile: vertical layout, collapsed sidebar
• Desktop: horizontal layout, expanded sidebar

Navigation

• Internal links use next/link
• useRouter() for programmatic navigation
• Auth redirects after login/register

---

Development Workflow

Adding a New Page

1. Create file under appropriate route group: app/(main)/new-feature/page.tsx
2. Make it a client component if it needs interactivity: "use client"
3. Use context hooks as needed (useAuth, useCart, useMenu)
4. Export default component
5. Add to documentation

Adding a New Route Group

1. Create directory: app/(group-name)/
2. Create layout.tsx if custom layout needed
3. Add pages under this group
4. Update codebase understanding

Styling Pages

• Use Tailwind classes + CSS variables
• Reference design tokens for consistency
• Follow responsive patterns from existing pages

---

(manager) Route Group

Layout (app/(manager)/layout.tsx)

Description: Layout for manager routes. Guards access — redirects non-managers to /. Wraps children in ManagerProvider.

---

Manager Dashboard (app/(manager)/manager/page.tsx)

Route: /manager Type: Client component Description: Full menu management interface for the shop owner.

Key Features

• Sidebar (desktop): Brand, tab navigation (Thực đơn / Combo / Danh mục), link to Financial Analytics, user info, logout
• Top bar: Page title, mobile tab switcher, analytics shortcut button
• Tabs: Products, Combos, Categories — each with CRUD modals
• Analytics link: fa-chart-line button → /manager/analytics

---

Financial Analytics (app/(manager)/manager/analytics/page.tsx)

Route: /manager/analytics Type: Client component Description: Financial analytics and reporting dashboard for the shop manager.

Key Features

• Summary cards: Total revenue, orders, profit, average order value — each with period-over-period comparison %
• Period selector: Day / Week / Month / Year — switches revenue dataset
• Chart switcher: Line chart (trend), Bar chart (current vs previous half), Pie chart (revenue by category)
• SVG charts: Pure SVG, no external library — hover tooltips stay inside viewBox (auto-flip above/below for line points & bar tops), interactive dots/slices
• Top 5 products: Horizontal bar ranking filtered by category
• Product detail table: All 18 products sortable by units sold, revenue, profit, margin
• Summary row: Totals for filtered data (revenue, profit, volume, avg margin)
• Category filter: Dropdown to filter both top-5 and detail table

Data Sources

• MOCK_REVENUE_DAILY/WEEKLY/MONTHLY/YEARLY from lib/constants.ts
• MOCK_PRODUCT_SALES from lib/constants.ts
• MENU_CATEGORIES for category labels

State Management

period: AnalyticsPeriod; // "day" | "week" | "month" | "year"
activeChart: "line" | "bar" | "pie";
categoryFilter: string; // category id or "all"

---

Future Enhancements

• Payment page implementation
• Customer review modal (ReviewModal) with 5-star rating + textarea
• Manager dashboard (menu management)
• Financial Analytics dashboard (charts, profit analysis)
• Order history/tracking page
• User profile page
• Cart checkout flow
• Real backend API integration