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)

---

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 (TBD) Description: Payment/checkout page. Currently a placeholder; implement when cart and order system are ready.

---

(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

---

Future Enhancements

• Payment page implementation
• Order history/tracking page
• Manager dashboard (menu management, order tracking)
• User profile page
• Cart checkout flow
• Real backend API integration