frontend/AGENTS.md

AGENTS GUIDE

1) Kiến trúc project

Dự án sử dụng Next.js App Router với cấu trúc chính:

app/ - Routes & Pages

Chứa route/page/layout theo Next.js App Router.

• layout.tsx - Root layout toàn app (Header + Providers + Footer wrapper)
• providers.tsx - Client component gắn 3 providers: AuthProvider, MenuProvider, CartProvider
• globals.css - Global styles + CSS variables + Tailwind imports
• Route groups:
  • (main)/ - Main shopping interface (duyệt menu, đăng nhập, đăng ký, thanh toán)
  • (feed)/ - Feed/discovery page (khám phá quán)
  • (manager)/ - Manager dashboard (quản lý sản phẩm, đơn hàng) - [ĐANG PHÁT TRIỂN]
• Tài liệu: app/APP.md - Chi tiết routes, pages, CSS tokens

components/ - Reusable UI Components

Chứa các UI component tái sử dụng:

• CartProduct.tsx - Product card (image, name, price, buy button)
• Navbar.tsx - Left sidebar với category filter (collapsible 64px/240px)
• CartFab.tsx - Floating action button hiển thị số item giỏ + tooltip giá
• ReviewModal.tsx - Modal đánh giá 5 sao + textarea
• Tài liệu: components/COMPONENTS.md - Props, behavior, styling của từng component

layouts/ - Layout Components

Chứa layout dùng chung:

• header.tsx - Sticky top bar với brand (logo + shop name) + auth status
• footer.tsx - Footer với 3 sections: brand info, social links, WiFi card
• Tài liệu: layouts/LAYOUTS.md - Responsive design, CSS variables, responsive patterns

lib/ - Shared Logic & Data

Chứa logic dùng chung, context, constants, types:

• types.ts - TypeScript interfaces: User, Product, MenuCategory, Shop, ShopInfo
• constants.ts - Mock data: MOCK_PRODUCTS (18 items), MOCK_SHOPS (5), MOCK_USERS, MENU_CATEGORIES (8), SHOP_INFO, SOCIAL_LINKS
• auth-context.tsx - AuthProvider + useAuth() hook (login, logout, register)
• cart-context.tsx - CartProvider + useCart() hook (add, remove, quantity operations)
• menu-context.tsx - MenuProvider + useMenu() hook (category state)
• Tài liệu: lib/LIB.md - Chi tiết types, constants, contexts, integration guide

public/ - Static Assets

Chứa static assets:

• favicon/ - Favicon files
• imgs/ - Logo, product images (organized in products/ subfolder)

scripts/ - Internal Scripts

Chứa script nội bộ:

• release.ts - Semantic release script

types/ - Global Types

Chứa type dùng chung cấp project:

• css.d.ts - TypeScript declarations cho CSS modules

Root Config Files

• package.json - Dependencies (Next.js 16.1.7, React 19.2.3, Tailwind 4.2.2, TypeScript)
• pnpm-lock.yaml, package-lock.json - Lock files
• tsconfig.json - TypeScript config
• next.config.ts - Next.js config
• tailwind.config.ts - Tailwind CSS config (v4)
• postcss.config.mjs - PostCSS config
• eslint.config.ts - ESLint rules
• .prettierrc - Prettier formatting
• release.config.ts - Semantic release config
• .gitignore - Git ignored files
• .blackboxrules - Custom rules for blackbox AI

2) Code convention (Naming, format, style guide)

Naming & File Organization

• React components: PascalCase (e.g., CartProduct.tsx, Navbar.tsx)
• Context/util files: kebab-case (e.g., auth-context.tsx, menu-context.tsx)
• Variables/functions: camelCase
• Types/Interfaces: PascalCase
• Routes: Follow folder structure in app/ (URL = folder path)
• Imports: Use absolute paths with @/ alias (e.g., import { useAuth } from "@/lib/auth-context")

Format & Linting

