epic-system

As a frontend developer, implement the MemeUpload section for the Carousel page. This section manages file upload state with `useState` hooks: `file`, `preview`, `isDragging`, `status`, `isUploading`, and `revealed`. A `sectionRef` drives an `IntersectionObserver` scroll-reveal (threshold 0.2) that sets `revealed` to trigger entrance animations. The drag-and-drop zone handles `onDrop`, `onDragOver`, and `onDragLeave` via `useCallback` handlers — updating `isDragging` for visual feedback. `validateFile` checks MIME type against `['image/jpeg','image/png','image/webp']` and enforces a 10MB size cap, displaying errors via `status.type === 'error'`. On valid selection, `FileReader.readAsDataURL` populates `preview`. `handleUpload` simulates an async upload (1200ms delay) and sets `status.type === 'success'` with message 'Meme uploaded! Preview it on your merch below.' Framer Motion `AnimatePresence` animates the status message and preview image in/out. Uses `.mu-*` CSS class prefix.

As a frontend developer, implement the ProductSelector section for the Carousel page. This section renders a grid of six product cards (Classic Logo Hoodie $49.99, Premium Cotton Tee $29.99, Limited Edition Hoodie $64.99, Vintage Wash Tee $34.99, Athletic Fit Tee $27.99, Zip-Up Hoodie $54.99) using a `ProductCard` sub-component and a `ColorDot` sub-component. State includes `selectedProduct`, `selectedColor` per card, and an `addedFlash` local state in `ProductCard` for a momentary add-to-cart confirmation. `ColorDot` renders `e.stopPropagation()` on click to prevent card selection conflicts. Out-of-stock cards (Zip-Up Hoodie `inStock: false`) disable the add-to-cart action. Cards display discount badges (e.g., '29% OFF'), original crossed-out price, and Lucide icons (`ShoppingCart`, `Check`, `Shirt`, `Camera`). Framer Motion `AnimatePresence` animates the `Check` confirmation flash. Framer Motion `motion.div` wraps card entrance. Uses `.ps-*` CSS class prefix.

As a frontend developer, implement the CheckoutProgressBar section for the Checkout page. Build the `CheckoutProgressBar` component using the `STAGES` array (cart, shipping, payment, confirmation) with lucide-react icons (ShoppingCart, Truck, CreditCard, CheckCircle2). Implement `useState` for `activeDesc` hover state and compute `safeIndex`/`fillPct` for the animated progress fill. Apply framer-motion `motion.div` with spring animation (`stiffness: 400, damping: 25`) on stage icon scale (1.12 when active). Render `is-completed`, `is-active`, `is-pending` CSS state classes. Add hover/focus handlers (`handleStageHover`, `handleStageLeave`) with tooltip-style description display. Include full ARIA attributes (`role='button'`, `aria-pressed`, `aria-label`) and keyboard accessibility (`tabIndex={0}`). Import `CheckoutProgressBar.css` for styling.

As a Backend Developer, implement the FastAPI endpoint for meme image uploads. POST /api/v1/memes/upload — accepts multipart/form-data with an image file (JPEG, PNG, WebP), enforces 10MB size limit, validates MIME type, stores the file to disk or object storage, creates a MemeUpload record in the database, and returns {meme_id, file_url, filename, uploaded_at}. Include proper error responses (400 for invalid type/size, 500 for storage failure). Add CORS headers for the frontend origin. This endpoint is required by the MemeUpload section on the Carousel page.

As a Backend Developer, implement the FastAPI product catalog endpoints. GET /api/v1/products — returns paginated list of products with id, name, price, original_price, colors, sizes, in_stock, discount_badge, and thumb_label. GET /api/v1/products/{product_id} — returns full product details. These endpoints serve the ProductSelector section on the Carousel page and the order summary sections. Response should match the hardcoded product data in the frontend: Classic Hoodie $49.99, Premium Tee $29.99, Limited Edition Hoodie $64.99, Vintage Wash Tee $34.99, Athletic Fit Tee $27.99, Zip-Up Hoodie $54.99 (out of stock).

