Engine v2.5 Next.js Headless Master Architecture Spec
Universal Headless E-Commerce System

Next.js 14 Frontend + WooCommerce Backend Architecture Spec

⚡ Sub-Second Speed (< 0.4s) 🔍 100% SEO Ready (SSR + JSON-LD Schema) 🛡️ Zero Duplicate Orders & In-Flight Lock 🎨 100% Full UI/UX Creative Freedom

এই মাস্টার ডকুমেন্টটি আমাদের UI/UX ডিজাইনার, ফ্রন্টএন্ড ডেভেলপার এবং AI ডিজাইনিং এজেন্টদের জন্য তৈরি করা হয়েছে। আমাদের আর্কিটেকচারটি একটি ইউনিভার্সাল হেডলেস ই-কমার্স ইঞ্জিন। ডিজাইনারকে কোনো বাঁধাধরা লেআউটে আবদ্ধ রাখা হচ্ছে না—হিরো সেকশন, ব্যানার স্লাইডার, কালার প্যালেট, টাইপোগ্রাফি ফন্ট, প্রোডাক্ট কার্ড স্টাইল কিংবা যেকোনো নতুন কাস্টম সেকশন আপনি ব্র্যান্ডের রুচি অনুযায়ী যেভাবে ইচ্ছা সেভাবে সম্পূর্ণ নতুন রূপ দিয়ে রি-ডিজাইন করতে পারেন। আমাদের পক্ষ থেকে আপনার ডিজাইনে ১০০% পূর্ণ স্বাধীনতা (Full Creative Freedom) দেওয়া হচ্ছে।

আপনার ডিজাইনকে সচল ও সফল করার জন্য শুধু একটি বিষয় নিশ্চিত করতে হবে: আমাদের প্রাইমারি রুলস (Primary Rules)—যেমন নির্দিষ্ট ইউআরএল স্লাগ, কার্ট ও চেকআউট স্ট্রাকচার এবং এসইও ও ফেসবুক পিক্সেল সার্ভার-সাইড ট্র্যাকিং মেকানিজম যেন হুবহু অপরিবর্তিত থাকে। ডিজাইন যেমনই হোক না কেন, এই ব্যাকএন্ড রুলস ঠিক রাখলে পুরো সিস্টেমটি স্বয়ংক্রিয়ভাবে নিখুঁতভাবে চলবে।

Headless Speed
< 0.4s Fast
Next.js 14 App Router, ISR ক্যাশিং ও WebP ছবির কারণে সাধারণ ওয়ার্ডপ্রেসের চেয়ে ৫-৬ গুণ দ্রুত।
Product URLs
/product/[slug]
গুগল এসইও এবং ওর্ডপ্রেস সিঙ্কের জন্য ক্লিন পার্মালিংক ফরম্যাট। কোনো কুয়েরি প্যারাম নয়।
Cart Experience
Slide Drawer
ডানদিক থেকে স্মুথ স্লাইড-ইন কার্ট সাইডবার ও ডেডিকেটেড /cart ওভারভিউ পেজ।
Frictionless Checkout
1-Page COD
ঢাকার ভেতরে/বাইরে লাইভ ডেলিভারি ফি, ইন-ফ্লাইট লক ও জিরো ডুপ্লিকেট অর্ডার ইঞ্জিন।

সিস্টেমের কাজের প্রবাহ (Data Flow & User Journey)

Step 1: Traffic
📱 Customer Enters
Facebook Ads, Google Search বা সরাসরি লিঙ্ক থেকে সাইটে আসে।
Step 2: Frontend
⚡ Next.js 14 SSR
মিলিসেকেন্ডে পেজ রেন্ডার হয়, JSON-LD স্কিমা ও মেটা লোড হয়।
Step 3: Interaction
🛒 Cart Drawer / Direct COD
সাইজ/কালার ভেরিয়েশন নির্বাচন করে স্লাইডার কার্ট বা অর্ডার ফর্মে যায়।
Step 4: Gateway
🛡️ /api/checkout
ইন-ফ্লাইট লক, ফোন কুলডাউন ও ফ্রড ভ্যালিডেশন নিশ্চিত করে।
Step 5: Backend
📦 WooCommerce Sync
WooCommerce REST API-তে অর্ডার তৈরি হয় ও মেটা CAPI ফায়ার হয়।
1

