Project Description
We are building FindAutoPartz, a premium automotive ecommerce + service marketplace. This is not a basic spare-parts site. It is a full automotive ecosystem with parts ecommerce, dealer listings, customer accounts, cart/checkout, payments, shipping, customer dashboard, garages, custom shops, Build Studio, requests, quotes, jobs, campaigns, reviews, future AI automation, and admin-controlled branding.
We already have a custom PHP/MySQL backend with a large admin panel and many API endpoints. The current WordPress/Elementor frontend is not suitable anymore, so we want a serious modern customer-facing frontend rebuild using Next.js.
Goal:
Build a premium, interactive, production-quality frontend and connect it properly to the existing backend APIs. Backend fixes required for customer-facing flows must also be handled during integration.
Required Tech:
Next.js, React, TypeScript, Tailwind CSS, Framer Motion, reusable components, central API client, AuthProvider/session handling, custom PHP/MySQL API integration, and mobile-first responsive design.
Backend Info:
The backend is not Laravel, Node.js, or WordPress. It is a custom PHP/MySQL system with API files, admin panel, customer/dealer APIs, garage/custom shop modules, payments, shipping foundation, Build Studio, requests/quotes/jobs, campaigns, reviews, notifications, saved/recent parts, and AI-related foundations.
Backend/API Requirement:
Before deep frontend work, create an endpoint map showing endpoint name, purpose, method, parameters, auth/public status, response format, working/broken/missing/needs-fix status, frontend page usage, and required backend fixes.
Frontend must use a central API client. Do not hardcode random API calls across pages.
Customer auth/session must be tested early and must work globally across header, dashboard, cart, checkout, saved parts, recently viewed, orders, requests, quotes, jobs, Build Studio, reviews, and notifications.
Frontend Scope:
1. Public Website + Global Layout
Home, About, Contact, FAQ, Terms, Privacy, Refund/Return Policy, blog listing/detail, 404 page, maintenance page, premium header/footer, desktop nav, mobile drawer, search, category navigation, login/customer menu, cart/dashboard shortcuts, dynamic branding/theme-ready structure, and smooth responsiveness. Design must feel premium, modern, automotive, and interactive.
2. Product Discovery / Ecommerce
Buy Parts/Shop, search results, category page, brand page, campaigns/deals page, product cards, search, filters, sorting, pagination/load more, vehicle make/model filter, price/brand/category/stock filters, mobile filter drawer, campaign price badges, stock status, dealer info, save/wishlist, compare, quick add to cart where safe, skeleton/empty/error states.
3. Product Detail
Product gallery, title/specs, price, discount/campaign price, stock status, dealer info, compatibility/fitment, reviews, related products, price history if supported, add to cart, save/wishlist, compare, recently viewed tracking, review submission, sticky purchase panel, garage fitting CTA, custom shop CTA, and Build Studio CTA.
4. Comparison / Personalization
Compare button on listing/detail, comparison page, saved parts page, recently viewed page, save/unsave, saved searches, stock alerts, product recommendations UI, and proper empty states.
5. Cart
Cart page, item cards, quantity update, remove item, dealer grouping if needed, subtotal, shipping estimate, VAT/tax, promo code, total, empty cart state, continue shopping, and checkout CTA.
6. Checkout / Payments
Checkout page, customer details, shipping address, shipping quote, payment method selection, PayPal/Ziina support if configured, promo validation, VAT/tax display, order summary, order creation, payment redirect/verification, order success/failed pages, and retry payment if supported.
No fake payment success. Payment status must come from backend verification.
7. Shipping
Shipping must be included properly. Frontend should show shipping quote in cart/checkout, shipping amount, dealer-grouped shipping if needed, shipping mode/carrier options if supported, tracking status in order detail if available, and clear shipping errors.
Backend should confirm/fix shipping_quote API, shipping calculation, order/payment total integration, and carrier structure for Aramex/DHL/FedEx/UPS if configured. Do not fake live carrier integration if real credentials are unavailable.
8. Customer Dashboard
Dashboard should feel like a premium SaaS control center. Include dashboard overview, orders/order details, saved parts, recently viewed, saved searches, stock alerts, notifications, messages/support, reviews submitted, profile/settings, address/shipping info, payment tracking, returns/issues/disputes, requests, quotes, jobs, and Build Studio requests.
9. Orders / Returns / Disputes / Support
Order status, payment status, items list, shipping amount, VAT/tax, invoice link, cancel order, retry payment, return request, order issue creation, dispute creation and details/messages, support/messages, notifications, and mark-as-read.
10. Garages Marketplace
Garages must be a real service marketplace, not just a homepage section. Include garage listing/detail, search/filter, cards, services/specialties, city/location, contact/WhatsApp, ratings/reviews, verified badges, request quote CTA/form, product detail “Need fitting?” link, and Build Studio partner routing.
11. Custom Shops Marketplace
Include custom shops listing/detail, search/filter, cards, services/specialties, city/location, logo/cover/description, ratings/reviews, verified badges, custom build request form, and links from product detail and Build Studio.
12. Build Studio
Build Studio should be one of the strongest and most interactive parts of the frontend. Include landing page, multi-step wizard, vehicle selection, build type, budget, customization preferences, performance/service preferences, package selection, partner routing, live build summary, progress indicator, animated steps, submit request, success page, and dashboard tracking.
13. Requests / Quotes / Jobs
Garages, custom shops, and Build Studio services are request/quote/job flows, not normal cart products. Include create request, request details, quote details, approve/reject quote, deposit payment if supported, job progress tracking, final payment if supported, completion confirmation, My Requests, My Quotes, My Jobs, job timeline/progress, payment states, and error states.
14. Reviews / Campaigns / Promo Codes
Product review listing/submission, garage/custom shop reviews, campaigns/deals page, campaign cards/products page, campaign pricing on listing/detail, promo code input in cart/checkout, promo success/error states, and invalid/expired promo handling.
15. Notifications / Messages
Notification dropdown or dashboard section, mark as read, message/support thread UI, customer support/dealer message UI, loading/empty/error states.
16. Theme / Branding System
Frontend must be theme-ready and able to later connect to admin-controlled branding/settings: logo, favicon, brand name, primary/secondary/accent colors, typography, border radius, shadows, button styles, cards, inputs, dropdowns, modals, badges, tabs, toasts, alerts, skeletons.
17. AI Integration / AI Foundation
AI is very important. We do not want a fake chatbot. We want the best possible AI-ready architecture. Existing AI modules are only partially completed, so AI should be designed cleanly for future expansion.
Required now: AI Parts Finder UI, natural language “Tell us what you need” assistant, AI compatibility checker UI, AI recommendations UI, AI Build Studio suggestions UI, AI help widget states, clean separation between AI frontend UI and backend AI service, provider-flexible structure for OpenAI/Claude/Gemini/OpenRouter, secure API key config pattern, and a structure so AI can use platform data first.
AI must not be hardcoded or fake. Placeholder/foundation AI must be clearly marked. Full advanced AI automation/agent system can be separate, but the architecture now must support it later.
18. Premium Design / Interactivity
Frontend must feel high-end, interactive, automotive-focused, and mobile-first. Include smooth transitions, Framer Motion animations, scroll reveal, hover card lift, interactive product cards, modal animations, mobile drawer animation, skeleton loading, premium empty/error/success states, sticky purchase panel, dashboard widgets, Build Studio step animations, and micro-interactions for save/compare/cart.
19. Backend Fixes During Integration
This is not a full backend rewrite, but backend fixes required for frontend flows must be handled: auth/session/cookies/CORS, API response consistency, product/search/filter APIs, saved/recent/compare APIs, cart/order APIs, shipping quote/carrier flow, payment create/capture/verify flows, promo/campaign APIs, customer dashboard APIs, notifications/messages APIs, returns/issues/disputes APIs, garage/custom shop APIs, Build Studio APIs, requests/quotes/jobs APIs, job payment APIs, theme/public config APIs, and error handling/logging.
Do not modify .env, .secrets, DB credentials, PayPal/Ziina keys, or production payment settings without approval.
Not Included Unless Separately Agreed:
Admin/dealer/garage/custom shop dashboard redesign, mobile app, full backend rewrite, and white-label reseller system.
Final Delivery:
Must include source code, staging/live demo, deployment instructions, API integration notes, backend fix log, testing report, completed features list, pending/future features list, and tested main flows: auth/session, products, cart, shipping, checkout, payments, dashboard, garages, custom shops, Build Studio, requests/quotes/jobs, job payment, reviews, and theme foundation.
We want a production-quality platform, not only a UI demo