As a Backend Developer, implement the FastAPI order management endpoints. POST /api/v1/orders — creates a new order from cart items, shipping address, payment method selection, and applied promo code; validates promo codes (FIFA20: 20% off, SAVE10: $10 off); computes subtotal, discount, tax (8.5%), shipping ($5.99 standard, $14.99 express, $29.99 overnight), and total; stores order and order items; returns order_id, order_number (MM-YYYY-NNNNN format), status, and line item breakdown. GET /api/v1/orders/{order_id} — returns full order details for the Confirmation page. POST /api/v1/promo/validate — validates a promo code and returns discount type and value.

As a Frontend Developer, implement global state management for the epic-system single-page application. Create a React Context (or Zustand store) for: cartItems (array of {product_id, name, size, color, quantity, unit_price, thumb_label}), uploadedMemeUrl (data URL from MemeUpload for live preview in MerchCarousel), promoCode and discounts, and currentOrderId (set after order creation). Expose addToCart, removeFromCart, updateQty, setMeme, setPromo, setOrderId actions. This shared state connects MemeUpload -> MerchCarousel (meme preview), ProductSelector -> OrderSummary (cart items), and CheckoutFlow -> Confirmation (order ID). Note: existing section tasks (MemeUpload, MerchCarousel, ProductSelector, OrderSummary, CheckoutFlow, CheckoutOrderSummary) should depend on this task for shared state access.

As a Backend Developer, configure the file storage service for meme image uploads. Set up a local disk storage path (configurable via STORAGE_PATH env var) with directory creation on startup. Implement a StorageService class with save_file(file, filename) -> str and delete_file(filename) -> bool methods. Add static file serving via FastAPI's StaticFiles mount at /uploads so uploaded memes are accessible by URL. Ensure the storage path is volume-mounted in docker-compose for persistence. This is a prerequisite for the Meme Upload API endpoint (task 9b5c6915).

As a DevOps Engineer, wire Alembic migrations into the application startup and CI/CD pipeline. Add an entrypoint script to the FastAPI Docker container that runs `alembic upgrade head` before starting uvicorn. Add a docker-compose `depends_on` with healthcheck on the MySQL/MariaDB service so migrations only run when the database is accepting connections. Include a seed data script (seed.py) that inserts the six product catalog items (Classic Hoodie, Premium Tee, Limited Edition Hoodie, Vintage Wash Tee, Athletic Fit Tee, Zip-Up Hoodie) on first run using an idempotent upsert. Note: depends on database models task (3c41bbb8).

As a Frontend Developer, create a centralized API client module for the React frontend. Use axios or the native Fetch API with a configured base URL (from VITE_API_BASE_URL env var). Implement typed request/response helpers for all backend endpoints: uploadMeme(file), getProducts(), createOrder(payload), validatePromo(code), initiatePayment(orderId, method), getOrder(orderId). Add global error interceptor that surfaces API error envelopes to the UI. Export a single apiClient instance used across all section components. Note: MemeUpload (2068619a), ProductSelector (5c8d22f2), CheckoutOrderSummary (20424c83), CheckoutFinalCTA (8aa99f81), and Confirmation sections all depend on this client for real API calls.

As a frontend developer, implement the MerchCarousel section for the Carousel page. This section renders a 3D product carousel using `@react-three/fiber` `Canvas` with `@react-three/drei` helpers (`Text`, `RoundedBox`, `useTexture`, `OrbitControls`). Five `PRODUCTS` (Classic Hoodie, Premium Tee, Jersey Pro, Snapback Cap, Tote Bag) are arranged in a circle using `CAROUSEL_RADIUS = 3.2` and `ANGLE_STEP = (Math.PI * 2) / 5`. A `createMemeTexture(memeDataUrl)` function builds a `THREE.CanvasTexture` from a 256×256 canvas — drawing a grid placeholder via `drawPlaceholder` immediately, then center-cropping the uploaded meme image `onload`. The `THREE.CanvasTexture` uses `LinearFilter` for both min/mag. The carousel uses `useFrame` for rotation animation and accepts a meme data URL prop (from MemeUpload) to apply the texture to `RoundedBox` meshes representing each product. Framer Motion `AnimatePresence` handles product label overlays. Styles use `.mc-*` CSS prefix from `Carousel.css`.

