# 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

```tsx
<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

```tsx
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

```tsx
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