প্রাইমারি রুলস — ইউআরএল স্লাগ ও রাউটিং কনভেনশন (Primary Routing Rules)

যেকোনো নতুন ব্র্যান্ড বা ক্যাটাগরির জন্য UI/UX ডিজাইন বানানোর সময় সবচেয়ে গুরুত্বপূর্ণ নিয়ম হলো নিচের ইউআরএল স্লাগগুলো অক্ষুণ্ণ রাখা। যদি ডিজাইনার সঠিক স্লাগ ব্যবহার করে HTML তৈরি করে, তবে আমাদের কোডে কোনো রাউটিং ফাইল পরিবর্তন করতে হয় না।

১. সিঙ্গেল প্রোডাক্ট পেজ (Product Details) MANDATORY
Pattern: /product/[slug]
✓ https://example.com/product/sneakers-007-olive-green ✓ https://example.com/product/retro-leather-loafer-brown ✗ https://example.com/?p=123 (ভুল) ✗ https://example.com/item/sneakers-007 (ভুল) ✗ https://example.com/products/sneakers-007 (ভুল)

কোর রুল: অলওয়েজ একবচনে /product/[slug] হবে, কখনোই /item/ বা /products/ বা আইডি কোয়েরি নয়।

২. ক্যাটাগরি আর্কাইভ পেজ (Category Page) MANDATORY
Pattern: /category/[slug]
✓ https://example.com/category/7a-grade ✓ https://example.com/category/uncategorized ✓ https://example.com/category/running-shoes ✗ https://example.com/cat/7a-grade (ভুল) ✗ https://example.com/collections/7a-grade (ভুল)

কোর রুল: ক্যাটাগরির মূল স্লাগ সবসময় /category/[slug]। ওয়ার্ডপ্রেস টার্ম স্লাগের সাথে এটি সরাসরি মিলে যায়।

৩. ব্র্যান্ড পেজ (Brand Page & Directory) MANDATORY
Pattern: /brand/[slug] & /brands
✓ https://example.com/brand/nike ✓ https://example.com/brand/adidas ✓ https://example.com/brands (সকল ব্র্যান্ডের সূচি) ✗ https://example.com/b/nike (ভুল)

কোর রুল: সিঙ্গেল ব্র্যান্ডের জন্য /brand/[slug] এবং অল-ব্র্যান্ডস গ্রিডের জন্য /brands।

৪. শপ ক্যাটালগ পেজ (All Products Shop) MANDATORY
Pattern: /shop
✓ https://example.com/shop ✓ https://example.com/shop?category=7a-grade ✓ https://example.com/shop?sort=price-asc ✗ https://example.com/all-products (ভুল) ✗ https://example.com/store (ভুল)

কোর রুল: সমস্ত প্রোডাক্টের মেইন ক্যাটালগ ও ফিল্টার পেজের স্লাগ অলওয়েজ /shop।

৫. কার্ট পেজ ও স্লাইড ড্রয়ার (Cart Drawer) MANDATORY
Pattern: /cart & [data-drawer="cart"]
✓ https://example.com/cart (ফুল পেজ) ✓ হেডার কার্ট আইকন ক্লিক ➔ স্লাইড-ইন সাইডবার ড্রয়ার ✗ https://example.com/basket (ভুল) ✗ https://example.com/my-cart (ভুল)

কোর রুল: সাইডবার স্লাইডার ড্রয়ারের পাশাপাশি ডেডিকেটেড কার্ট পেজের স্লাগ হবে /cart।

৬. চেকআউট পেজ (Frictionless Checkout) MANDATORY
Pattern: /checkout
✓ https://example.com/checkout ✗ https://example.com/order-now (ভুল) ✗ https://example.com/payment (ভুল)

কোর রুল: সব পেজের "Buy Now" বা কার্টের "Proceed to Checkout" বাটন সোজা /checkout এ রিডাইরেক্ট করবে।

৭. অর্ডার কনফার্মেশন (Order Received) MANDATORY
Pattern: /order-received/[id]
✓ https://example.com/order-received/1284 ✗ https://example.com/thank-you (ভুল) ✗ https://example.com/success (ভুল)

কোর রুল: সফল অর্ডারের পর ক্রেতা এই পেজে যাবে। এখানে কুকি ভেরিফিকেশন দিয়ে কাস্টমারের তথ্য সুরক্ষিত রাখা হয়।