As a frontend developer, implement the OrderSummary section for the Carousel page. This is a static read-only panel displaying three hardcoded `ORDER_ITEMS`: Classic Hoodie (L, $49.99 ×1, thumbLabel 'FH'), Premium Tee (M, $29.99 ×2, thumbLabel 'PT'), and Limited Edition Hoodie (XL, $64.99 ×1, thumbLabel 'LE'). The `itemCount` is computed via `Array.reduce` over quantities. Each item renders an `.os-thumb` placeholder div (showing the `thumbLabel` initials), `.os-item-info` with name and size/price meta, an `.os-qty-badge` (e.g., '×2'), and an `.os-item-price` line total computed as `price * qty`. The header shows a cart SVG icon inline and the dynamic item count label ('4 items'). A `formatPrice` utility formats values as `$X.XX`. No quantity controls — purely display. Uses `.os-*` CSS class prefix.

As a frontend developer, implement the CheckoutOrderSummary section for the Checkout page. Build the `CheckoutOrderSummary` component with `DEFAULT_ITEMS` (Argentina Champions Hoodie, Ronaldo SIUU Tee) and `useState` hooks for `expanded`, `items`, `promoCode`, `appliedPromo`, `promoError`, and `totalChanged`. Use `useMemo` to compute `subtotal`, `discount` (percent or fixed promo types), `tax` (TAX_RATE=0.08), `shipping` ($5.99), and `total`. Implement `updateQty` (useCallback) with item removal when qty reaches 0. Implement `applyPromo` (useCallback) supporting demo codes `FIFA20` (20% off) and `SAVE10` ($10 off) with error timeout. Use framer-motion `AnimatePresence` for animated expand/collapse of the summary panel (ChevronDown toggle) and item entry/exit animations. Render icons from lucide-react: ShoppingBag, ChevronDown, Minus, Plus, X, Check, Truck, PackageOpen. Import `CheckoutOrderSummary.css`.

As a frontend developer, implement the CheckoutShippingForm section for the Checkout page. Build the `CheckoutShippingForm` component with `SAVED_ADDRESSES` (Home and Office presets for Alex Johnson) and `COUNTRIES` dropdown (8 countries). Manage `useState` for `selectedSaved`, `form` (INITIAL_FORM with fullName, email, addressLine1, addressLine2, city, state, country, postalCode), `errors`, `saveForLater`, and `submitted`. Implement `validateField` (useCallback) with field-specific validation rules (name length, email regex, address/city/state/postal min-length). Implement `applySavedAddress` (useCallback) to toggle saved address selection and pre-fill form fields while preserving email. Implement `handleChange` (useCallback) with live error re-validation after first submission attempt. Render saved address cards as selectable tiles, a full address form with labeled inputs and inline error messages, a 'Save for later' checkbox, and a submit button that triggers full-form validation. Import `CheckoutShippingForm.css`.

As a frontend developer, implement the CheckoutPaymentMethod section for the Checkout page. Build the `CheckoutPaymentMethod` component with `PAYMENT_METHODS` array (card, paypal, wallet, bank) each containing inline SVG icons. Include `SAVED_CARDS` (Visa 4242, Mastercard 8881) for quick card selection. Use `useState` for selected payment method and card form fields. Apply framer-motion `AnimatePresence` with `cardDetailsVariants` (height: 0→auto, opacity animated) for smooth expand/collapse of the credit card detail form when 'card' method is selected. Apply `optionHover` motion variants (`scale: 1.02` on hover, `scale: 0.985` on tap) on payment option tiles. Render saved card tiles as selectable options within the card method panel. Import `CheckoutPaymentMethod.css`.

