Skip to content

README.md

Latest commit

 

History

History
233 lines (179 loc) · 6.35 KB

README.md

File metadata and controls

233 lines (179 loc) · 6.35 KB

Tea Store Demo

A full-stack premium tea e-commerce application with a React frontend and FastAPI backend.

Features

  • Modern UI - Clean design with Tailwind CSS
  • Responsive Design - Mobile-first design that works on all devices
  • Shopping Cart - Full-featured cart with add/remove items and quantity management
  • Wishlist - Save favorite teas for later
  • Product Filtering - Filter by category, price range, and origin
  • Product Customization - Multi-step wizard for customizing select teas
  • Dark Mode - Toggle between light and dark themes
  • Persistent State - Cart and wishlist saved in localStorage

Technology Stack

Backend

  • Python 3.12 + FastAPI
  • Pydantic for data validation
  • Uvicorn ASGI server
  • Pytest for testing

Frontend

  • React 19 with TypeScript
  • Vite 7 for build tooling
  • Tailwind CSS 4
  • React Context for state management
  • Vitest for unit testing
  • Playwright for E2E testing

Project Structure

tea-store-demo/
├── backend/                    # FastAPI Python backend
│   ├── app/
│   │   ├── api/
│   │   │   └── routes.py       # API endpoints
│   │   ├── main.py             # FastAPI app with CORS
│   │   ├── models.py           # Pydantic models
│   │   ├── mock_data.py        # Product data
│   │   └── customization_config.py
│   ├── tests/
│   ├── main.py                 # Uvicorn entry point
│   ├── requirements.txt
│   └── pytest.ini
│
├── frontend/                   # React frontend
│   ├── src/
│   │   ├── components/
│   │   │   ├── features/       # Feature components
│   │   │   └── shared/         # Reusable components
│   │   ├── contexts/           # React Context providers
│   │   ├── services/           # API services
│   │   ├── types/              # TypeScript types
│   │   └── test/               # Test utilities
│   ├── package.json
│   └── vite.config.ts
│
├── e2e/                        # Playwright E2E tests
├── test.js                     # Cross-platform test runner
├── playwright.config.ts
├── .gitignore
└── README.md

Getting Started

Prerequisites

  • Python 3.9+
  • Node.js 18+
  • npm

Quick Start

The easiest way to run the application:

# macOS/Linux
./start.sh

# Windows
start.bat

This will:

  1. Create a Python virtual environment (if needed)
  2. Install backend dependencies
  3. Install frontend dependencies
  4. Start both services

Press Ctrl+C to stop all services.

Manual Installation

If you prefer to set up manually:

# Backend
cd backend
python -m venv venv

# Activate virtual environment
source venv/bin/activate        # macOS/Linux
venv\Scripts\activate.bat       # Windows

pip install -r requirements.txt

# Frontend
cd frontend
npm install

# E2E tests (from project root)
npm install

Running Manually

# Backend (port 8765)
cd backend
source venv/bin/activate        # macOS/Linux
venv\Scripts\activate.bat       # Windows
python main.py

# Frontend (port 4321) - in a separate terminal
cd frontend
npm run dev

The application will be available at:

API Endpoints

Method Endpoint Description
GET /api/products Get all products (supports filtering)
GET /api/products/{id} Get product by ID
GET /api/products/category/{category} Get products by category
GET /api/customization-config/{category} Get customization options

Query Parameters for /api/products

  • category - Filter by category (green, black, oolong, herbal)
  • price_max - Maximum price filter
  • material - Filter by origin (China, Japan, India, Taiwan)

Frontend Architecture

Context Providers

  • CartContext - Shopping cart state with localStorage persistence
  • WishlistContext - Wishlist state with localStorage persistence
  • ThemeContext - Dark/light mode with system preference detection
  • NotificationContext - Toast notifications

Services

  • productService - API calls for products
  • customizationService - Tea customization API calls

Components

  • features/ - Home, Wishlist, Customization modal
  • shared/ - Header, Footer, ProductCard, CartSidebar, LoadingSpinner

Testing

Test Runner Script

The test.js script runs all tests (cross-platform):

# Using node directly
node test.js              # Run backend + frontend unit tests
node test.js --e2e        # Include E2E tests
node test.js --e2e --headed  # Run E2E tests with visible browser
node test.js --coverage   # Run with coverage reports
node test.js --help       # Show all options

# Or using npm scripts
npm test                  # Run backend + frontend unit tests
npm run test:all          # Include E2E tests
npm run test:coverage     # Run with coverage reports
Option Description
--e2e Run E2E tests (Playwright)
--headed Run E2E tests in headed mode (visible browser)
--coverage Run tests with coverage reports

Running Tests Individually

# Backend tests
cd backend && pytest -v

# Frontend unit tests
cd frontend && npm run test

# E2E tests
npx playwright test
npx playwright test --headed  # With visible browser
npx playwright test --ui      # With Playwright UI

Note for Linux users: Playwright may require system dependencies. If browser installation fails, run:

npx playwright install-deps chromium

Product Data

The application includes 15 premium teas:

  • 5 Green Teas - Including Dragon Well, Matcha, Sencha, Jasmine Pearl, and Gyokuro
  • 4 Black Teas - Darjeeling, Assam, Earl Grey, and Pu-erh
  • 3 Oolong Teas - High Mountain, Tie Guan Yin, and Oriental Beauty
  • 3 Herbal Teas - Chamomile, Peppermint, and Rooibos

Teas range from $18 to $85 with origins including China, Japan, India, and Taiwan.

Development Notes

  • Frontend proxies /api requests to backend during development
  • CORS is configured for localhost:4321
  • State is persisted to localStorage (cart, wishlist, theme)

Built with React, FastAPI, and Tailwind CSS