• Language: TypeScript (.ts, .tsx) for all files
• Formatter: Prettier (config: .prettierrc)
  • Import sorting: @trivago/prettier-plugin-sort-imports
  • Tailwind class sorting: prettier-plugin-tailwindcss
• Linter: ESLint (config: eslint.config.ts, extends next rules)
• Code style:
  • Clear, self-documenting code
  • Separate concerns by module/file
  • Avoid code duplication
  • Keep imports clean (no dead code)
  • Use "use client" directive only where needed (interactive components)

Styling & UI

• Framework: Tailwind CSS v4.2.2
• CSS Variables: Defined in globals.css at :root
  • Colors: --color-primary, --color-primary-dark, --color-accent, --color-bg-*, --color-text-*, --color-border-*, --color-shadow-*
  • Spacing: --spacing-header-height (72px)
  • Use in Tailwind: bg-[color:var(--color-primary)], text-[color:var(--color-text-primary)]
• Icons: FontAwesome (free CDN icons via <i class="fa-solid fa-...">)
• Images: Next.js Image component from next/image
• Dark mode: CSS variables support dark mode (can override :root values in @media (prefers-color-scheme: dark))

Responsive Design

• Breakpoints (Tailwind): sm (640px), md (768px), lg (1024px), xl (1280px), 2xl (1536px)
• Every new UI feature must be responsive:
  • Mobile (<640px): Single column, stacked layout, collapsed sidebar
  • Tablet (640px-1024px): 2-column layout, adjusted grid
  • Desktop (1024px+): Multi-column, expanded sidebar, comfortable spacing
• Mobile-first approach: Write base styles for mobile, then add sm:, md:, lg:, xl: prefixes for larger screens
• Example: className="w-full sm:w-1/2 md:w-1/3 lg:w-1/4"

3) Quy tắc quan trọng

Markdown Documentation Updates

Luôn update các file markdown trong folder liên quan khi hoàn thành task:

Folder Modified	Update File	Content to Add/Update
app/	app/APP.md	Routes, pages, layouts, CSS tokens, responsive behavior
components/	components/COMPONENTS.md	Component props, behavior, styling, dependencies, usage examples
layouts/	layouts/LAYOUTS.md	Layout structure, responsive patterns, CSS variables, integration
lib/	lib/LIB.md	New types, constants, contexts, integration guide, best practices

Quy trình:

1. Hoàn thành task/feature
2. Update file .md tương ứng trong folder
3. Commit code + markdown updates cùng lúc
4. Push to branch

Type Safety & Data Flow

• Always use TypeScript - no plain any types
• Mock data first - Use lib/constants.ts for development, replace with API later
• Contexts for state sharing:
  • AuthContext (lib/auth-context.tsx) - User state + auth operations
  • CartContext (lib/cart-context.tsx) - Shopping cart + operations
  • MenuContext (lib/menu-context.tsx) - Active category state
• localStorage keys: coffee-shop-user, coffee-shop-cart (defined in contexts)

Component Development

• Client vs Server Components:
  • Use "use client" only for interactive components (forms, state, event handlers)
  • Server components by default (layouts, static content)
• Props pattern: Always define prop interfaces, no unnamed parameters
• Reusable components: Place in components/, not scattered in app/
• Styling: Use Tailwind + CSS variables, not inline styles or CSS files

Testing & Quality

• Responsive testing: Test on mobile (< 640px), tablet (768px), desktop (1024px+)
• Accessibility: Images have alt text, buttons have semantic HTML, sufficient contrast
• Performance: Use Next.js Image component, optimize imports, lazy-load where needed
• Error handling: Validate user input at system boundaries, not internally trusted code

Git & Commits

• Commit message: Follow conventional commits (feat:, fix:, docs:, style:, refactor:)
• Before pushing: Ensure npm run lint and npm run format pass locally
• Markdown updates: Include in same commit as code changes
• Branch naming: Feature branches = feature_<name> (e.g., feature_manager_page)