৮. পলিসি ও স্ট্যাটিক পেজসমূহ (Static Pages) MANDATORY
Pattern: /page/[slug]
✓ https://example.com/page/about-us ✓ https://example.com/page/privacy-policy ✓ https://example.com/page/terms-conditions ✓ https://example.com/page/shipping-and-delivery

কোর রুল: ওয়ার্ডপ্রেস পেজের লাইভ কনটেন্ট Next.js এ /page/[slug] দিয়ে রেন্ডার হয়।

✓ ডিজাইনার ও এজেন্টের করণীয় (What UI/UX Agent MUST Do)
  • যেকোনো প্রোডাক্টের জন্য কার্ডের বাটন বা লিঙ্কে /product/{slug} ডাইনামিক রেফারেন্স রাখা।
  • ক্যাটাগরি মেনু বা লিঙ্কে /category/{slug} ব্যবহার করা।
  • হেডারে কার্ট আইকন দিয়ে ক্লিক করলে স্লাইড-ইন সাইডবার কার্ট ড্রয়ার ওপেন হওয়ার অপশন রাখা।
  • প্রোডাক্ট ডিটেইলস পেজে সাইজ (Sizes) এবং কালার (Colors) ভ্যারিয়েশন অপশন রাখা।
  • চেকআউট পেজে মাত্র ১ পেজের মধ্যে নাম, ফোন, ঠিকানা ও ডেলিভারি এরিয়া ড্রপডাউন রাখা।
✗ যা কখনো করা যাবে না (What You MUST Avoid)
  • ইউআরএল-এ ?p=123, /item/, /items/ বা /products/ দিয়ে লিংক তৈরি করা যাবে না।
  • চেকআউট পেজকে একাধিক ধাপে (Multi-step Wizard) ভাগ করা যাবে না—কাস্টমার এক পেজেই অর্ডার কনফার্ম করবে।
  • কার্ট সিস্টেম ছাড়া শুধু হোয়াটসঅ্যাপ মেসেজ দিয়ে অর্ডার সীমাবদ্ধ করা যাবে না।
  • মোবাইল ভিউপোর্টে সাইটের প্রস্থ ফিক্সড পিক্সেল দিয়ে ভেঙে ফেলা যাবে না।
2

কম্পোনেন্ট আর্কিটেকচার ও UI নির্দেশিকা (Component Architecture & UI)

নতুন যেকোনো ডিজাইনের ক্ষেত্রে UI/UX এজেন্টের স্বাধীনতা রয়েছে সম্পূর্ণ নতুন কালার প্যালেট, ইউনিক কার্ড শ্যাডোজ, আকর্ষণীয় টাইপোগ্রাফি এবং নতুন সেকশন যোগ করার।

হিরো সেকশন, ব্যানার স্লাইডার ও কাস্টম সেকশন রি-ডিজাইন করার পূর্ণ স্বাধীনতা: হোমপেজের হিরো এরিয়া বা স্লাইডার আপনি যেভাবে ইচ্ছা ডিজাইন করতে পারেন—ফুল-উইডথ ক্যারোসেল, স্প্লিট ব্যানার, অটো-স্লাইডার, ভিডিও হিরো কিংবা গ্রিড ব্যানার। একইসাথে ব্র্যান্ডের যেকোনো নতুন সেকশন (যেমন: ফিচার্ড কালেকশন, কাস্টমার রিভিউ, ব্র্যান্ড স্টোরি, সাইজ গাইড, এফএকিউ ইত্যাদি) যুক্ত করতে পারেন। শুধু লক্ষ্য রাখবেন, প্রোডাক্টের যেকোনো ক্লিকে যেন /product/[slug] এবং ক্যাটাগরিতে /category/[slug] লিংক যুক্ত থাকে।

১. গ্লোবাল হেডার ও কার্ট সাইডবার ড্রয়ার (Header & Cart Drawer)

হেডারে ব্র্যান্ড লোগো, নেভিগেশন লিংক এবং একটি লাইভ কার্ট আইকন থাকবে। কার্ট আইকনে ক্লিক করলে পেজ রিফ্রেশ না হয়ে ডানদিক থেকে একটি আধুনিক Slide-Over Cart Drawer ভেসে উঠবে:

২. প্রোডাক্ট কার্ড ও ক্যাটালগ গ্রিড (ProductCard & Grid)

