Welcome to the Eyewear Store Frontend

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• app/layout.tsx
• lib/api-client.ts
• features/products/components/products-content.tsx
• app/admin/products/page.tsx
• types/product.types.ts
• app/globals.css
• E2E_TESTING.md

This document provides a comprehensive technical overview of the Eyewear Store Frontend, a Next.js application for the "VisionStore" e-commerce platform. The project is designed to offer a modern shopping experience for premium eyewear, featuring a customer-facing shop and an administrative dashboard for managing products, orders, and users. It is built with a focus on feature-based organization, type safety, and a clear separation of concerns.

The application is built using v0.app and is deployed on Vercel. It includes features such as product browsing with advanced filtering, a shopping cart, a checkout process, user account management, and a virtual try-on feature. The architecture emphasizes a service layer for business logic, Zustand for global state management, and a robust API client for backend communication.

Sources: README.md:1-12, app/layout.tsx:18-21

Project Overview & Tech Stack

The project is a modern web application built with Next.js 16 and React 19. It uses TypeScript for type safety and Tailwind CSS for styling. The core state management is handled by Zustand, with TanStack Query (@tanstack/react-query) managing server state, caching, and data fetching.

Sources: package.json:51-78

Key Dependencies

Library	Version	Purpose
next	16.0.1	The React framework for production.
react	19	A JavaScript library for building user interfaces.
tailwindcss	4.1.9	A utility-first CSS framework.
typescript	5.9.3	A typed superset of JavaScript.
zustand	5.0.8	Small, fast, and scalable state-management.
@tanstack/react-query	5.90.7	Server-state management for fetching, caching, and updating.
axios	1.13.1	Promise-based HTTP client for the browser and node.js.
zod	3.25.76	TypeScript-first schema declaration and validation.
@playwright/test	1.56.1	End-to-end testing framework.
jest	30.0.0	JavaScript testing framework.

Sources: package.json:5-81

Architecture

The application follows a set of clear architectural principles to ensure maintainability and scalability. The core tenets are feature-based organization, a distinct service layer, and robust state management.

Sources: README.md:29-50

Project Structure

The codebase is organized by features, with shared components, hooks, and utilities located in higher-level directories. This modular structure helps isolate concerns and makes it easier to navigate the project.

The diagram below illustrates the high-level directory structure.

Architectural Principles

Principle	Description
Feature-based Organization	Each feature (e.g., products, cart) is a self-contained module with its own components, hooks, types, and utilities.
Service Layer	Business logic, such as API calls and data transformation, is abstracted into service classes (e.g., product.service.ts). This logic is reusable across components.
State Management	A hybrid approach is used: Zustand for global state (cart, user), React hooks for local component state, and React Query for server state.
Type Safety	Leverages TypeScript extensively, using branded types, discriminated unions for API responses, and Zod for runtime validation.

Sources: README.md:52-75

This diagram shows the data flow between the different architectural layers.

API Communication

Communication with the backend is handled by a centralized API client built with Axios. It is configured to manage authentication, token refreshing, and error handling automatically.

Sources: lib/api-client.ts

API Client Configuration

The client is configured with a base URL from environment variables and a default timeout.

Configuration	Value	Source File
BASE_URL	process.env.NEXT_PUBLIC_API_URL or http://localhost:3000	lib/api-client.ts:20
TIMEOUT	10000ms	lib/api-client.ts:21
RETRY_COUNT	3	lib/api-client.ts:22
RETRY_DELAY	1000ms	lib/api-client.ts:23

Authentication & Token Refresh

The API client uses interceptors to manage JWT-based authentication.

1. Request Interceptor: Before any request is sent, the interceptor retrieves the accessToken from the useAuthStore (Zustand) and adds it to the Authorization header.
2. Response Interceptor: If a request fails with a 401 Unauthorized status, the interceptor attempts to refresh the token using the refreshToken.
   • It calls the /auth/refresh endpoint.
   • If successful, it updates the tokens in useAuthStore, updates the header of the original failed request, and retries it.
   • If the refresh fails, it clears all tokens and redirects the user to the login page.

The following sequence diagram illustrates the token refresh flow.

Core Features

Admin Product Management

The admin dashboard provides full CRUD (Create, Read, Update, Delete) functionality for products.

• List Products: The /admin/products page displays a paginated and filterable list of all products. Admins can search by name or filter by category.
• Create Product: The /admin/products/new page presents a form to add a new product.
• Edit Product: The /admin/products/[id]/edit page allows for updating an existing product's details.
• Delete Product: A confirmation dialog is used to prevent accidental deletion.

This flow chart shows the process of creating a new product.

Shop Product Discovery

The main shop page at /products allows users to discover eyewear through a rich interface.

• Layout: Users can toggle between a grid and list view.
• Filtering: A sidebar allows filtering by price range and category.
• Sorting: Products can be sorted by price, newest, and rating.
• Search: A search bar provides full-text search capabilities.
• Pagination: Results are paginated, and users can change the number of items per page.

State is managed within the ProductsContent component using useState and synchronized with URL search parameters. Data is fetched using the useProducts hook, which calls the backend API with the appropriate query parameters.

Sources: features/products/components/products-content.tsx

Data Models

The application relies on strongly-typed data models, primarily for products. The Product type is defined with Zod for runtime validation.

Product Type

Field	Type	Description
id	string	Unique identifier (CUID).
sku	string	Stock Keeping Unit.
name	string	Product name.
slug	string	URL-friendly slug.
priceInt	number	Price in VND integer format.
stock	number	Available quantity.
description	`string	null`
imageUrls	string[]	Array of image URLs.
categoryId	`string	null`
attributes	`ProductAttributes	null`
model3dUrl	`string	null`
createdAt	string	Creation timestamp.
updatedAt	string	Last update timestamp.

Sources: types/product.types.ts:88-103

Styling and Theming

The project uses Tailwind CSS with a CSS variable-based theming system to support both light and dark modes. Colors, fonts, and other design tokens are defined in app/globals.css.

• Light Mode (default): Defined under the :root selector.
• Dark Mode: Defined under the .dark class selector.

A few key color variables are shown below:

Variable	Light Mode	Dark Mode
--background	#ffffff	#1a1a1a
--foreground	#1a1a1a	#f7fafc
--primary	#2d3748	#f7fafc
--card	#ffffff	#2d3748
--destructive	#e53e3e	#fc8181

Sources: app/globals.css:4-70

Testing

The project includes configurations for both end-to-end (E2E) and unit testing.

• E2E Testing: Performed with Playwright. Tests cover critical user flows like checkout.
• Unit Testing: Set up with Jest and React Testing Library.

The following scripts are available for running tests:

Script	Command	Description
test	jest	Runs all unit tests.
test:watch	jest --watch	Runs unit tests in interactive watch mode.
test:e2e	playwright test	Runs all Playwright E2E tests.
test:e2e:ui	playwright test --ui	Opens the Playwright UI for interactive E2E testing.

Sources: package.json:8-13, E2E_TESTING.md

Summary

The Eyewear Store Frontend is a well-structured Next.js application designed for a modern e-commerce experience. Its architecture promotes modularity and maintainability through a feature-based organization, a clear service layer, and robust state management. The use of TypeScript and Zod ensures type safety, while the centralized API client simplifies backend communication and handles authentication seamlessly. With integrated testing and a flexible theming system, the project provides a solid foundation for building and scaling a premium eyewear storefront.

Sources: README.md, package.json, lib/api-client.ts