---

4) Quick Reference Guide for AI

Creating a New Component

1. Create file in components/ComponentName.tsx (PascalCase)
2. Use TypeScript with proper prop interfaces
3. Export default component
4. Add section to components/COMPONENTS.md

Creating a New Page

1. Create folder: app/(group-name)/page-name/page.tsx
2. Add "use client" if interactive
3. Use context hooks as needed: useAuth(), useCart(), useMenu()
4. Document in app/APP.md

Adding a New Route Group

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

Adding Product Categories

1. Update MENU_CATEGORIES in lib/constants.ts
2. Update Product.category references
3. Update MOCK_PRODUCTS with new category items
4. Document in lib/LIB.md

Adding Mock Products

1. Add to MOCK_PRODUCTS array in lib/constants.ts
2. Ensure Product interface fields are filled
3. Place images in public/imgs/products/
4. Test filtering in main page

Using Contexts

// In client component with "use client"
import { useAuth } from "@/lib/auth-context";
import { useCart } from "@/lib/cart-context";
import { useMenu } from "@/lib/menu-context";

export default function MyComponent() {
  const { user, login, logout } = useAuth();
  const { items, addToCart, removeFromCart } = useCart();
  const { activeCategory, setActiveCategory } = useMenu();
  // ... component logic
}

Common File Locations

• Page layouts: app/(group-name)/layout.tsx
• Page content: app/(group-name)/page-name/page.tsx
• Shared UI components: components/ComponentName.tsx
• Layout wrappers: layouts/header.tsx, layouts/footer.tsx
• Business logic: lib/auth-context.tsx, lib/cart-context.tsx, etc.
• Data/constants: lib/constants.ts
• Type definitions: lib/types.ts
• Styling: app/globals.css (CSS variables), Tailwind classes in components

CSS Variables (from globals.css)

/* Colors */
--color-primary: main brand color
--color-primary-dark: darker shade
--color-accent: secondary color
--color-bg-main: main background
--color-bg-card: card background
--color-bg-sidebar: sidebar background
--color-text-primary: main text color
--color-text-secondary: secondary text
--color-text-muted: gray/muted text
--color-border: border color
--color-border-light: light border
--color-shadow-sm: small shadow
--color-shadow-md: medium shadow

/* Spacing */
--spacing-header-height: 72px

Useful Commands

# Development
npm run dev              # Start dev server

# Code quality
npm run lint            # Run ESLint
npm run format          # Format code with Prettier

# Build & Deploy
npm run build           # Build for production
npm start               # Start production server

# Release
npm run release         # Semantic release (auto-version + changelog)

Common Patterns

Filtering products by category:

const filtered = MOCK_PRODUCTS.filter(p =>
  activeCategory === "all" || p.category === activeCategory
);

Adding to cart:

const { addToCart } = useCart();
<button onClick={() => addToCart(product)}>Add to Cart</button>

Conditional rendering for user roles:

const { user } = useAuth();
{user?.role === "customer" && <CustomerOnlyFeature />}
{user?.role === "manager" && <ManagerDashboard />}

Responsive classes:

// Mobile-first: base style applies to all, sm:/md:/lg: apply at breakpoints
className="w-full sm:w-1/2 md:w-1/3 p-4 md:p-6 hidden md:block"

---

5) Project Status

✅ Completed Features

• User authentication (login, register, logout)
• Product grid display with category filtering
• Shopping cart with add/remove/update operations
• Payment page with review modal
• Shop discovery (feed page)
• Responsive design (mobile, tablet, desktop)
• Header + Footer with navigation
• Sidebar category filter

🚀 In Progress

• Manager dashboard (quản lý sản phẩm) - app/(manager)/ route group

📋 Planned Features

• Order history and tracking
• User profile page
• Real backend API integration (replace MOCK_PRODUCTS, MOCK_SHOPS)
• Dark mode toggle
• Search functionality enhancement
• Admin order management page