Project Description
We are building FindAutoPartz, a premium automotive ecommerce platform. This is not a simple spare parts website or basic product listing marketplace.
It is a full automotive ecosystem with ecommerce, dealer selling, customer accounts, cart, checkout, payments, garages, custom shops, Build Studio, service requests, quotes, jobs, reviews, campaigns, promo codes, dashboards, admin-controlled branding, and AI-powered features.
We already have an existing custom PHP/MySQL backend and admin panel with many APIs/modules partially built. The backend is not fully clean or production-ready yet. Some flows are incomplete, inconsistent, or broken and need to be audited, cleaned, fixed, improved, and completed.
The current public frontend is WordPress/Elementor and has become messy due to proxy files, customer session/login issues, caching problems, and mixed API handling. We do not want to continue patching WordPress as the main frontend.
Goal:
Build a new premium frontend from scratch, connect it properly to the existing backend, clean up backend flows, complete missing flows, and prepare the platform to become buyer-ready / production-ready.
The developer must be comfortable using AI coding tools such as Cursor, Claude, Gemini, Kimi, Antigravity, Cline, Copilot, or similar tools to speed up development. AI can be used, but final code must be clean, reviewed, tested, maintainable. The platform itself should also include AI-powered frontend/backend features where possible.
Main platform includes ecommerce, dealer product management, customer accounts, cart, checkout, orders, payments, VAT/tax, promo codes, deals, reviews, saved/recent parts, dashboards, garages, custom shops, Build Studio, service requests, quotes, jobs, deposit/final payment, notifications, search, filters, AI assistant/search, admin-controlled branding, and future white-label readiness.
Preferred frontend stack:
Next.js, React, TypeScript, Tailwind CSS, shadcn/ui or similar, Framer Motion or similar, reusable components, central API client, central AuthProvider, central theme/branding provider, responsive mobile-first design, and proper loading/empty/error/success states.
Backend stack:
Existing custom PHP backend, MySQL database, admin panel, API files, and dealer/admin/customer modules.
Do not use:
WordPress or Elementor as final frontend, PHP proxy files for frontend auth, fake localStorage-only login, scattered auth checks, duplicated API calls, basic template UI, untested payment flow, fake connected screens, hardcoded one-brand-only design, or random backend rewrites without understanding the system.
Frontend design:
The frontend must look extremely premium, modern, interactive, and high-end. It should feel like a premium automotive technology platform, not a basic ecommerce store.
Design should include:
- Multi-colour theme system
- Admin-controlled colours, brand name, logo, favicon, accents, button styles, card radius, typography, and theme tokens
- Dynamic theme loading from backend/admin if possible
- Beautiful responsive layouts
- Smooth animations and premium transitions
- Interactive product cards and filters
- Premium dashboard widgets
- Hover effects, scroll animations, glass/card effects, and 3D-like depth where suitable
- High-quality mobile navigation and premium checkout
- Strong visual hierarchy, clean luxury automotive look, polished loading/empty/error states
The site should feel immersive, like entering a premium interactive automotive showroom. Sections can zoom, slide, reveal, or move smoothly, but animations must stay professional.
AI-assisted development:
AI may be used for components, UI variations, refactoring, TypeScript types, API debugging, backend improvements, tests, code review, API documentation, bug finding, cleanup, and UI/UX improvements.
Developer remains responsible for quality. AI-generated code must be reviewed. No messy AI files, duplicate components everywhere, random hacks, or unsafe changes to backend secrets, .env, database config, PayPal, Ziina, or payment keys.
AI features inside platform:
Frontend AI may include AI parts finder, natural language search, “tell us what you need” assistant, product recommendations, Build Studio suggestions, customer help widget, garage/custom shop request helper, fitment suggestion UI, and chatbot UI. Backend/admin AI may include admin/dealer AI assistant, product description generator, support helper, operations insights, marketplace health summary, campaign suggestions, request summarizer, and quote/job summary generator.
Frontend pages/modules needed:
1. Home:
Premium hero, AI-style parts finder/search, featured parts, categories, campaigns/deals, garages, custom shops, Build Studio CTA, how it works, trust/metrics, testimonials/reviews, premium footer, dynamic branding/theme support, strong animations.
2. Buy Parts / Product Listing:
Search, filters, sort, brand/category/price/vehicle filters, product cards, campaign pricing, save, compare, add to cart, stock status, dealer info, skeletons, empty states, mobile filter drawer, pagination/load more.
3. Product / Part Detail:
Image gallery, specs, price, discount/campaign price, dealer details, stock, compatibility, warranty, reviews, related parts, save, compare, add to cart, service routing to garage/custom shop/Build Studio, sticky purchase panel if suitable.
4. Cart and Checkout:
Cart item cards, quantity update, remove item, cart summary, VAT/tax calculation, promo code, shipping estimate, protected checkout, customer/shipping/contact details, payment method selection, order summary, secure checkout UI, PayPal/Ziina flow if supported, success/failure/return pages, no fake payment success.
5. Customer Login/Register:
Email/password login, Google login if possible, registration, email verification, forgot password if supported, Turnstile/reCAPTCHA, clean errors, loading states, redirect after login, one central customer session system, header updates after login.
6. Customer Dashboard:
Premium sidebar/dashboard, metrics, orders, order details, saved parts, recently viewed, requests, quotes, jobs, notifications, reviews, profile, quick actions, payment/order status, service/build tracking.
7. Garages and Custom Shops:
Public directories, search/filters, cards, location info, service highlights, ratings/reviews if available, request quote CTA, partner profile feel.
8. Build Studio:
Highly interactive multi-step wizard with vehicle selection, build type, budget, exterior/interior preferences, performance/customization preferences, package selection, partner routing, live summary, submit request CTA, request creation flow, premium animations.
9. Customer Requests / Quotes / Jobs:
Customer submits service/build request → admin/partner creates quote → customer accepts/rejects → deposit payment if required → job starts → status/progress updates → final payment/completion. Customer must track everything in dashboard.
10. Reviews, Promo Codes, Campaigns, Theme, Security:
Product/dealer/garage/custom shop reviews if supported, review submission, promo code input, campaign/deal pricing, discount badges, admin-managed discounts, Google login if possible, Turnstile/reCAPTCHA, secure sessions, protected routes, clean logout, proper errors, rate limiting where needed, secure payment flow, and no secret key exposure.
Admin-controlled branding must include brand name, logo, favicon, primary/secondary/accent colours, button style, card radius, typography if possible, and global theme tokens. Frontend must not hardcode one fixed brand style.
Backend work required:
Audit APIs, map endpoints, identify incomplete/broken flows, fix broken APIs, add missing APIs where needed, fix CORS/session/cookie issues for direct frontend API calls, complete order/cart/checkout, payments, request/quote/job flow, garage/custom shop/Build Studio flow, review promo/reviews/campaigns, improve API response consistency, remove duplicated/broken logic where safe, add validation/error handling, and ensure frontend/backend work together without breaking the admin panel.
Backend cleanup may include standardizing API responses and auth/session helpers, fixing inconsistent customer sessions, require/include paths, repeated code blocks, unsafe/fragile code, poor errors/logs, and making endpoints predictable while keeping existing admin/dealer features safe.
Important:
Do not delete files blindly. Do not modify .env, .secrets, DB credentials, PayPal keys, Ziina keys, or production secrets without permission. Do not rewrite the backend from zero unless agreed.
Key backend flows to complete:
Customer auth must support login, register, check, logout, Google login if possible, Turnstile/reCAPTCHA, protected routes, and consistent session/cookie/CORS behavior. Login once must work across header, dashboard, cart, checkout, saved parts, orders, requests, quotes, and jobs. Ecommerce must support listing, filters, detail, images, stock, dealer info, campaign price, save/recent/reviews/related/compare. Cart/checkout must support add/remove/update, summary, VAT/tax, promo, shipping estimate, order creation, multi-dealer grouping if needed, payment selection, success/failure, and status update. Payments must support PayPal/Ziina create, redirect, verification, return URLs, duplicate payment protection, and no fake success. Service marketplace must support garages, custom shops, Build Studio, request, quote, approval/rejection, deposit/final payment, job tracking, and dashboard tracking.
Required deliverables:
Backend/API audit, working/broken API list, backend changes list, new Next.js frontend, central API client, central AuthProvider, theme/branding system, premium responsive UI, working auth/session, product listing/detail, cart, checkout/order flow, dashboard with real data where possible, garages/custom shops/Build Studio, request/quote/job flow, reviews/promo/campaign support, payment flow review/fix, AI feature foundation.