হোমপেজ, ক্যাটাগরি পেজ বা শপ পেজে প্রোডাক্ট ডিসপ্লে করার জন্য কার্ডে নিচের তথ্যগুলো থাকা বাঞ্ছনীয়:

৩. প্রোডাক্ট ডিটেইলস পেজ ও ভেরিয়েশন সাপোর্ট (Sizes, Colors, Variations)

WooCommerce Product Variations পুরোপুরি সাপোর্টেড: আমাদের কোড স্বয়ংক্রিয়ভাবে উকমার্সের সাইজ (যেমন: 40, 41, 42, 43, 44 বা S, M, L, XL) এবং কালার ভেরিয়েশন রিড করে।

৪. চেকআউট পেজ (Frictionless 1-Page Checkout)

বাংলাদেশের ই-কমার্স ও ক্যাশ-অন-ডেলিভারি (COD) অপারেশনের জন্য আমাদের চেকআউট ফর্মটি মাত্র ১ পেজে রাখা হয়েছে:

3

ডেটা কীভাবে আসে এবং এপিআই এন্ডপয়েন্টসমূহ (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
সার্ভার ক্যাশিং ও অন-ডিমান্ড রিভ্যালিডেশন (Instant Cache Sync): সাধারণ ওয়ার্ডপ্রেসের মতো প্রতি ক্লিকে ডাটাবেসে কুয়েরি হয় না। Next.js সার্ভার মেমোরিতে ডেটা ক্যাশ করে রাখে। অ্যাডমিন যখন ওয়ার্ডপ্রেস প্যানেলে কোনো প্রোডাক্টের দাম বা ছবি পরিবর্তন করে, প্লাগিন স্বয়ংক্রিয়ভাবে /api/revalidate এন্ডপয়েন্টে সিঙ্ক পাঠায় এবং সাথে সাথে নতুন ডেটা লাইভ হয়ে যায়।
4

প্রজেক্ট ফাইল ডিরেক্টরি ও 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/ ওয়ার্ডপ্রেস অ্যাডমিন কন্ট্রোল প্যানেল, কুইজ এডিটর, রিলস ও সেটিংস মডিউল।
5

মডুলার ফিচারসমূহ — কুইজ ইঞ্জিন ও ভিডিও রিলস (Modular Features)

আমাদের সিস্টেমে কিছু শক্তিশালী মডুলার ফিচার বিল্ট-ইন তৈরি করা আছে। ডিজাইনার যদি তাদের নতুন UI কনসেপ্টে এগুলো যুক্ত করতে চান, তবে সরাসরি এগুলো ব্যবহার করতে পারবেন:

১. কুইজ ইঞ্জিন — প্রোডাক্ট রেকমেন্ডেশন সিস্টেম (Smart Quiz Recommendation)

কাস্টমারের পছন্দ ও প্রয়োজনের ওপর ভিত্তি করে স্বয়ংক্রিয়ভাবে সেরা প্রোডাক্ট ম্যাচ করিয়ে দেওয়ার জন্য এই কুইজ সিস্টেমটি তৈরি:

২. ইনস্টাগ্রাম-স্টাইল ভিডিও রিলস (Interactive Video Commerce)

6

ডিজাইনার ও AI এজেন্টের জন্য ফাইনাল চেকলিস্ট (Hand-off Checklist)

যেকোনো নতুন HTML বা UI ডিজাইন ডেলিভারি দেওয়ার আগে অনুগ্রহ করে নিচের পয়েন্টগুলো মিলিয়ে নিন:

ডিজাইনারের জন্য চূড়ান্ত বার্তা (Full Creative Freedom — Zero Restriction):
আমরা ডিজাইনার বা এজেন্টকে কোনো রেস্ট্রিকশনে রাখছি না। আপনার ব্র্যান্ডের প্রোডাক্ট টাইপ অনুযায়ী হিরো স্লাইডার, ব্যানার, কালার স্কিম, টাইপোগ্রাফি এবং নতুন যত সেকশন প্রয়োজন সবই যুক্ত করুন। শুধু আমাদের উল্লিখিত প্রাইমারি রুলস (URL Slugs, Routing & Data References) ঠিক রাখুন—যাতে এসইও এবং মেটা পিক্সেল ট্র্যাকিং সহ ব্যাকএন্ড ডাটা ফ্লো কোনো সমস্যা ছাড়াই ১০০% স্মুথলি কাজ করে।