<project_specification>
  <project_name>ShopFlow - Modern E-Commerce Platform</project_name>

  <overview>
    Build a fully functional e-commerce platform with product browsing, shopping cart, checkout,
    and order management. Features include product search with filters, user accounts, wishlist,
    reviews, and an admin dashboard for inventory management. Focus on conversion-optimized UX
    with fast performance and mobile-first design.
  </overview>

  <technology_stack>
    <language_preference>
      IMPORTANT: Use TypeScript (.ts, .tsx) for ALL code. Do NOT use JavaScript (.js, .jsx).
      All files must have proper type annotations and strict type checking enabled.
    </language_preference>
    <api_key>
        You can use an API key located at /tmp/api-key for testing.
    </api_key>
    <frontend>
      <framework>React 18+ with Vite and TypeScript</framework>
      <language>TypeScript (strict mode) - use .tsx for components, .ts for utilities</language>
      <styling>Tailwind CSS (via CDN or PostCSS)</styling>
      <state_management>React hooks with typed state, Context for cart, Zustand with TypeScript</state_management>
      <routing>React Router v6 with typed routes</routing>
      <forms>React Hook Form with TypeScript and Zod for validation</forms>
      <type_safety>Enable strict mode in tsconfig.json, no implicit any</type_safety>
      <port>Only launch on port {frontend_port}</port>
    </frontend>
    <backend>
      <runtime>Node.js with Express and TypeScript</runtime>
      <language>TypeScript - compile with tsc or ts-node for development</language>
      <database>SQLite with better-sqlite3 (with typed queries)</database>
      <authentication>JWT-based auth with refresh tokens (typed middleware)</authentication>
      <payment>Stripe integration with @stripe/stripe-js types (test mode)</payment>
      <image_handling>Multer with TypeScript types for product image uploads</image_handling>
      <type_safety>Use interfaces for all API request/response types</type_safety>
    </backend>
    <communication>
      <api>RESTful endpoints with typed request/response interfaces</api>
      <shared_types>Create shared type definitions for frontend and backend</shared_types>
    </communication>
  </technology_stack>

  <prerequisites>
    <environment_setup>
      - Repository includes .env with JWT_SECRET and STRIPE_TEST_KEY
      - Frontend dependencies pre-installed via pnpm
      - Backend code in /server directory
      - Sample product data included
    </environment_setup>
  </prerequisites>

  <core_features>
    <product_catalog>
      - Product listing with grid/list view toggle
      - Product detail page with image gallery
      - Multiple product images with zoom
      - Size and color variants
      - Stock availability indicator
      - Related products section
      - Recently viewed products
      - Category and subcategory navigation
      - Brand filtering
      - Price range filtering
      - Sorting (price, popularity, newest, rating)
      - Pagination and infinite scroll option
    </product_catalog>

    <search>
      - Full-text product search
      - Search suggestions (autocomplete)
      - Search filters (category, price, brand)
      - Search history
      - No results handling with suggestions
      - Voice search (mobile)
    </search>

    <shopping_cart>
      - Add to cart with quantity selection
      - Cart drawer/slide-out panel
      - Update quantity in cart
      - Remove items from cart
      - Save for later functionality
      - Cart persistence (localStorage + server sync)
      - Cart item count badge
      - Estimated shipping cost
      - Promo code application
      - Cart summary with totals
    </shopping_cart>

    <user_accounts>
      - Registration with email verification
      - Login with remember me option
      - Social login (Google, mock implementation)
      - Password reset flow
      - Profile management
      - Address book (multiple addresses)
      - Order history
      - Wishlist management
      - Account deletion
    </user_accounts>

    <checkout>
      - Multi-step checkout wizard
      - Guest checkout option
      - Shipping address form with validation
      - Address autocomplete
      - Shipping method selection
      - Payment form (Stripe Elements)
      - Order summary review
      - Order confirmation page
      - Order confirmation email (mock)
      - Express checkout option
    </checkout>

    <orders>
      - Order confirmation with number
      - Order status tracking
      - Order history list
      - Order detail view
      - Reorder functionality
      - Order invoice download (PDF mock)
      - Cancel order (if not shipped)
    </orders>

    <reviews_ratings>
      - Star rating system (1-5)
      - Written reviews
      - Review photos
      - Helpful/not helpful voting
      - Review filtering and sorting
      - Verified purchase badge
      - Average rating display
      - Rating distribution chart
    </reviews_ratings>

    <wishlist>
      - Add/remove from wishlist
      - Wishlist page
      - Move to cart from wishlist
      - Share wishlist link
      - Low stock notifications
    </wishlist>

    <admin_dashboard>
      - Product management (CRUD)
      - Order management
      - Customer management
      - Inventory tracking
      - Sales analytics
      - Revenue reports
      - Category management
      - Promo code management
    </admin_dashboard>

    <responsive_design>
      - Mobile-first layout
      - Touch-optimized product cards
      - Swipe for product images
      - Sticky add to cart on mobile
      - Bottom navigation on mobile
      - Responsive product grid
    </responsive_design>
  </core_features>

  <database_schema>
    <tables>
      <users>
        - id, email, password_hash, name
        - phone, avatar_url
        - role (customer, admin)
        - email_verified, created_at, updated_at
      </users>

      <addresses>
        - id, user_id, label (Home, Work)
        - first_name, last_name
        - street_address, apartment
        - city, state, postal_code, country
        - phone, is_default
      </addresses>

      <categories>
        - id, parent_id, name, slug
        - description, image_url
        - position, is_active
      </categories>

      <products>
        - id, category_id, brand_id
        - name, slug, description
        - price, compare_at_price
        - sku, barcode
        - stock_quantity, low_stock_threshold
        - is_active, is_featured
        - weight, dimensions (JSON)
        - created_at, updated_at
      </products>

      <product_images>
        - id, product_id, url
        - alt_text, position, is_primary
      </product_images>

      <product_variants>
        - id, product_id
        - name (Size, Color)
        - value (M, L, Red, Blue)
        - price_adjustment
        - stock_quantity, sku
      </product_variants>

      <brands>
        - id, name, slug, logo_url
        - description, is_active
      </brands>

      <orders>
        - id, user_id, order_number
        - status (pending, processing, shipped, delivered, cancelled)
        - shipping_address (JSON)
        - billing_address (JSON)
        - subtotal, shipping_cost, tax, discount, total
        - payment_method, payment_status
        - shipping_method, tracking_number
        - notes, created_at, updated_at
      </orders>

      <order_items>
        - id, order_id, product_id, variant_id
        - quantity, unit_price, total_price
        - product_snapshot (JSON)
      </order_items>

      <cart_items>
        - id, user_id, session_id
        - product_id, variant_id, quantity
        - created_at, updated_at
      </cart_items>

      <wishlist>
        - id, user_id, product_id
        - created_at
      </wishlist>

      <reviews>
        - id, product_id, user_id
        - rating (1-5), title, content
        - is_verified_purchase
        - helpful_count
        - created_at, updated_at
      </reviews>

      <promo_codes>
        - id, code, type (percentage, fixed)
        - value, min_order_amount
        - max_uses, current_uses
        - start_date, end_date
        - is_active
      </promo_codes>
    </tables>
  </database_schema>

  <api_endpoints_summary>
    <products>
      - GET /api/products
      - GET /api/products/:slug
      - GET /api/products/search
      - GET /api/products/featured
      - GET /api/categories
      - GET /api/categories/:slug/products
      - GET /api/brands
    </products>

    <cart>
      - GET /api/cart
      - POST /api/cart/items
      - PUT /api/cart/items/:id
      - DELETE /api/cart/items/:id
      - POST /api/cart/promo-code
      - DELETE /api/cart/promo-code
    </cart>

    <checkout>
      - POST /api/checkout/validate-address
      - GET /api/checkout/shipping-methods
      - POST /api/checkout/create-payment-intent
      - POST /api/checkout/complete
    </checkout>

    <orders>
      - GET /api/orders
      - GET /api/orders/:id
      - POST /api/orders/:id/cancel
    </orders>

    <reviews>
      - GET /api/products/:id/reviews
      - POST /api/products/:id/reviews
      - PUT /api/reviews/:id
      - DELETE /api/reviews/:id
      - POST /api/reviews/:id/helpful
    </reviews>

    <wishlist>
      - GET /api/wishlist
      - POST /api/wishlist
      - DELETE /api/wishlist/:productId
    </wishlist>

    <user>
      - GET /api/user/profile
      - PUT /api/user/profile
      - GET /api/user/addresses
      - POST /api/user/addresses
      - PUT /api/user/addresses/:id
      - DELETE /api/user/addresses/:id
    </user>

    <admin>
      - GET /api/admin/products
      - POST /api/admin/products
      - PUT /api/admin/products/:id
      - DELETE /api/admin/products/:id
      - GET /api/admin/orders
      - PUT /api/admin/orders/:id
      - GET /api/admin/analytics
    </admin>
  </api_endpoints_summary>

  <ui_layout>
    <header>
      - Logo (left)
      - Category mega menu
      - Search bar (center)
      - User account icon
      - Wishlist icon with count
      - Cart icon with count + mini preview
    </header>

    <product_listing>
      - Filters sidebar (collapsible on mobile)
      - Sort dropdown
      - View toggle (grid/list)
      - Product cards with:
        - Image with hover zoom
        - Quick view button
        - Add to wishlist heart
        - Product name
        - Price (sale price highlighted)
        - Rating stars
        - Add to cart button
    </product_listing>

    <product_detail>
      - Image gallery with thumbnails
      - Product info section:
        - Name, brand, rating
        - Price and discount
        - Variant selectors
        - Quantity picker
        - Add to cart button
        - Add to wishlist
        - Share buttons
      - Tabs: Description, Specifications, Reviews
      - Related products carousel
    </product_detail>

    <cart_drawer>
      - Item list with images
      - Quantity adjusters
      - Remove button
      - Subtotal
      - Checkout button
      - Continue shopping link
    </cart_drawer>

    <checkout_flow>
      - Progress stepper
      - Step 1: Shipping address
      - Step 2: Shipping method
      - Step 3: Payment
      - Step 4: Review and confirm
      - Order summary sidebar (sticky)
    </checkout_flow>
  </ui_layout>

  <design_system>
    <color_palette>
      - Primary: Emerald (#10B981)
      - Secondary: Slate (#475569)
      - Background: White, Gray-50
      - Text: Gray-900, Gray-600
      - Sale/Discount: Red-500
      - Success: Green-500
      - Warning: Amber-500
    </color_palette>

    <typography>
      - Font: Inter, system-ui
      - Product titles: font-medium, text-lg
      - Prices: font-bold
      - Body: text-sm to text-base
    </typography>

    <components>
      - Product cards with hover effects
      - Pill-shaped buttons
      - Star rating component
      - Quantity stepper
      - Price with strikethrough for discounts
      - Badge for sale/new/bestseller
      - Skeleton loaders
    </components>
  </design_system>

  <implementation_steps>
    <step number="1">
      <title>Foundation Setup</title>
      <tasks>
        - Initialize Vite React project with TypeScript template (npm create vite@latest client -- --template react-ts)
        - Initialize Express backend with TypeScript (tsconfig.json with strict: true)
        - Create shared types directory for frontend/backend type sharing
        - Set up SQLite with better-sqlite3 and typed query helpers
        - Create database schema with TypeScript interfaces
        - Implement typed authentication middleware
        - Seed sample products with type-safe data
      </tasks>
    </step>

    <step number="2">
      <title>Product Catalog</title>
      <tasks>
        - Build product listing API
        - Create product detail API
        - Implement categories
        - Add search functionality
        - Build filtering and sorting
      </tasks>
    </step>

    <step number="3">
      <title>Shopping Cart</title>
      <tasks>
        - Create cart API
        - Build cart UI components
        - Implement cart drawer
        - Add quantity management
        - Handle cart persistence
      </tasks>
    </step>

    <step number="4">
      <title>User Accounts</title>
      <tasks>
        - Registration and login flows
        - Profile management
        - Address book
        - Order history
      </tasks>
    </step>

    <step number="5">
      <title>Checkout Flow</title>
      <tasks>
        - Multi-step checkout UI
        - Shipping address form
        - Shipping method selection
        - Stripe payment integration
        - Order confirmation
      </tasks>
    </step>

    <step number="6">
      <title>Reviews and Wishlist</title>
      <tasks>
        - Review submission and display
        - Star rating system
        - Wishlist functionality
      </tasks>
    </step>

    <step number="7">
      <title>Admin Dashboard</title>
      <tasks>
        - Product management UI
        - Order management
        - Basic analytics
      </tasks>
    </step>

    <step number="8">
      <title>Polish</title>
      <tasks>
        - Mobile optimization
        - Performance tuning
        - SEO improvements
        - Accessibility audit
      </tasks>
    </step>
  </implementation_steps>

  <success_criteria>
    <functionality>
      - Complete purchase flow works end-to-end
      - Cart syncs between sessions
      - Search returns relevant results
      - Filters work correctly
      - Reviews display and submit
    </functionality>

    <performance>
      - Product listing loads under 2s
      - Images lazy load properly
      - Checkout completes under 5s
      - Mobile performance score > 85
    </performance>

    <design>
      - Professional e-commerce appearance
      - Consistent branding
      - Mobile-responsive at all breakpoints
      - Clear CTAs and conversion paths
    </design>
  </success_criteria>
</project_specification>