As a frontend developer, implement the CheckoutSecurityBadges section for the Checkout page. Build the `CheckoutSecurityBadges` component using `useRef` and `useEffect` with an `IntersectionObserver` (threshold: 0.3) to trigger `setVisible(true)` on scroll-into-view (observe once, then unobserve). Render three badges: SSL (256-bit SSL / Encrypted with lock SVG), Secure Payment (PCI Compliant with shield SVG), and 30-Day Guarantee (Money Back with badge SVG). Apply framer-motion `motion.div` with `badgeVariants` (hidden: opacity 0, y 12 → visible: opacity 1, y 0) using staggered `delay: i * 0.12` and custom ease `[0.25, 0.46, 0.45, 0.94]`. Apply `trustVariants` for the trust tagline with delay 0.55s. Add `whileHover={{ scale: 1.03 }}` with spring transition on each badge. Use `AnimatePresence` gating on `visible` state. Render dividers (`csb-divider`) between badges. Import `CheckoutSecurityBadges.css`.

As a frontend developer, implement the Navbar section for the Confirmation page. This reuses the shared checkout Navbar component (may already exist from Checkout page) with `activeStep='confirm'` prop. The component renders a 3-step progress indicator using STEPS array (Cart→Checkout→Confirmation) with lucide-react icons (ShoppingCart, CreditCard, CheckCircle2). Uses `useState` to track active step, computes `safeIndex` and `activeIndex` to apply `is-done`, `is-active` CSS state classes. Completed steps render a `<Check />` icon instead of the step icon. Includes `nv-connector` spans with `is-filled` class for completed connectors. Also renders MemeMerch logo with `<Shirt />` icon and a 'Back to cart' link with `<ChevronLeft />`. Import from '../styles/Navbar.css'.

As a Backend Developer, implement the payment processing integration in FastAPI. POST /api/v1/payments/initiate — accepts order_id and payment_method (card, paypal, wallet, bank), integrates with a payment gateway (Stripe or equivalent), creates a payment intent/session, and returns client_secret or redirect_url. POST /api/v1/payments/confirm — receives payment confirmation webhook or client token, updates order status to 'paid', and returns updated order status. Include idempotency key handling and secure storage of transaction IDs (never store raw card data). This endpoint is required by CheckoutFinalCTA and CheckoutPaymentMethod sections.

As a Tech Lead, verify the end-to-end integration between the MemeUpload frontend section and the Meme Upload backend API (/api/v1/memes/upload). Ensure the file drag-and-drop and selection flow correctly POSTs multipart/form-data to the backend, error responses (invalid type, size exceeded) are surfaced in the UI status messages, and on success the returned file_url is stored in global state and passed as memeDataUrl prop to MerchCarousel for live texture preview. Confirm CORS headers are correct and the 1200ms simulated delay is replaced by the real API call.

As a Tech Lead, verify the end-to-end integration between the ProductSelector frontend section and the Products Catalog backend API (/api/v1/products). Ensure the product grid is populated from the API response instead of hardcoded data, out-of-stock products disable the add-to-cart button correctly, add-to-cart actions update the global cart state, and the OrderSummary panels on both Carousel and Confirmation pages reflect real cart contents. Confirm price formatting, discount badges, and color/size selection all work with live data.

As a Backend Developer, complete the Meme Upload API endpoint wiring by depending on the file storage service. Update task 9b5c6915 dependency chain: POST /api/v1/memes/upload must use StorageService for file persistence and return a publicly accessible file_url (e.g., /uploads/{filename}). Ensure MIME validation (image/jpeg, image/png, image/webp) and 10MB size cap are enforced before storage. Note: the MemeUpload frontend section (2068619a) should depend on this backend task for real API integration instead of the simulated 1200ms delay.

As a Tech Lead, verify the end-to-end integration between the Global Cart and Meme State (c712994b) and the Orders API (POST /api/v1/orders). Ensure: cartItems from the Zustand/Context store are correctly mapped to order line items (product_id, name, size, color, quantity, unit_price); the setOrderId action is called with the order_id returned from POST /api/v1/orders; and the currentOrderId flows through to the Confirmation page to fetch live order data via GET /api/v1/orders/{order_id}. Verify cart is cleared after successful order creation.

