polar-architecture

As a customer, I want to see an interactive blueprint-themed homepage (Landing v2 design) so that I get a memorable first impression of Navjeevan Supershopee. Implement the pencil-sketch retail store animation, scroll-triggered blueprint-to-store transition, hover effects showing product details, drawing-pin button micro-interactions, and the hero section with category highlights. Implement based on the existing Landing (v2) JSX design. Links to Login and Register pages.

As a customer or admin, I want to use the Login page (Login v2 design) to sign in via Mobile OTP or Email & Password so that I can access my portal securely. Implement the two-column layout: left brand panel with deep blue gradient and blueprint illustration, right auth form panel with tab switcher (Mobile OTP / Email & Password), OTP input flow, show/hide password toggle, Forgot Password link, Guest access option, and Admin Portal link. Use Firebase Auth for OTP. Implement based on existing Login (v2) JSX design.

As a new customer, I want to use the Auth/Register page (Auth v2 design) to create an account via Mobile OTP or Email & Password so that I can start shopping. Implement registration form with OTP verification flow, Firebase Auth integration, field validation with inline error messages, and redirect to Home page on success. Implement based on existing Auth (v2) JSX design.

As a logged-in customer, I want to use the Home page (Home v2 design) to browse product categories and featured items so that I can quickly find what I need. Implement category grid, featured products carousel, search bar linking to Products page, cart icon with item count badge, and navigation header. Implement based on existing Home (v2) JSX design. Links to Products, Product Detail, and Cart pages.

As a customer, I want to use the Products page (Products v2 design) to search, filter, and browse the full product catalogue so that I can find specific items. Implement search bar, category filter chips, stock status filter, sort controls (price, rating, popularity), product grid with cards showing name, price, rating, and Add to Cart button. Blueprint-style loading state. Implement based on existing Products (v2) JSX design. Links to Product Detail and Cart.

As a customer, I want to use the Product Detail page (Product Detail v2 design) to view full product information, ratings, and reviews, and add items to my cart so that I can make an informed purchase decision. Implement product image gallery, name, SKU, price in INR, stock indicator, quantity selector, Add to Cart button with animation, ratings breakdown, review list, and review submission form. Implement based on existing Product Detail (v2) JSX design.

As a customer, I want to use the Cart page (Cart v2 design) to review, update, and remove items before proceeding to checkout so that I have full control over my order. Implement cart item list with quantity controls, price breakdown (subtotal, taxes, total in INR), empty cart illustration, real-time stock validation indicators, and Proceed to Checkout CTA. Implement based on existing Cart (v2) JSX design. Links to Checkout page.

As a customer, I want to use the Checkout page (Checkout v2 design) to enter delivery details and make a payment via Razorpay so that my order is placed securely. Implement order summary panel, address form, payment method selector (UPI, cards, net banking), Razorpay payment gateway integration, payment success and failure handling, and order confirmation screen. Implement based on existing Checkout (v2) JSX design.

As a customer, I want to use the Orders page (Orders v2 design) to track the real-time status of my orders and view order history so that I know exactly when my order is ready. Implement order status timeline (Placed → Preparing → Ready → Served), order history list, order details drawer, invoice PDF download button, and status badge colour coding. Implement based on existing Orders (v2) JSX design.

As an admin, I want to use the Dashboard page (Dashboard v2 design) to view analytics — sales trends, best sellers, low inventory alerts, and peak order times — so that I can make informed business decisions. Implement stat summary cards (total sales, order count, revenue, low-stock count), sales trend chart, best-selling products list, peak order times heatmap, and low inventory alert banners. Implement based on existing Dashboard (v2) JSX design.

As an admin, I want to use the Inventory page (Inventory v2 design) to add, edit, update stock levels, and auto-hide out-of-stock products so that the Customer Portal always shows accurate availability. Implement the product table with status badges, visibility toggle, inline edit and delete actions, Add Product modal with image upload, low-stock alert panel, stats bar, and search/filter toolbar. Implement based on existing Inventory (v2) JSX design.

As an admin, I want to use the Orders page (Orders v2 design) to view all incoming orders in a sequential timestamp view and update their statuses so that customers receive timely service. Implement order list with timestamp sorting, status update controls (Placed → Preparing → Ready → Served), order detail drawer, search and filter by status/date, and real-time refresh indicator. Implement based on existing Orders (v2) JSX design for the admin context.

As an admin, I want to use the Reports page (Reports v2 design) to generate and export reports on sales, orders, best sellers, revenue by category, and payment mode breakdown so that I can analyse business performance. Implement report type selector, date range picker, report preview with charts and tables, PDF export button, Excel export button, and summary KPI cards. Implement based on existing Reports (v2) JSX design.

As a backend developer, I want to implement FastAPI endpoints for cart management and checkout so that customers can add/remove items, validate stock in real time, and place orders. Endpoints: GET /cart, POST /cart/items, PUT /cart/items/{id}, DELETE /cart/items/{id}, POST /orders (place order with stock validation), POST /payments/initiate (Razorpay order creation), POST /payments/verify (webhook signature validation). Include INR currency handling and payment failure rollback.

As a backend developer, I want to implement FastAPI endpoints for inventory management so that admins can update stock levels, trigger low-stock alerts, and auto-hide out-of-stock products. Endpoints: GET /admin/inventory (with stock status filters), PUT /products/{id}/stock, GET /admin/inventory/low-stock-alerts. Include inventory log recording on every stock change and threshold-based alert logic.

As a backend developer, I want to implement FastAPI endpoints for product ratings and reviews so that customers can submit reviews and admins can moderate them. Endpoints: GET /products/{id}/reviews, POST /products/{id}/reviews, PUT /admin/reviews/{id} (approve/reject), DELETE /admin/reviews/{id}. Include average rating calculation and review validation (one review per order item per customer).

As a backend developer, I want to implement role-based access control (RBAC) so that admin-only endpoints are protected and customers cannot access admin functionality. Implement JWT middleware with role claims (customer, admin), FastAPI dependency injection guards on all /admin/* routes, Firebase Auth token verification, and frontend route guards that redirect unauthorised users to Login. Include bcrypt password encryption for email/password auth.

As a backend developer, I want to implement FastAPI endpoints for order tracking and management so that customers can track order status and admins can update order statuses. Endpoints: GET /orders (customer history), GET /orders/{id}, GET /orders/{id}/invoice (PDF generation), PUT /orders/{id}/status (admin), GET /admin/orders (all orders with filters and timestamp sort). Include invoice PDF generation using a Python PDF library.

As a backend developer, I want to implement FastAPI endpoints for admin reports and analytics so that admins can generate and export business performance data. Endpoints: GET /admin/reports/sales-summary, GET /admin/reports/orders-count, GET /admin/reports/best-sellers, GET /admin/reports/revenue-by-category, GET /admin/reports/payment-breakdown, GET /admin/reports/export?format=pdf|excel, GET /admin/analytics/sales-trends, GET /admin/analytics/peak-order-times. Include PDF and Excel export generation.

As a frontend developer, I want to wire all designed pages to the live FastAPI backend so that real data flows through the application end-to-end. Replace all mock/static data in Landing, Home, Products, Product Detail, Cart, Checkout, Orders, Dashboard, Inventory, and Reports pages with API calls using a shared Axios/fetch service layer. Implement loading states, error handling toasts, and auth token injection (JWT) for protected routes. Configure environment-based API base URLs.