Next.js 14 Frontend + WooCommerce Backend Architecture Spec
এই মাস্টার ডকুমেন্টটি আমাদের UI/UX ডিজাইনার, ফ্রন্টএন্ড ডেভেলপার এবং AI ডিজাইনিং এজেন্টদের জন্য তৈরি করা হয়েছে। আমাদের আর্কিটেকচারটি একটি ইউনিভার্সাল হেডলেস ই-কমার্স ইঞ্জিন। ডিজাইনারকে কোনো বাঁধাধরা লেআউটে আবদ্ধ রাখা হচ্ছে না—হিরো সেকশন, ব্যানার স্লাইডার, কালার প্যালেট, টাইপোগ্রাফি ফন্ট, প্রোডাক্ট কার্ড স্টাইল কিংবা যেকোনো নতুন কাস্টম সেকশন আপনি ব্র্যান্ডের রুচি অনুযায়ী যেভাবে ইচ্ছা সেভাবে সম্পূর্ণ নতুন রূপ দিয়ে রি-ডিজাইন করতে পারেন। আমাদের পক্ষ থেকে আপনার ডিজাইনে ১০০% পূর্ণ স্বাধীনতা (Full Creative Freedom) দেওয়া হচ্ছে।
আপনার ডিজাইনকে সচল ও সফল করার জন্য শুধু একটি বিষয় নিশ্চিত করতে হবে: আমাদের প্রাইমারি রুলস (Primary Rules)—যেমন নির্দিষ্ট ইউআরএল স্লাগ, কার্ট ও চেকআউট স্ট্রাকচার এবং এসইও ও ফেসবুক পিক্সেল সার্ভার-সাইড ট্র্যাকিং মেকানিজম যেন হুবহু অপরিবর্তিত থাকে। ডিজাইন যেমনই হোক না কেন, এই ব্যাকএন্ড রুলস ঠিক রাখলে পুরো সিস্টেমটি স্বয়ংক্রিয়ভাবে নিখুঁতভাবে চলবে।
/cart ওভারভিউ পেজ।সিস্টেমের কাজের প্রবাহ (Data Flow & User Journey)
প্রাইমারি রুলস — ইউআরএল স্লাগ ও রাউটিং কনভেনশন (Primary Routing Rules)
যেকোনো নতুন ব্র্যান্ড বা ক্যাটাগরির জন্য UI/UX ডিজাইন বানানোর সময় সবচেয়ে গুরুত্বপূর্ণ নিয়ম হলো নিচের ইউআরএল স্লাগগুলো অক্ষুণ্ণ রাখা। যদি ডিজাইনার সঠিক স্লাগ ব্যবহার করে HTML তৈরি করে, তবে আমাদের কোডে কোনো রাউটিং ফাইল পরিবর্তন করতে হয় না।
/product/[slug]
কোর রুল: অলওয়েজ একবচনে /product/[slug] হবে, কখনোই /item/ বা /products/ বা আইডি কোয়েরি নয়।
/category/[slug]
কোর রুল: ক্যাটাগরির মূল স্লাগ সবসময় /category/[slug]। ওয়ার্ডপ্রেস টার্ম স্লাগের সাথে এটি সরাসরি মিলে যায়।
/brand/[slug] & /brands
কোর রুল: সিঙ্গেল ব্র্যান্ডের জন্য /brand/[slug] এবং অল-ব্র্যান্ডস গ্রিডের জন্য /brands।
/shop
কোর রুল: সমস্ত প্রোডাক্টের মেইন ক্যাটালগ ও ফিল্টার পেজের স্লাগ অলওয়েজ /shop।
/cart & [data-drawer="cart"]
কোর রুল: সাইডবার স্লাইডার ড্রয়ারের পাশাপাশি ডেডিকেটেড কার্ট পেজের স্লাগ হবে /cart।
/checkout
কোর রুল: সব পেজের "Buy Now" বা কার্টের "Proceed to Checkout" বাটন সোজা /checkout এ রিডাইরেক্ট করবে।
/order-received/[id]
কোর রুল: সফল অর্ডারের পর ক্রেতা এই পেজে যাবে। এখানে কুকি ভেরিফিকেশন দিয়ে কাস্টমারের তথ্য সুরক্ষিত রাখা হয়।
/page/[slug]
কোর রুল: ওয়ার্ডপ্রেস পেজের লাইভ কনটেন্ট Next.js এ /page/[slug] দিয়ে রেন্ডার হয়।
- যেকোনো প্রোডাক্টের জন্য কার্ডের বাটন বা লিঙ্কে
/product/{slug}ডাইনামিক রেফারেন্স রাখা। - ক্যাটাগরি মেনু বা লিঙ্কে
/category/{slug}ব্যবহার করা। - হেডারে কার্ট আইকন দিয়ে ক্লিক করলে স্লাইড-ইন সাইডবার কার্ট ড্রয়ার ওপেন হওয়ার অপশন রাখা।
- প্রোডাক্ট ডিটেইলস পেজে সাইজ (Sizes) এবং কালার (Colors) ভ্যারিয়েশন অপশন রাখা।
- চেকআউট পেজে মাত্র ১ পেজের মধ্যে নাম, ফোন, ঠিকানা ও ডেলিভারি এরিয়া ড্রপডাউন রাখা।
- ইউআরএল-এ
?p=123,/item/,/items/বা/products/দিয়ে লিংক তৈরি করা যাবে না। - চেকআউট পেজকে একাধিক ধাপে (Multi-step Wizard) ভাগ করা যাবে না—কাস্টমার এক পেজেই অর্ডার কনফার্ম করবে।
- কার্ট সিস্টেম ছাড়া শুধু হোয়াটসঅ্যাপ মেসেজ দিয়ে অর্ডার সীমাবদ্ধ করা যাবে না।
- মোবাইল ভিউপোর্টে সাইটের প্রস্থ ফিক্সড পিক্সেল দিয়ে ভেঙে ফেলা যাবে না।
কম্পোনেন্ট আর্কিটেকচার ও UI নির্দেশিকা (Component Architecture & UI)
নতুন যেকোনো ডিজাইনের ক্ষেত্রে UI/UX এজেন্টের স্বাধীনতা রয়েছে সম্পূর্ণ নতুন কালার প্যালেট, ইউনিক কার্ড শ্যাডোজ, আকর্ষণীয় টাইপোগ্রাফি এবং নতুন সেকশন যোগ করার।
/product/[slug] এবং ক্যাটাগরিতে /category/[slug] লিংক যুক্ত থাকে।
১. গ্লোবাল হেডার ও কার্ট সাইডবার ড্রয়ার (Header & Cart Drawer)
হেডারে ব্র্যান্ড লোগো, নেভিগেশন লিংক এবং একটি লাইভ কার্ট আইকন থাকবে। কার্ট আইকনে ক্লিক করলে পেজ রিফ্রেশ না হয়ে ডানদিক থেকে একটি আধুনিক Slide-Over Cart Drawer ভেসে উঠবে:
- কার্ট ড্রয়ার কনটেন্ট: কার্টে থাকা আইটেমের থাম্বনেইল, প্রোডাক্টের টাইটেল, নির্বাচিত সাইজ/কালার ভেরিয়েশন, ইউনিট প্রাইস,
+ও-কোয়ান্টিটি বাটন এবং ডিলিট আইকন। - সাবটোটাল ও চেকআউট বাটন: ড্রয়ারের নিচের অংশে লাইভ সাবটোটাল (৳) প্রদর্শিত হবে এবং একটি বড় "Proceed to Checkout" বাটন থাকবে যা সরাসরি
/checkoutপেজে নিয়ে যাবে। - ফুল ভিউ কার্ট অপশন: নিচে ছোট একটি "View Full Cart" লিংক থাকবে যা
/cartপেজে নিয়ে যাবে।
২. প্রোডাক্ট কার্ড ও ক্যাটালগ গ্রিড (ProductCard & Grid)
হোমপেজ, ক্যাটাগরি পেজ বা শপ পেজে প্রোডাক্ট ডিসপ্লে করার জন্য কার্ডে নিচের তথ্যগুলো থাকা বাঞ্ছনীয়:
- ফিচার্ড ইমেজ ও হোভার সোয়াপ: মূল ছবি এবং মাউস হোভার বা সোয়াইপে সেকেন্ডারি গ্যালারি ইমেজ প্রদর্শনের ব্যবস্থা।
- ব্যাজেস (Badges): ডিসকাউন্ট শতাংশ (
X% OFF), স্টক স্ট্যাটাস (Out of Stock), অথবা হট ট্যাগ (New,Sale)। - প্রাইসিং: কারেন্ট সেলস প্রাইস (বোল্ড) এবং যদি ডিসকাউন্ট থাকে তবে আগের রেগুলার প্রাইস (কেটে দেওয়া / Strike-through)।
- লিঙ্ক ও অ্যাকশন বাটন: পুরো কার্ড বা প্রোডাক্টের নাম ক্লিক করলে
/product/[slug]পেজে যাবে। কার্ডের নিচে সরাসরি "Order Now" বা "Add to Bag" বাটন থাকবে।
৩. প্রোডাক্ট ডিটেইলস পেজ ও ভেরিয়েশন সাপোর্ট (Sizes, Colors, Variations)
- সাইজ সিলেক্টর গ্রিড: কাস্টমার সাইজ বাটনে ক্লিক করলে তা হাইলাইট হবে। যে সাইজ স্টকে নেই (Out of stock), সেটি ডিসেবলড বা স্ট্রাইকথ্রু আকারে দেখাবে।
- কালার সিলেক্টর: কালার থাম্বনেইল বা সোয়াচ পিল। কালার পরিবর্তন করলে স্বয়ংক্রিয়ভাবে সেই ভ্যারিয়েন্টের ছবি ও দাম আপডেট হবে।
- স্টক ইন্ডিকেটর: ইন-স্টক বা অল্প স্টক থাকলে লাইভ ওয়ার্নিং (যেমন: "Only 2 pairs left in stock!").
- ডুয়েল অ্যাকশন বাটন: একটি "Add to Cart" বাটন (যা কার্ট ড্রয়ার ওপেন করবে) এবং একটি "Order Now / Buy Now" বাটন (যা সরাসরি সাইজ সহ চেকআউটে নিয়ে যাবে)।
৪. চেকআউট পেজ (Frictionless 1-Page Checkout)
বাংলাদেশের ই-কমার্স ও ক্যাশ-অন-ডেলিভারি (COD) অপারেশনের জন্য আমাদের চেকআউট ফর্মটি মাত্র ১ পেজে রাখা হয়েছে:
- ফর্ম ফিল্ডস: কাস্টমারের পুরো নাম, ১১ ডিজিটের মোবাইল নম্বর, সম্পূর্ণ ডেলিভারির ঠিকানা।
- ডেলিভারি এরিয়া সিলেক্টর: দুটি রেডিও বাটন—"ঢাকার ভেতরে (৳৭০)" এবং "ঢাকার বাইরে (৳১৩০)"। সিলেক্ট করার সাথে সাথে অর্ডারের টোটাল বিল স্বয়ংক্রিয়ভাবে ক্যালকুলেট হয়।
- অর্ডার সামারি টেবিল: নির্বাচিত প্রোডাক্ট, সাইজ, কালার, কোয়ান্টিটি এবং কুপন ডিসকাউন্ট কোড ইনপুট বক্স।
- ইন-ফ্লাইট লক (In-Flight Protection): প্লেস অর্ডার চাপলে বাটন "Processing..." হয়ে লক হয়ে যাবে যাতে কাস্টমার ডাবল ক্লিক করে ডুপ্লিকেট অর্ডার তৈরি করতে না পারে।
ডেটা কীভাবে আসে এবং এপিআই এন্ডপয়েন্টসমূহ (Data Fetching & APIs)
Next.js ফ্রন্টএন্ড কোনো সাধারণ স্ট্যাটিক এইচটিএমএল নয়; এটি ব্যাকগ্রাউন্ডে উকমার্সের লাইভ ডেটার সাথে সংযুক্ত। ডিজাইনার যাতে বুঝতে পারেন কোন সেকশনে কোন ডেটা আসে, তার টেকনিক্যাল গাইডলাইন নিচে দেওয়া হলো:
| এপিআই এন্ডপয়েন্ট (Endpoint) | মেথড | কী ডেটা প্রদান করে? | Next.js ফাইলে কোথায় ব্যবহৃত হয়? |
|---|---|---|---|
/wp-json/wc/store/v1/products |
GET | ক্যাটালগের সমস্ত প্রোডাক্ট, দাম, স্টক, থাম্বনেইল ও রেটিং | src/lib/store-api.ts (Home, Shop, Category) |
/wp-json/wc/v3/products?slug=[slug] |
GET | সিঙ্গেল প্রোডাক্টের ফুল গ্যালারি, ডেসক্রিপশন ও ভেরিয়েশনস | src/app/product/[slug]/page.tsx |
/wp-json/nextjs-editor/v1/settings |
GET | সাইট লোগো, ব্যানার, ডেলিভারি ফি, হোয়াটসঅ্যাপ নম্বর, কালার | src/lib/settings.ts (Global Layout, Header, Footer) |
/wp-json/nextjs-editor/v1/quiz |
GET | কুইজ প্রশ্ন, অপশন, স্কোরিং রুলস ও প্রোডাক্ট ট্যাগ ক্যাটালগ | src/components/home/QuizSection.tsx |
/wp-json/nextjs-editor/v1/reels |
GET | ইনস্টাগ্রাম-স্টাইল ভিডিও রিলস ও ট্যাগড প্রোডাক্ট লিঙ্কস | src/components/home/ReelsSection.tsx |
/api/checkout |
POST | অর্ডার ভ্যালিডেশন, ইন-ফ্লাইট লক ও উকমার্সে অর্ডার প্লেসমেন্ট | src/app/api/checkout/route.ts |
/api/fraud-check |
GET | লাইভ ফোন কুলডাউন (Cooldown) ও ব্লকলিস্টেড নম্বর ভেরিফিকেশন | src/app/api/fraud-check/route.ts |
/api/incomplete-order |
POST | চেকআউটে ফোন লিখে বের হয়ে গেলে পরিত্যক্ত কার্ট সেভ | src/app/api/incomplete-order/route.ts |
/api/revalidate |
POST | ওয়ার্ডপ্রেসে প্রোডাক্ট বা ব্যানার সেভ হলে ইনস্ট্যান্ট ক্যাশ পার্জ | src/app/api/revalidate/route.ts |
/api/revalidate এন্ডপয়েন্টে সিঙ্ক পাঠায় এবং সাথে সাথে নতুন ডেটা লাইভ হয়ে যায়।
প্রজেক্ট ফাইল ডিরেক্টরি ও UI ম্যাপিং (File Structure Map)
ডিজাইনার বা ডেভেলপার যখন কোনো নির্দিষ্ট পেজ বা সেকশন কাস্টমাইজ করবেন, তখন কোন ফাইলের সাথে কাজ করতে হবে তার সরাসরি গাইড:
| UI পেজ / সেকশন | Next.js সোর্স ফাইল | কাজের বিবরণ ও দায়িত্ব |
|---|---|---|
| হোমপেজ (Homepage) | src/app/page.tsx |
হিরো ব্যানার, ফিচার্ড ক্যাটাগরি, প্রোডাক্ট ক্যারোসেল, কুইজ ও রিভিউ সেকশন। |
| সিঙ্গেল প্রোডাক্ট পেজ | src/app/product/[slug]/page.tsx |
গ্যালারি, সাইজ/কালার ভেরিয়েশন, বিবরণ, রিভিউ, রিলেটেড প্রোডাক্ট ও এসইও মেটা। |
| ক্যাটাগরি আর্কাইভ পেজ | src/app/category/[slug]/page.tsx |
নির্দিষ্ট ক্যাটাগরির প্রোডাক্ট গ্রিড, ফিল্টার ও পেজিনেশন। |
| ব্র্যান্ড পেজসমূহ | src/app/brand/[slug]/page.tsx |
নির্দিষ্ট ব্র্যান্ডের প্রোডাক্ট ক্যাটালগ ও ব্র্যান্ড ব্যানার। |
| শপ / অল প্রোডাক্টস | src/app/shop/page.tsx |
সম্পূর্ণ ক্যাটালগ, ক্যাটাগরি ফিল্টার, প্রাইস সর্টিং ও সার্চ রেজাল্ট গ্রিড। |
| কার্ট পেজ ও স্টেট | src/app/cart/page.tsx & src/context/CartContext.tsx |
কার্ট ওভারভিউ পেজ ও গ্লোবাল কার্ট ড্রয়ার স্টেট ম্যানেজমেন্ট। |
| চেকআউট পেজ | src/app/checkout/page.tsx |
১-পেজ ক্যাশ অন ডেলিভারি ফর্ম, ডেলিভারি ফি ক্যালকুলেশন ও অর্ডার সাবমিশন। |
| অর্ডার কনফার্মেশন | src/app/order-received/[id]/page.tsx |
সুরক্ষিত থ্যাংক ইউ পেজ (কুকি ম্যাচিং, জিরো PII লিক)। |
| হেডার ও নেভিগেশন | src/components/layout/Header.tsx |
লোগো, ক্যাটাগরি মেনু, ইনস্ট্যান্ট সার্চ ইনপুট ও কার্ট ট্রিগার বাটন। |
| ফুটার সেকশন | src/components/layout/Footer.tsx |
কুইক লিংকস, সোশ্যাল মিডিয়া, পেমেন্ট পার্টনারস ও কপিরাইট টেক্সট। |
| কার্ট স্লাইডার ড্রয়ার | src/components/layout/CartDrawer.tsx |
ডানপাশ থেকে স্লাইড হয়ে আসা ইনস্ট্যান্ট কার্ট সাইডবার উইন্ডো। |
| প্রোডাক্ট কার্ড কম্পোনেন্ট | src/components/product/ProductCard.tsx |
রি-ইউজেবল সিঙ্গেল প্রোডাক্ট কার্ড উইথ প্রাইস, ব্যাজ ও অ্যাড-টু-কার্ট। |
| ওয়ার্ডপ্রেস প্লাগিন | wp-plugin/nextjs-editor/ |
ওয়ার্ডপ্রেস অ্যাডমিন কন্ট্রোল প্যানেল, কুইজ এডিটর, রিলস ও সেটিংস মডিউল। |
মডুলার ফিচারসমূহ — কুইজ ইঞ্জিন ও ভিডিও রিলস (Modular Features)
আমাদের সিস্টেমে কিছু শক্তিশালী মডুলার ফিচার বিল্ট-ইন তৈরি করা আছে। ডিজাইনার যদি তাদের নতুন UI কনসেপ্টে এগুলো যুক্ত করতে চান, তবে সরাসরি এগুলো ব্যবহার করতে পারবেন:
১. কুইজ ইঞ্জিন — প্রোডাক্ট রেকমেন্ডেশন সিস্টেম (Smart Quiz Recommendation)
কাস্টমারের পছন্দ ও প্রয়োজনের ওপর ভিত্তি করে স্বয়ংক্রিয়ভাবে সেরা প্রোডাক্ট ম্যাচ করিয়ে দেওয়ার জন্য এই কুইজ সিস্টেমটি তৈরি:
- অ্যাক্সিস-বেসড স্কোরিং (Multi-Axis Scoring): কুইজে প্রশ্নগুলোর উত্তরের সাথে ৪টি প্রধান অ্যাক্সিসের ট্যাগ সংযুক্ত থাকে—Occasion (অনুষ্ঠান), Season (মৌসুম), Look (স্টাইল) এবং Use (ব্যবহার)।
- বাজেট ফিল্টার: কাস্টমারের সর্বোচ্চ বাজেটের ভেতরের লাইভ ইন-স্টক প্রোডাক্ট খুঁজে বের করে।
- রেজাল্ট আউটপুট: সর্বোচ্চ ম্যাচিং প্রোডাক্টকে "Hero Match" হিসেবে এবং সাথে ৩-৪টি রানার-আপ প্রোডাক্ট
% matchব্যাজ সহ নিমিষে প্রদর্শন করে। - এডমিন ম্যানেজমেন্ট: ওয়ার্ডপ্রেসের Quiz Editor প্যানেল থেকে প্রশ্ন, উত্তর, ক্যাটাগরি ফিল্টার এবং প্রোডাক্ট ট্যাগ সহজেই পরিচালনা করা যায়।
২. ইনস্টাগ্রাম-স্টাইল ভিডিও রিলস (Interactive Video Commerce)
- মোবাইলে ফুল-স্ক্রিন বা হোমপেজে সোয়াইপএবল শর্ট ভিডিও ক্যারোসেল।
- ভিডিওর ওপর সরাসরি ট্যাগড প্রোডাক্টের নাম, ডিসকাউন্ট প্রাইস ও ইনস্ট্যান্ট "Buy Now" বাটন ভেসে ওঠে।
- ওয়ার্ডপ্রেস প্লাগিনের Reels Manager থেকে এমপি৪ ভিডিও ও প্রোডাক্ট ট্যাগ সহজেই সংযুক্ত করা যায়।
ডিজাইনার ও AI এজেন্টের জন্য ফাইনাল চেকলিস্ট (Hand-off Checklist)
যেকোনো নতুন HTML বা UI ডিজাইন ডেলিভারি দেওয়ার আগে অনুগ্রহ করে নিচের পয়েন্টগুলো মিলিয়ে নিন:
-
সকল প্রোডাক্ট লিংকের স্লাগ ঠিক আছে তো?
প্রতিটি প্রোডাক্ট কার্ড এবং ডিটেইলস লিংক অবশ্যই/product/[slug]ফরম্যাটে থাকতে হবে। কোনো?p=...বা/item/নয়। -
ক্যাটাগরি পেজের লিংক
/category/[slug]ফরম্যাটে আছে তো?
মেনু ও ফিল্টারের সমস্ত ক্যাটাগরি লিংক যেনো সরাসরি/category/[slug]কে রেফার করে। -
শপ ক্যাটালগ পেজ
/shopএ পয়েন্ট করছে তো?
অল-প্রোডাক্টস বাটন এবং শপ মেনু লিঙ্ক/shopফরম্যাটে থাকতে হবে। -
স্লাইড-ওভার কার্ট সাইডবার ড্রয়ার (Cart Drawer) রয়েছে তো?
হেডারের কার্ট আইকনে ক্লিক করলে ডানদিক থেকে কার্ট সাইডবার বের হবে এবং ভেতরে সাবটোটাল সহ "Proceed to Checkout" বাটন থাকবে। -
সাইজ ও কালার ভেরিয়েশন সিলেক্টর প্রোডাক্ট পেজে আছে তো?
প্রোডাক্ট ডিটেইলসে সাইজ বাটন গ্রিড এবং কালার সোয়াচ অপশন থাকতে হবে যা ক্লিক করলে একটিভ স্টেট প্রদর্শন করে। -
চেকআউট পেজ সিঙ্গেল-পেজ এবং COD ফ্রেন্ডলি তো?
নাম, ফোন নম্বর, ডেলিভারি ঠিকানা এবং "ঢাকার ভেতরে (৳৭০) / ঢাকার বাইরে (৳১৩০)" রেডিও অপশন সহ ১-পেজ ফর্মে সাজানো থাকতে হবে। -
মোবাইল স্ক্রিনে সব গ্রিড ও টেবিল রেসপনসিভ তো?
কোনো এলিমেন্ট যেন ডানে-বামে কেটে না যায় বা হরাইজন্টাল স্ক্রোল না ভেঙে ফেলে।
আমরা ডিজাইনার বা এজেন্টকে কোনো রেস্ট্রিকশনে রাখছি না। আপনার ব্র্যান্ডের প্রোডাক্ট টাইপ অনুযায়ী হিরো স্লাইডার, ব্যানার, কালার স্কিম, টাইপোগ্রাফি এবং নতুন যত সেকশন প্রয়োজন সবই যুক্ত করুন। শুধু আমাদের উল্লিখিত প্রাইমারি রুলস (URL Slugs, Routing & Data References) ঠিক রাখুন—যাতে এসইও এবং মেটা পিক্সেল ট্র্যাকিং সহ ব্যাকএন্ড ডাটা ফ্লো কোনো সমস্যা ছাড়াই ১০০% স্মুথলি কাজ করে।