As a frontend developer, implement the CheckoutFlow section for the Carousel page. This section renders a 4-step checkout wizard (STEPS: ['Customer', 'Shipping', 'Payment', 'Review']) with `useState` tracking `currentStep` and form field values. A `ConfettiCanvas` sub-component mounts a Three.js scene using `useRef` and `useEffect` — creating 60 `THREE.Mesh` instances from `THREE.PlaneGeometry(0.12, 0.12)` with `MeshBasicMaterial` in 6 brand colors (0x3B82F6, 0xF59E0B, 0xEF4444, 0x10B981, 0xFBBF24, 0x1E3A8A), each with `userData` velocity/spin fields animated per frame (vy downward drift, y reset to top when below -5). The renderer uses `alpha: true`, appends its `domElement` to `mountRef`, and is displayed on the final confirmation step. Three `SHIPPING_OPTIONS` (Standard $4.99, Express $14.99, Overnight $29.99) and three `PAYMENT_METHODS` (Card, PayPal, Apple Pay) are rendered as selectable radio-style cards. Framer Motion `AnimatePresence` animates step transitions. Uses `.cf-*` CSS class prefix.

As a frontend developer, implement the CheckoutFinalCTA section for the Checkout page. Build the `CheckoutFinalCTA` component with `useState` for `acceptedTerms`, `isLoading`, and `termsError`. Implement `toggleTerms` (useCallback) that clears `termsError` on acceptance. Implement `handlePlaceOrder` (useCallback) that validates `acceptedTerms` (sets `termsError` if false) then sets `isLoading(true)` to trigger a loading state. Render a total summary row (`cfc-total-row`) with `$59.99` via `whileInView` motion fade-in (opacity 0→1, y 12→0, ease [0.4,0,0.2,1]). Render an accessible terms checkbox (`role='checkbox'`, `aria-checked`, `tabIndex={0}`, keyboard Enter/Space support) with `AnimatePresence mode='wait'` animating between checked/unchecked states (scale 0.7↔1, opacity 0↔1). Apply `cfc-checkbox--error` class on validation failure. Include links to `/Terms` and `/PrivacyPage` with `e.stopPropagation()`. Import `CheckoutFinalCTA.css`.

As a frontend developer, implement the ConfirmationHeader section for the Confirmation page. Renders a static `<section className='ch-root'>` with a `<CheckCircle2 strokeWidth={2} />` lucide icon inside `ch-status-icon` span, plus a `ch-meta` div containing two spans: `ch-label` ('Order placed successfully') and `ch-order-number` displaying hardcoded order number 'MM-2025-08472' prefixed with '#'. No state or interactivity. Import from '../styles/ConfirmationHeader.css'.

As a frontend developer, implement the OrderSummary section for the Confirmation page (distinct from Carousel's OrderSummary). Renders a read-only items list from the hardcoded ORDER_ITEMS array (Classic Hoodie L $49.99 qty:1, Premium Tee M $29.99 qty:2, Limited Edition Hoodie XL $64.99 qty:1). Computes `itemCount` via `reduce`. Each item renders inside `os-item` with: `os-thumb` div containing `os-thumb-placeholder` showing abbr labels (FH/PT/LE), `os-item-info` with name and meta (size + unit price via `formatPrice`), `os-qty-badge` showing `×{qty}`, and `os-item-price` showing line total. Header shows inline SVG cart icon and dynamic item count label. No quantity controls — confirmation view only. Import from '../styles/OrderSummary.css'.

As a frontend developer, implement the OrderDetails section for the Confirmation page. Renders a pricing breakdown card with hardcoded LINE_ITEMS array (Subtotal $64.99, Tax 8.5% $5.52, Shipping Free with `isPositive: true`). Maps LINE_ITEMS to `od-row` divs, applying `is-positive` modifier class on the value span for the Free shipping item. Renders an `od-divider` separator then a Grand Total row with `od-row is-total` and `od-row-val is-highlight` classes showing '$70.51'. Includes a trust badge at bottom with `<ShieldCheck />` lucide icon and encrypted payment copy inside `od-trust` div. Import from '../styles/OrderDetails.css'.

As a frontend developer, implement the ShippingInfo section for the Confirmation page. This is the most complex section, featuring a full 3D merch carousel built with `@react-three/fiber` Canvas, `@react-three/drei` (OrbitControls, RoundedBox, MeshWobbleMaterial, Html), and `framer-motion`. MERCH_ITEMS array defines 5 items (Classic Hoodie, Premium Tee, Limited Edition Hoodie, Meme Match Tee, Stadium Hoodie) with hex color and accent values. `MerchCard` component uses `useRef` and `useFrame` for smooth position.y interpolation via `Math.pow(0.02, delta)` easing; active card floats up 0.12 units. Cards arranged in a circle at RADIUS=2.4 using sin/cos. `MeshWobbleMaterial` has higher factor (0.08) and speed (2) for active card. Active card shows `<Html>` label overlay. `MerchCarousel` group uses `useRef` for `targetAngle`/`currentAngle` smooth rotation interpolation and `useState` for activeIdx. Outer React component uses `useState` for activeIdx and `useRef` for container, wrapped in `<Suspense>`. Also includes shipping address display with lucide icons (MapPin, Truck, Clock, Mail, Phone, PackageCheck) for delivery details. Import from '../styles/ShippingInfo.css'.

As a frontend developer, implement the NextSteps section for the Confirmation page. Renders a static CTA section with a decorative `ns-accent-stroke` ring div (aria-hidden), an `ns-icon-ring` div containing `<CheckCircle2 />` lucide icon, an `ns-heading` h2 ('Your order is confirmed!'), a `ns-note` paragraph with confirmation email copy referencing 'fan@example.com' in a `<strong>` tag, an `ns-separator` div, and an `ns-actions` div with two links: a primary `ns-primary-btn` anchor to '/Carousel' with `<ShoppingBag />` icon ('Continue Shopping'), and a secondary `ns-secondary-link` anchor to '/Confirmation' with `<ClipboardList />` and `<ArrowRight />` icons ('View Order Status'). No state or interactivity. Import from '../styles/NextSteps.css'.

As a Tech Lead, verify the end-to-end integration between the CheckoutShippingForm frontend section and the Orders backend API. Ensure: the shipping form's validated address data (fullName, email, addressLine1, city, state, country, postalCode) is correctly serialized and included in the POST /api/v1/orders request body as shipping_address_json; the backend stores and echoes back the address in GET /api/v1/orders/{order_id}; and the ShippingInfo section on the Confirmation page renders the submitted address from live API data rather than static placeholders.

As a Tech Lead, verify the end-to-end integration between the Checkout page frontend sections (CheckoutShippingForm, CheckoutPaymentMethod, CheckoutFinalCTA, CheckoutOrderSummary) and the Orders/Payment backend APIs (/api/v1/orders, /api/v1/payments/initiate, /api/v1/payments/confirm, /api/v1/promo/validate). Ensure: promo code validation calls the backend and surfaces correct discounts; order creation POSTs cart items and shipping details and receives a real order_id; payment initiation uses the returned client_secret for card processing; on payment confirmation the order status updates and the user is redirected to the Confirmation page with the real order_number. Verify terms checkbox gating, loading states, and error handling.

As a Tech Lead, verify the end-to-end integration between the CheckoutPaymentMethod and CheckoutFinalCTA frontend sections and the Payment Gateway backend API (/api/v1/payments/initiate, /api/v1/payments/confirm). Ensure: the selected payment method (card, paypal, wallet, bank) is passed correctly to the initiate endpoint; the returned client_secret is used to complete card payment via the Stripe SDK on the frontend; payment confirmation webhook updates order status to 'paid'; and the user is redirected to the Confirmation page with the correct order_id. Verify error states (declined card, timeout) are surfaced in the UI.

As a Tech Lead, verify the end-to-end integration between the Confirmation page frontend sections (ConfirmationHeader, OrderSummary, OrderDetails, ShippingInfo, NextSteps) and the Orders backend API (GET /api/v1/orders/{order_id}). Ensure the real order_id from checkout is used to fetch live order data, the order number in ConfirmationHeader reflects the backend-generated MM-YYYY-NNNNN format, OrderSummary renders actual purchased items (not hardcoded), OrderDetails shows real pricing breakdown including applied promo discount, and ShippingInfo displays the submitted shipping address. Replace all hardcoded values (fan@example.com, MM-2025-08472, static items) with API-driven data.