GhuriAI প্রজেক্ট মাস্টার প্ল্যান ও আর্কিটেকচার টিউটোরিয়াল

নতুন শিক্ষার্থীদের জন্য সম্পূর্ণ প্রজেক্টের পুঙ্খানুপুঙ্খ স্টাডি গাইড: কোথায় কোন ফাইল আছে, এক ফাইলের সাথে অন্য ফাইলের সম্পর্ক কী, ডেটা ফ্লো এবং HTML ও React উভয় সিস্টেমের ব্যাখ্যা।

১. প্রজেক্ট মাস্টার প্ল্যান ও ভিশন (Project Master Plan)

কোর প্রজেক্ট কনসেপ্ট

“Budget based Bangladeshi smart travel planner.” — আগে বাজেট দিন, পরে ভ্রমণকারী, দিন ও স্টার্টিং পয়েন্ট সিলেক্ট করুন; সিস্টেম স্বয়ংক্রিয়ভাবে বাস্তবসম্মত খরচে সেরা ট্রিপ প্ল্যান তৈরি করবে।

প্রজেক্টের মূল উদ্দেশ্য ও সমস্যা সমাধান:

বাংলাদেশে ভ্রমণ করার সময় সাধারণ মানুষ তিনটি বড় সমস্যার সম্মুখীন হন: (১) বাজেটের তুলনায় বাস্তব খরচ কতটা হবে তা আগে জানা যায় না, (২) ট্রাভেল এজেন্টরা অতিরিক্ত দাম নেয়, এবং (৩) প্রচলিত AI (ChatGPT বা Gemini) সরাসরি জিজ্ঞেস করলে কাল্পনিক বা অবাস্তব দাম (Hallucination) প্রদর্শন করে।

GhuriAI-এর সমাধান দর্শন:
• বাজেট-ফার্স্ট অ্যালগরিদম: ব্যবহারকারী প্রথমেই তার বাজেট ইনপুট দেবেন।
• হাইব্রিড গার্ডরেইল আর্কিটেকচার: টাকা-পয়সা, গাড়ির ভাড়া, হোটেল রুম ও খাবারের খরচ ১০০% খাঁটি গাণিতিক কোডে হিসাব হবে (AI কখনো টাকা বানাতে পারবে না)।
• AI-এর ভূমিকা: AI (Gemini 1.5 Flash) শুধুমাত্র সকাল, দুপুর ও সন্ধ্যার নিরাপদ সাইটসিয়িং ও পর্যটন অভিজ্ঞতার রোমাঞ্চকর বিবরণ তৈরি করবে।

২. Two-Root আর্কিটেকচারাল কাঠামো (Two Independent Roots)

প্রজেক্টের দীর্ঘমেয়াদি স্থায়িত্ব এবং বিভিন্ন পরিবেশে চালনার জন্য পুরো রিপোজিটরিকে দুটি সম্পূর্ণ স্বাধীন রুটে ভাগ করা হয়েছে:

c:\Versity\GhuriAI\ (Root 1: HTML Project Root) │ ├── [শুধুমাত্র HTML প্রজেক্টের ফাইলসমূহ] │ ├── index.html, explore.html, preset.html, planner.html, admin.html, docs.html │ ├── assets/ (css, js, 21টি local webp images) │ ├── data/ (places.json, presets.json) │ └── server/ (server.cjs, logic.cjs, test.cjs, integration_test.cjs) │ └── GhuriAI_React/ (Root 2: React Project Root — সম্পূর্ণ স্বাধীন) ├── package.json, vite.config.js, README.md ├── public/assets/images/ (21টি webp images) └── src/ ├── components/ (SearchableDropdown, Navbar, Footer) ├── pages/ (HomePage, ExplorePage, PresetDetailPage, PlannerPage, DocsPage, AdminPage) ├── data/ (places.json, presets.json) └── utils/calculator.js (ডিটারমিনিস্টিক ক্যালকুলেটর)
তুলনামূলক বিষয় রুট ১: HTML প্রজেক্ট রুট (c:\Versity\GhuriAI\) রুট ২: React প্রজেক্ট রুট (GhuriAI_React\)
মূল দর্শন জিরো ডিপেন্ডেন্সি, কোনো সার্ভার ছাড়া সরাসরি ব্রাউজারে ডাবল ক্লিকেই সচল আধুনিক মডিউলার SPA (Single Page App), কম্পোনেন্ট মডেল ও Vite লোকালহোস্ট
ফাইলের ধরণ শুধুমাত্র পিওর HTML, CSS, JS, ডেটা ও HTML প্রজেক্টের সার্ভার/টেস্ট স্ক্রিপ্ট React 18 JSX, Vite কনফিগ, মডিউলার কম্পোনেন্ট ও নিজস্ব ডেটাসেট
প্যাকেজ ফাইল রুটে কোনো package.json বা node_modules নেই (জিরো ব্লট) নিজস্ব package.json, vite.config.js এবং node_modules
চলানোর নিয়ম index.html-এ ডাবল ক্লিক অথবা node server/server.cjs cd GhuriAI_React → npm run dev (Port 5173)

৩. এন্ড-টু-এন্ড ডেটা ফ্লো ও লাইফসাইকেল বিশ্লেষণ

একজন শিক্ষার্থী হিসেবে বোঝা জরুরি: ব্যবহারকারী যখন ইনপুট দেন, তখন কোডের ভেতর দিয়ে তথ্য কীভাবে প্রবাহিত হয়?

[ধাপ ১: ইউজার ইনপুট] বাজেট (৳8,000) ──> সদস্য (2 জন) ──> দিন (3 দিন) ──> শুরু (Khulna) ──> গন্তব্য (AI Suggest) │ ▼ [ধাপ ২: Haversine দূরত্ব গণনা] Khulna (22.84, 89.54) থেকে ১৮টি গন্তব্যের ভৌগোলিক অক্ষাংশ-দ্রাঘিমাংশ দিয়ে দূরত্ব নির্ণয়: দৃষ্টান্ত: Kuakata = 104 km, Sundarban = 75 km, Sixty Dome Mosque = 32 km... দূরত্বের ক্রমানুসারে সাজিয়ে শীর্ষ ৩টি গন্তব্য নির্বাচন! │ ▼ [ধাপ ৩: খাঁটি কোডে খরচ বিভাজন (Deterministic Calculation)] ১. যাতায়াত (Transport): Round Trip = Distance × 2 × সদস্য সংখ্যা × বেস রেট ২. হোটেল রুম (Rooms): Math.ceil(সদস্য / 2) রুম × রাত × রুম রেট ৩. খাবার (Food): সদস্য সংখ্যা × দিন × ৩ বেলার বরাদ্দ ৪. অ্যাক্টিভিটি (Activities): সদস্য সংখ্যা × দর্শনীয় স্থানের এন্ট্রি ফি │ ▼ [ধাপ ৪: বাজেট যাচাই ও ঘাটতি পরীক্ষা] মোট আনুমানিক খরচ ৳6,400 <= বাজেট ৳8,000? ├── হ্যা: উদ্বৃত্ত সঞ্চয় = ৳1,600 (STATUS: ESTIMATE_WITHIN_BUDGET) └── না (যেমন ৳100 বাজেট): ঘাটতি = ৳6,300 (STATUS: BUDGET_TOO_LOW) ──> সতর্কবার্তা ও সর্বনিম্ন বাজেট পরামর্শ │ ▼ [ধাপ ৫: রেন্ডারিং ও আউটপুট প্রদর্শন] • আইটেমাইজড টেবিল • দিনভিত্তিক ডেলাইট আইটিনারারি • Asia/Dhaka লাইভ টাইমস্ট্যাম্প • প্রিন্ট / PDF এক্সপোর্ট

২. কোর আর্কিটেকচারাল FAQ ও এভিডেন্স ডিরেক্টরি (GhuriAI Core FAQ & Architectural Answers)

বিশ্ববিদ্যালয় ডিফেন্স ও সিস্টেম পর্যালোচনার জন্য প্রস্তুতকৃত প্রশ্নোত্তর

এই সেকশনটি তৈরি করা হয়েছে বিশ্ববিদ্যালয় ভাইভা বোর্ড, ফ্যাকাল্টি মূল্যায়ন এবং টেকনিক্যাল নিরীক্ষার সাধারণ অথচ জটিল প্রশ্নগুলোর সরাসরি কোডিং সোর্স ও লজিক্যাল এভিডেন্স দেওয়ার জন্য।

FAQ ১: ট্রেন, বাস, প্রাইভেট ও হোটেল ভাড়া কোন উৎস থেকে যাচাই করা হয়? এগুলো তো প্রতিনিয়ত ওঠানামা করে—এর ব্যাখ্যা কীভাবে ও কোথায় লেখা হয়েছে?

বাস্তব সমস্যা: বাংলাদেশের পর্যটন সেক্টরে উবার বা এয়ারবিএনবির মতো সেন্ট্রালাইজড লাইভ প্রাইসিং এপিআই নেই। এমনকি একই দিনে ঢাকা–কক্সবাজারের নন-এসি বাসের ভাড়া যেখানে ৯০০ টাকা, সেখানে এসি বাসে ২,৫০০ টাকাও হতে পারে। তেলের দাম, ঈদ সিজন বা শীতকালে হোটেল ভাড়া কয়েক গুণ বৃদ্ধি পায়।

GhuriAI-এর মূল অবস্থান: GhuriAI কোনো কাল্পনিক "লাইভ ভাড়ার" মিথ্যা দাবি করে না। আমাদের নীতিমালায় এগুলোকে সংজ্ঞায়িত করা হয়েছে "Illustrative Planning Benchmark" (পরিকল্পনা প্রাক্কলন মানদণ্ড) হিসেবে।

খাত তথ্যসূত্র (Data Source) ওঠানামার চরিত্র ভেরিফিকেশন লেবেল
ট্রেন ভাড়া বাংলাদেশ রেলওয়ের অফিসিয়াল গেজেট ও শোভন/স্নিগ্ধা রেট। সরকার নির্ধারিত (স্থায়ী)। আসন সংকট থাকে। supported_estimate
বাস ভাড়া বিআরটিএ (BRTA) নির্ধারিত নন-এসি চেয়ার কোচ বেঞ্চমার্ক (places.json)। জ্বালানি মূল্য ও ঈদ মৌসুমে ২০%–৩০% বাড়ে। supported_estimate
হোটেল / রিসোর্ট পর্যটন করপোরেশন মোটেল ও স্থানীয় স্ট্যান্ডার্ড ৩-স্টার হোটেলের গড় হার। সিজন ভেদে দ্বিগুণ বা তিনগুণ পর্যন্ত ওঠানামা করে। unverified (কাউন্টারে যাচাইযোগ্য)
লোকাল পরিবহন ও টিকিট প্রত্নতত্ত্ব অধিদপ্তর/বন বিভাগের টিকিট ও স্থানীয় ট্রলার/সিএনজির গড় ভাড়া। পর্যটকের দরদাম ও সদস্য সংখ্যার ওপর নির্ভরশীল। unverified (কাউন্টারে যাচাইযোগ্য)

৩টি গাণিতিক নিরাপত্তা বলয় (Safety Buffers):
১. ফ্লোর প্রাইস ও সিলিং: যেকোনো দূরত্বের জন্য সর্বনিম্ন ১০০ টাকার একমুখী ফ্লোর রেট রাখা হয়েছে এবং সব সময় ১০ টাকার গুণিতকে সিলিং (Math.ceil) করা হয়।
২. বিজোড় সদস্যে অতিরিক্ত রুম বরাদ্দ: ৩ জন ভ্রমণকারী হলে সিস্টেম কখনোই ১টি রুমে ভাগ করে ঝুঁকি নেয় না; বরং সিলিং ফাংশন দিয়ে সরাসরি ২টি রুমের বাজেট ধরে।
৩. ২৫% ফুড ও আনুষঙ্গিক বাফার: খাবার ও স্থানীয় খরচে নমনীয় মার্জিন রাখা হয়েছে যা লোকাল রিকশা বা এন্ট্রি টিকিটের মূল্যবৃদ্ধিকে কভার করে।

কোডিং সোর্স এভিডেন্স (Code References):
• server/logic.js (লাইন ৩৭-৪১): costEvidence অ্যারেতে ESTIMATE ও UNVERIFIED টাইপ নির্ধারণ।
• src/components/PlanEvidence.jsx (লাইন ৮৬-৯৪): ইউজার ইন্টারফেসে লাইভ স্বচ্ছতা ডিসক্লেইমার প্রকাশ।
• README.md (লাইন ৩৭-৪৪): "Costs and freshness: what is actually known" সেকশন।
• .agents/skills/ghuriai-docs/references/responsible_ai.md: এআই স্কিলের এভিডেন্স স্কিমা।

🎓 ভাইভা ডিফেন্স টিপ: "আমরা কোনো কাল্পনিক লাইভ ভাড়ার ভুয়া দাবি করি না। আমাদের সিস্টেমটি বিআরটিএ ও পর্যটন করপোরেশনের গড় তথ্যের ওপর ডিটারমিনিস্টিক বেঞ্চমার্ক তৈরি করে এবং ব্যবহারকারীকে স্পষ্ট ব্যাজ দেখিয়ে স্থানীয় কাউন্টারে নিশ্চিত করার পরামর্শ দেয়। এটিই আমাদের Responsible AI বৈশিষ্ট্য।"

FAQ ২: লাইভ ডেটা সোর্স বনাম স্ট্যাটিক JSON — আমাদের অ্যাপ্লিকেশনে কি Google Search Grounding সত্যিই ব্যবহৃত হয়েছে, নাকি আমরা শুধু স্ট্যাটিক ডেটায় সীমাবদ্ধ?

উত্তর: হ্যাঁ, আমাদের অ্যাপ্লিকেশনে Google Search Grounding-এর মাধ্যমে রিয়েল-টাইম লাইভ এপিআই ব্যবহৃত হয়েছে। আমরা শুধু স্ট্যাটিক ডেটায় সীমাবদ্ধ নই।

GhuriAI একটি অত্যন্ত আধুনিক "হাইব্রিড আর্কিটেকচার" (Hybrid Intelligence) অনুসরণ করে:

[ ১. স্ট্যাটিক ব্যাকবোন: places.json ] ──> ভৌগোলিক স্থানাঙ্ক (Lat/Lon) ও গাণিতিক খরচের সীমানা রক্ষা করে। + [ ২. লাইভ গুগল সার্চ গ্রাউন্ডিং: Google AI Studio API ] ──> শীর্ষ ট্রাভেল ম্যাগাজিন ও পাবলিক নিউজ পোর্টাল ব্রাউজ করে। │ ▼ [ সমন্বিত ফলাফল ] ──> জীবন্ত সাম্প্রতিক বর্ণনা + আসল পাবলিক সোর্স লিংক [১], [২] + নিখুঁত বাজেট!

লাইভ সার্চ কীভাবে কাজ করে?
যখন ইউজার প্ল্যান রিকোয়েস্ট পাঠান, লোকাল সার্ভার গুগল এআই স্টুডিওর gemini-3.8-flash মডেলকে tools: [{ google_search: {} }] সহ কল করে। তখন গুগল ব্যাকগ্রাউন্ডে TripAdvisor, Lonely Planet, বাংলাদেশ পর্যটন করপোরেশনের পোর্টাল, প্রথম আলো ছুটির দিনে ইত্যাদির মতো শীর্ষ ট্রাভেল ফিচার ব্রাউজ করে দর্শনীয় স্থানের বর্তমান পরিস্থিতি, সময়সূচি ও আকর্ষণ সংগ্রহ করে।

গুগল লাইভ সার্চ থেকে প্রাপ্ত মেটাডাটা:
• groundingChunks: গুগল যে যে ওয়েবসাইট ঘেঁটেছে সেগুলোর সরাসরি পাবলিক ইউআরএল (web.uri) এবং টাইটেল।
• groundingSupports: বর্ণনার কোন নির্দিষ্ট বাক্যটি কোন ওয়েবসাইটের সাথে মিলেছে তার ম্যাপিং।
• searchEntryPoint: গুগলের অফিসিয়াল সার্চ উইজেট যা আমাদের অ্যাপে স্যান্ডবক্সড iframe-এ রেন্ডার হয়।

কোডিং সোর্স এভিডেন্স (Code References):
• server/gemini.js (লাইন ৩৭): tools: [{ google_search: {} }] এপিআই প্যারামিটার।
• server/gemini.js (লাইন ৪৭-৫৩): meta.groundingChunks থেকে সোর্স ইউআরএল ও টাইটেল নিষ্কাশন।
• src/components/PlanEvidence.jsx (লাইন ১৩৫-১৭০): স্ক্রিনে লাইভ সোর্স লিংক [{s.index + 1}] {s.title} রেন্ডারিং।

🎓 কেন ভাড়ার দায়িত্ব গুগলের ওপর ছেড়ে দেওয়া হয়নি? ইন্টারনেটের কোনো ব্লগে হয়তো ২০১৯ সালের পুরোনো ভাড়া (৫০০ টাকা) লেখা আছে। এআই যদি সেই পুরোনো তথ্যকে আজকের ভাড়া মনে করে, তবে পর্যটক মাঝপথে বিপদে পড়বেন। তাই বর্ণনার জন্য লাইভ গুগল সার্চ নেওয়া হয়েছে, কিন্তু আর্থিক সুরক্ষার জন্য সার্ভারের খাঁটি গণিত ব্যবহার করা হয়েছে।

FAQ ৩: ৳১০০ অসম্ভব বাজেট হ্যান্ডলিং — এআই কেন বানিয়ে কথা বলে না এবং কীভাবে সিদ্ধান্ত নেয়?

চ্যাটবটের চাটুকারিতা বনাম GhuriAI: প্রথাগত এআই চ্যাটবটকে ১০০ টাকায় ৩ দিনের ট্যুর চাইলে সে মিষ্টি ভাষায় বানিয়ে বানিয়ে একটি কাল্পনিক প্ল্যান তৈরি করে দেয়। কিন্তু GhuriAI-তে "People-Pleasing Hallucination" সম্পূর্ণ নিষিদ্ধ।

সিদ্ধান্ত প্রবাহ (Decision Lifecycle):
১. খুলনা থেকে নিকটতম ৩টি গন্তব্য বের করা হয় (ষাট গম্বুজ মসজিদ ৩১ কিমি, সুন্দরবন ৯২ কিমি, কুয়াকাটা ১১৩ কিমি)।
২. ৩টি গন্তব্যের মধ্যে সবচেয়ে কম খরচেরটিতেও ৩ দিনের মোট খরচ আসে ৳১,৮৬০।
৩. ব্যবহারকারীর বাজেট (৳১০০) সর্বনিম্ন খরচের চেয়ে কম হওয়ায় স্ট্যাটাস কোড সেট হয় BUDGET_TOO_LOW।
৪. নিখুঁত ঘাটতি গণনা করা হয়: ৳১,৮৬০ - ৳১০০ = ৳১,৭৬০।
৫. স্ক্রিনে লাল সতর্কতা জারি করে জানিয়ে দেওয়া হয় যে ১০০ টাকায় ভ্রমণ অসম্ভব এবং সর্বনিম্ন ৳১,৮৬০ লাগবে।

কোডিং সোর্স এভিডেন্স (Code References):
• server/logic.js (লাইন ৫২-৬১): shortfall = minimumIllustrativeBudget - req.budget এবং statusMessage জেনারেশন।
• tests/planner.test.js (লাইন ১২-২১): ৳১০০ বাজেটে ৩টি নিকটতম গন্তব্য ও নিখুঁত ঘাটতির অটোমেটেড টেস্ট (Pass)।

FAQ ৪: ব্রাউজারে API Key এক্সপোজ না হওয়ার নিশ্চয়তা কী? ক্লায়েন্ট কি কখনো এআই স্টুডিওর কী দেখতে পায়?

জিরো-এক্সপোজার আর্কিটেকচার: পূর্বে অনেকে ব্রাউজারের localStorage-এ কী সংরক্ষণ করার চেষ্টা করতেন যা Inspect Element খুললেই দেখা যেত। GhuriAI ৪.০-এ ব্রাউজারে এপিআই কী-এর কোনো অস্তিত্ব নেই।

ডাটা ফ্লো: রিঅ্যাক্ট ব্রাউজার থেকে কেবলমাত্র /api/plan পাথে রিকোয়েস্ট যায়। লোকাল Node.js সার্ভার (server/server.js) তার ইন্টারনাল এনভায়রনমেন্ট (process.env.GEMINI_API_KEY) থেকে কী নিয়ে অফিশিয়াল হেডারে গুগলের সাথে যোগাযোগ করে। ব্রাউজার শুধু প্রস্তুতকৃত ফলাফল পায়; এপিআই কী নেটওয়ার্ক ট্রাফিকেও উন্মুক্ত হয় না।

কোডিং সোর্স এভিডেন্স (Code References):
• server/server.js (লাইন ১৩, ৩৫-৪২): লোকালহোস্ট ভ্যালিডেশন ও সিকিউর প্রক্সি হ্যান্ডলিং।
• src/utils/api.js (লাইন ১-১২): ব্রাউজারের সেইম-অরিজিন এপিআই কল (জিরো কী)।
• SECURITY_NOTES.md: সার্ভার-অনলি ক্রেডেনশিয়াল পলিসি।

FAQ ৫: হ্যাভারসাইন সরলরৈখিক দূরত্ব দিয়ে কি বাংলাদেশের পাহাড়ি বা নদীমাতৃক পথের ভ্রমণ সময় পরিমাপ করা সম্ভব?

সীমাবদ্ধতার সৎ স্বীকারোক্তি: হ্যাভারসাইন সমীকরণ দিয়ে পাখির মতো সোজা দূরত্ব (Air Distance) পাওয়া যায়। কিন্তু পার্বত্য চট্টগ্রাম বা সুন্দরবনের নদীপথে সড়কপথের দূরত্ব ও সময় অনেক বেশি হতে পারে।

GhuriAI-এর সমাধান: GhuriAI কখনোই সোজা দূরত্বের ওপর ভিত্তি করে বাস ভাড়াকে সত্য বলে দাবি করে না। এটি দূরত্বকে শুধুমাত্র প্রাথমিক ৩টি বিকল্প শর্টলিস্ট করার জন্য ব্যবহার করে এবং ব্যবহারকারীকে পরিষ্কার ডিসক্লেইমার দেয় যে—নদী ও পাহাড়ি রুটের সময়সূচি স্থানীয় কাউন্টারে নিশ্চিত করা আবশ্যক।

কোডিং সোর্স এভিডেন্স (Code References):
• server/logic.js (লাইন ৪-৮): airKm ফাংশন।
• server/logic.js (লাইন ৪৭): warnings: ['Straight-line distance, not road distance or travel time...']।

FAQ ৬: সাধারণ পর্যটক এবং অ্যাডমিনের ক্ষমতার পার্থক্য কী? ক্র্যাশ করলেও প্রিসেট ডাটাবেজ কেন নষ্ট হয় না?

পাবলিক বনাম অ্যাডমিন: সাধারণ ভিজিটর যেকোনো প্রিসেটের বাজেট ও দিন পরিবর্তন করে লাইভ হিসাব দেখতে পারেন, কিন্তু সিস্টেমের ১৮টি মূল প্রিসেট ওভাররাইট করতে পারেন না। কেবলমাত্র সার্ভার পাসওয়ার্ড দিয়ে লগইন করা অ্যাডমিন X-CSRF-Token ও HttpOnly সেশন দিয়ে সুরক্ষিত হয়ে প্রিসেট আপডেট করতে পারেন।

অ্যাটমিক পারসিস্টেন্স: সার্ভার সরাসরি ফাইলে লিখে রিস্ক নেয় না। এটি প্রথমে published.json.tmp ফাইলে লিখে এবং সফল হলে ওএস লেভেলে অ্যাটমিক রিনেম (fs.rename) করে। ফলে সার্ভার চলাকালে বিদ্যুৎ চলে গেলেও ডাটা করাপ্ট হয় না।

কোডিং সোর্স এভিডেন্স (Code References):
• server/server.js (লাইন ১০৬-১১৫): fs.rename(temp, storePath) অ্যাটমিক রাইট।
• tests/planner.test.js (লাইন ৮১-১২০): সার্ভার রিস্টার্ট টেস্ট ও পারসিস্টেন্স ভেরিফিকেশন (Pass)।

FAQ ৭: ghuriai-docs নামক AI Skill তৈরি করার উদ্দেশ্য কী এবং কীভাবে এটি গবেষক বা নতুন ডেভেলপারের কাজে লাগে?

উদ্দেশ্য: প্রজেক্টের কোড জটিল হলেও যেন যেকোনো নতুন এআই এজেন্ট বা গবেষক এক ক্লিকে পুরো সিস্টেমের আর্কিটেকচার, হ্যাভারসাইন গণিত ও ট্রাবলশুটিং নির্দেশিকা বুঝতে পারেন।

কাঠামো: এটি .agents/skills/ghuriai-docs/ ডিরেক্টরিতে অবস্থিত। এতে SKILL.md ছাড়াও ৬টি রেফারেন্স মডিউল (আর্কিটেকচার, গণিত, রেসপন্সিবল এআই, সিকিউরিটি, প্রিসেট, ট্রাবলশুটিং) এবং একটি স্বয়ংক্রিয় পাওয়ারশেল হেলথ চেকার (verify-system.ps1) রয়েছে।

কোডিং সোর্স এভিডেন্স (Code References):
• .agents/skills/ghuriai-docs/SKILL.md: মূল এআই ডিরেক্টিভ।
• .agents/skills/ghuriai-docs/scripts/verify-system.ps1: স্বয়ংক্রিয় সিস্টেম ভেরিফায়ার।

৩. HTML প্রজেক্ট: প্রতিটি ফাইলের কাজ ও অবস্থান

HTML প্রজেক্টটি c:\Versity\GhuriAI\ রুট ফোল্ডারে অবস্থান করছে। নিচে প্রতিটি ফাইলের বিস্তারিত কাজ উল্লেখ করা হলো:

ফাইলের নাম ও পাথ ফাইলটির কাজ ও বিশেষত্ব কোন কোন ফাইলের সাথে সম্পর্কযুক্ত
index.html প্রধান ল্যান্ডিং পেজ। এতে রয়েছে হিরো ব্যানার, বাজেট-ফার্স্ট কুইক প্ল্যানার, আকর্ষণীয় ফিচার হাইলাইটস এবং কুইক স্ট্যাটস। assets/css/style.css, assets/js/app.js, planner.html, explore.html
explore.html বাংলাদেশের ১৮টি ট্যুরিস্ট স্পটের ক্যাটালগ। এতে ক্যাটাগরি ট্যাব, বিভাগ ড্রপডাউন এবং রিয়েল-টাইম সার্চ রয়েছে। প্রতিটি কার্ডের "Plan Trip" বাটন প্রিসেট পেজে পাঠায়। assets/js/app.js (ডেস্টিনেশন ডেটা), preset.html?id=<id>
preset.html নির্দিষ্ট ডেস্টিনেশনের প্রিসেট ভিউয়ার। এতে যাত্রা শুরু ও গন্তব্য ফিক্সড (Locked Route) থাকে। ব্যবহারকারী বাজেট/দিন পরিবর্তন করে লাইভ হিসেব করতে পারেন। অ্যাডমিন লগইন থাকলে প্রিসেট আপডেট বাটন দেখা যায়। assets/js/preset.js, data/presets.json, server/server.cjs (/api/presets)
planner.html পূর্ণাঙ্গ বাজেট-ফার্স্ট এআই ট্রিপ প্ল্যানার। "AI Suggest" সিলেক্ট করলে নিকটতম ৩টি গন্তব্য কার্ডসহ পূর্ণাঙ্গ হিসেব টেবিল ও আইটিনারারি তৈরি করে। assets/js/app.js, server/logic.cjs
admin.html অ্যাডমিন লগইন ও ১৮টি ডেস্টিনেশনের প্রিসেট ম্যানেজমেন্ট ড্যাশবোর্ড (পাসওয়ার্ড: admin123)। preset.html, server/server.cjs (/api/admin/login)
docs.html এই পূর্ণাঙ্গ ডেভেলপার গাইড ও স্টাডি টিউটোরিয়াল পেজ (সার্চ ও স্টিকি সাইডবার সহ)। assets/css/style.css
assets/css/style.css সম্পূর্ণ প্রজেক্টের Authoritative CSS। সমস্ত কালার ভ্যারিয়েবল, কাস্টম ড্রপডাউনের `12px` বর্ডার রেডিয়াস, বাটন/কার্ডের `6px` রেডিয়াস এবং রেসপনসিভ গ্রিড নির্ধারণ করে। প্রজেক্টের সকল HTML ফাইলের সাথে সংযুক্ত।
assets/js/app.js কোর ফ্রন্টএন্ড জাভাস্ক্রিপ্ট। `initCustomDropdowns()` ফাংশন দিয়ে সাইটের সমস্ত কাস্টম ড্রপডাউন ইনিশিয়ালাইজ করে, ১৮টি গন্তব্যের লোকাল ডেটা অ্যারে ধারণ করে এবং ফিল্টারিং পরিচালনা করে। index.html, explore.html, planner.html
assets/js/preset.js প্রিসেট পেজের স্পেশাল কন্ট্রোলার। ঢাকা টাইমস্ট্যাম্প (`Asia/Dhaka`) ফরম্যাট করে, প্রিন্ট হ্যান্ডেল করে এবং অ্যাডমিনের আপডেট রিকোয়েস্ট পাঠায়। preset.html
data/places.json ১৮টি গন্তব্য ও ১০টি বিভাগীয় শহরের অক্ষাংশ-দ্রাঘিমাংশ, নন-এসি/এসি যাতায়াত বেস ভাড়া, হোটেল রুম রেট এবং খাবারের খরচ সূচক। server/logic.cjs, server/server.cjs
data/presets.json ১৮টি ডেস্টিনেশনের সংরক্ষিত প্রিসেট তথ্য (বাজেট, সদস্য, দিন ও পাবলিশড স্ট্যাটাস)। preset.html, server/server.cjs

৫. HTML ফাইলগুলোর পারস্পরিক সংযোগ ও কাজের প্রবাহ

HTML প্রজেক্টে ফাইলগুলো কীভাবে একে অপরের সাথে কথা বলে তা শিক্ষার্থীদের জন্য একটি ফ্লো-চার্ট আকারে দেখানো হলো:

[index.html] │ (ইউজার কুইক প্ল্যানার পূরণ করল) ├───> URL Parameters দিয়ে পাঠায় ───> [planner.html] │ │ (লোকাল লজিক বা /api/plan এ রিকোয়েস্ট) │ └───> তৈরি হয় ক্যালকুলেটেড প্ল্যান ও প্রিন্ট ভিউ [explore.html] │ (১৮টি কার্ডের যেকোনোটিতে "Plan Trip" চাপল) └───> preset.html?id=coxs-bazar │ ├──> [assets/js/preset.js] URL থেকে 'id' পড়ে ├──> ডেটা নিয়ে আসে /api/presets/coxs-bazar অথবা data/presets.json থেকে ├──> From ও To ফিক্সড (Locked) রেখে ফর্ম সাজায় │ ├── [সাধারণ ভিজিটর হলে]: │ └── "Generate AI Plan" বাটনে লাইভ হিসেব দেখে ও প্রিন্ট করে │ └── [অ্যাডমিন লগইন থাকলে (admin.html)]: └── "Update Current Preset" সক্রিয় হয় এবং প্রিসেট স্থায়ী আপডেট হয়!

৬. server/*.cjs ফাইলসমূহ ও তাদের ভূমিকা

server/ ফোল্ডারটি HTML প্রজেক্টের অবিচ্ছেদ্য অংশ

রুট ফোল্ডারে থাকা server/ ফোল্ডারের স্ক্রিপ্টগুলো HTML প্রজেক্টের ব্যাকএন্ড এপিআই সার্ভার এবং স্বয়ংক্রিয় টেস্ট পরিচালনার জন্য তৈরি করা হয়েছে।

স্ক্রিপ্ট নাম কাজের বিবরণ কীভাবে টেস্ট বা রান করবেন
server/server.cjs জিরো-ডিপেন্ডেন্সি নোড HTTP 1.1 সার্ভার (Port 3000)। /api/plan, /api/presets/:id এবং অ্যাডমিন সেশন কুকি হ্যান্ডেল করে। node server/server.cjs
server/logic.cjs বিশুদ্ধ গাণিতিক ক্যালকুলেটর ইঞ্জিন। এতে Haversine সূত্র, ৳১০০ বাজেট শর্টফল লজিক, রুম হিসাব এবং দিনভিত্তিক আইটিনারারি ফাংশন রয়েছে। server/server.cjs এবং test.cjs কর্তৃক ইম্পোর্টকৃত
server/test.cjs ইউনিট টেস্ট সুইট। ১৮টি ডেস্টিনেশন ভ্যালিডেশন, ৳১০০ এজ কেস, Haversine দূরত্ব এবং রুম রিকোয়ারমেন্ট নিখুঁতভাবে যাচাই করে। node server/test.cjs (৭/৭ পাস)
server/integration_test.cjs এন্ড-টু-এন্ড এইচটিটিপি ইন্টিগ্রেশন টেস্ট। সার্ভারের সমস্ত এন্ডপয়েন্ট ও এডমিন সিকিউরিটি লাইভ পোর্ট ৩০০০-এ যাচাই করে। node server/integration_test.cjs (৮/৮ পাস)

৭. React প্রজেক্ট: প্রতিটি ফাইলের কাজ ও অবস্থান

React সংস্করণটি c:\Versity\GhuriAI\GhuriAI_React\ ফোল্ডারে একটি স্বয়ংসম্পূর্ণ রুট হিসেবে গঠিত। নিচে এর প্রতিটি ফাইলের কাজ বিশদভাবে ব্যাখ্যা করা হলো:

ফাইলের নাম ও পাথ ফাইলটির কাজ ও দায়িত্ব সম্পর্কিত উপাদান
package.json প্রজেক্টের ডিপেন্ডেন্সি (React 18, React DOM, Vite) ও স্ক্রিপ্ট কমান্ড (`dev`, `build`, `preview`) ধারণ করে। npm install, npm run dev
vite.config.js Vite বিল্ড কনফিগারেশন ও React প্লাগইন ইন্টিগ্রেশন। Vite ইঞ্জিন
src/main.jsx React অ্যাপ্লিকেশনের প্রবেশদ্বার (Entrypoint)। `index.html`-এর `#root` ডিভে `App.jsx` মাউন্ট করে। index.html, App.jsx
src/App.jsx মাস্টার কন্ট্রোলার ও স্টেট ম্যানেজার। `activePage` ট্র্যাক করে, ব্রাউজার হ্যাশ হ্যান্ডেল করে (`#explore`, `#planner`, `#admin`, `#docs`), এবং `Navbar`, অ্যাক্টিভ পেজ ও `Footer` রেন্ডার করে। সকল পেজ ও কম্পোনেন্ট
src/components/SearchableDropdown.jsx PROJECT_RULES.md-এর বাধ্যতামূলক কাস্টম ড্রপডাউন কম্পোনেন্ট (জিরো নেটিভ ` HomePage, ExplorePage, PresetDetailPage, PlannerPage
src/components/Navbar.jsx ব্র্যান্ড লোগো, এক্টিভ পেজ ইন্ডিকেটর ও অ্যাডমিন ড্যাশবোর্ড শর্টকাট সহ রেসপনসিভ হেডার। App.jsx
src/components/Footer.jsx কুইক লিংকস, কপিরাইট এবং প্রজেক্ট আর্কিটেকচার ব্যাজ সহ গ্লোবাল ফুটার। App.jsx
src/pages/HomePage.jsx বাজেট-ফার্স্ট ফ্লোটিং প্ল্যানার কার্ড, হিরো ব্যানার এবং কুইক স্ট্যাটস। SearchableDropdown, App.jsx
src/pages/ExplorePage.jsx ১৮টি ফিল্টারেবল ও সার্চেবল গন্তব্য কার্ড। কার্ডে ক্লিক করলে প্রিসেট পেজে পাঠায়। SearchableDropdown, places.json
src/pages/PresetDetailPage.jsx ফিক্সড রুট প্রিসেট প্ল্যানার, ঢাকা টাইমস্ট্যাম্প, লাইভ ক্যালকুলেশন, প্রিন্ট এক্সপোর্ট এবং অ্যাডমিনের জন্য "Update Current Preset" বাটন। calculator.js, SearchableDropdown
src/pages/PlannerPage.jsx পূর্ণাঙ্গ বাজেট-ফার্স্ট ট্রিপ প্ল্যানার। "AI Suggest" সিলেক্ট করলে সেরা ৩টি নিকটবর্তী অপশন সাজেস্ট করে এবং পূর্ণাঙ্গ হিসেব টেবিল দেখায়। calculator.js, SearchableDropdown
src/pages/DocsPage.jsx রিয়েল-টাইম সার্চ ইনপুট ও স্টিকি সাইডবার যুক্ত সম্পূর্ণ ডেভেলপার গাইড ও টিউটোরিয়াল। App.jsx
src/pages/AdminPage.jsx অ্যাডমিন লগইন (পাসওয়ার্ড: `admin123`) এবং ১৮টি প্রিসেটের লাইভ ম্যানেজমেন্ট টেবিল। PresetDetailPage
src/utils/calculator.js ক্লায়েন্ট-সাইড ডিটারমিনিস্টিক ক্যালকুলেটর। Haversine দূরত্ব সূত্র, খরচের খাতভিত্তিক হিসাব, ৳১০০ বাজেট শর্টফল হ্যান্ডলিং এবং ঢাকা টাইমস্ট্যাম্প ফরম্যাটিং। PlannerPage, PresetDetailPage, HomePage
src/data/places.json & presets.json React প্রজেক্টের নিজস্ব লোকাল ডেটাসেট (বাহ্যিক কোনো সার্ভার ছাড়াই স্বয়ংসম্পূর্ণভাবে চলার জন্য)। calculator.js, পেজসমূহ

৮. React কম্পোনেন্ট ট্রি ও স্টেট ম্যানেজমেন্ট

React অ্যাপ্লিকেশনে ডেটা কীভাবে পেরেন্ট থেকে চাইল্ড কম্পোনেন্টে পাস হয় তা শিক্ষার্থীদের জন্য বিশ্লেষণ করা হলো:

[App.jsx] (মাস্টার স্টেট: activePage, selectedPresetId, isAdmin) │ ┌────────────────────────────────┼────────────────────────────────┐ ▼ ▼ ▼ [Navbar.jsx] [Active Page View] [Footer.jsx] │ ┌──────────────┬───────────────┼───────────────┬──────────────┐ ▼ ▼ ▼ ▼ ▼ [HomePage] [ExplorePage] [PresetDetail] [PlannerPage] [AdminPage] │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ [SearchableDropdown] ──> PROJECT_RULES.md (12px Radius, Zero <select>, Live Search) │ ▼ [src/utils/calculator.js] ──> Pure Client Math (Haversine & Deterministic Calculation)

৯. Haversine দূরত্ব সূত্র ও খরচের সমীকরণ

পৃথিবী সম্পূর্ণ সমতল নয়, তাই সাধারণ জ্যামিতিক সূত্রে দূরত্ব বের করলে ভুল হবে। GhuriAI-তে গ্রেট-সার্কেল দূরত্ব পরিমাপের জন্য বিশ্বমানের Haversine Formula ব্যবহার করা হয়েছে:

HAVERSINE MATHEMATICAL IMPLEMENTATION (JAVASCRIPT)
function airKm(pointA, pointB) {
  const R = 6371; // পৃথিবীর গড় ব্যাসার্ধ (কিলোমিটারে)
  const toRad = (deg) => (deg * Math.PI) / 180;
  
  const dLat = toRad(pointB.lat - pointA.lat);
  const dLon = toRad(pointB.lon - pointA.lon);
  
  const a = Math.sin(dLat / 2) ** 2 +
            Math.cos(toRad(pointA.lat)) * Math.cos(toRad(pointB.lat)) *
            Math.sin(dLon / 2) ** 2;
            
  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
  return Math.round(R * c);
}

খরচের ৪টি প্রধান খাতের হিসাব সূত্র:

  • ১. যাতায়াত খরচ (Transport):
    RoundTrip = DistanceKm × 2
    মোট যাতায়াত = RoundTrip × সদস্য সংখ্যা × প্রতি কিমি রেট (বা বেস ফেয়ার)
  • ২. আবাসন খরচ (Accommodation):
    প্রয়োজনীয় রুম = Math.ceil(সদস্য সংখ্যা / 2)
    ১ দিনের ডে-ট্যুরে রুম খরচ = ৳০। একাধিক দিনের ক্ষেত্রে: রুম সংখ্যা × (দিন - ১) × রুম রেট
  • ৩. খাবার খরচ (Food):
    সদস্য সংখ্যা × দিন × ৩ বেলা পুষ্টিকর খাবারের গড় বরাদ্দ
  • ৪. সাইটসিয়িং ও এন্ট্রি ফি (Activities):
    সদস্য সংখ্যা × স্থানীয় পর্যটন পয়েন্ট ও গাইডিং ফি

১০. বাজেট ঘাটতি ও ৳১০০ অসম্ভব বাজেট কেস স্টাডি

বাস্তবসম্মত সিস্টেম বিহেভিয়ার

কোনো ব্যবহারকারী যদি অবাস্তব কম বাজেট (যেমন ৳১০০) দিয়ে ট্যুর প্ল্যান তৈরি করতে চান, সিস্টেম কাল্পনিক ডেটা বানিয়ে ব্যবহারকারীকে বিভ্রান্ত করে না।

সিস্টেম যেভাবে হ্যান্ডেল করে:
১. অ্যালগরিদম তাৎক্ষণিকভাবে স্টার্টিং পয়েন্ট থেকে সবচেয়ে কাছের ৩টি স্পট খুঁজে বের করে।
২. সেই দূরত্বের জন্য রিয়েল-ওয়ার্ল্ড সর্বনিম্ন প্রয়োজনীয় খরচ হিসাব করে (যেমন ৳২,২০০)।
৩. ঘাটতি হিসাব করে: ঘাটতি = সর্বনিম্ন খরচ (৳২,২০০) - ইউজারের বাজেট (৳১০০) = ৳২,১০০।
৪. ইউজারকে পরিষ্কারভাবে লাল সতর্কবার্তা দিয়ে জানিয়ে দেয়: "আপনার প্রদত্ত বাজেট (৳১০০) দিয়ে কোনো বাস্তবসম্মত ট্রিপ সম্পন্ন করা সম্ভব নয়। নিকটতম গন্তব্যে ভ্রমণের জন্য সর্বনিম্ন ৳২,২০০ বাজেট প্রয়োজন (ঘাটতি: ৳২,১০০)।"

১১. জেমিনি এআই নিয়ন্ত্রণ নীতিমালা (AI Guardrails)

GhuriAI-তে কৃত্রিম বুদ্ধিমত্তা ব্যবহারের ক্ষেত্রে ৩টি কঠোর নীতি মেনে চলা হয়:

  • ১. জিরো প্রাইজ হ্যালুসিনেশন: AI কখনো সরাসরি ট্রাভেল খরচ বা টাকার অংক নির্ধারণ করে না। সমস্ত ক্যালকুলেশন বিশুদ্ধ কোডে সম্পন্ন হওয়ার পর AI-কে শুধুমাত্র সেই তথ্যের ভিত্তিতে আকর্ষণীয় গল্প ও ডেসক্রিপশন লিখতে বলা হয়।
  • ২. নিরাপদ দিবালোক সূচি (Daylight Itinerary): রাতে অনিরাপদ ভ্রমণ পরিহার করে শুধুমাত্র সকাল, দুপুর ও শেষ বিকেলের উপযুক্ত দর্শনীয় স্থানসমূহের সময়সূচি তৈরি করতে AI বাধ্য থাকে।
  • ৩. ১০০% অফলাইন ফলব্যাক: জেমিনি এপিআই-তে নেটওয়ার্ক ব্যর্থতা হলেও প্রজেক্ট বন্ধ হয় না; সাথে সাথে বিল্ট-ইন স্ট্যাটিক আইটিনারারি স্ক্রিনে প্রদর্শিত হয়।

১২. নতুন Windows পিসিতে ফ্রেশ সেটআপ ও সফটওয়্যার ডাউনলোড লিংক

একটি সম্পূর্ণ নতুন বা ফ্রেশ ইনস্টল করা Windows 10/11 কম্পিউটারে GhuriAI রান করানোর জন্য নিচের সফটওয়্যারগুলো ইনস্টল করুন। এখানে অফিশিয়াল সাইটের সোর্স লিংক এবং CLI কমান্ড উভয়ই দেওয়া হলো:

সফটওয়্যার ও অফিসিয়াল সোর্স প্রস্তাবিত ভার্সন ব্যবহার CLI ইনস্টলেশন কমান্ড (PowerShell)
Node.js LTS
nodejs.org/download
v20+ / v26.13.1 LTS (npm v11+) React Vite ও Express টেস্ট সার্ভার winget install OpenJS.NodeJS.LTS
Git for Windows
git-scm.com/downloads
v2.40.0+ কোড ক্লোন ও ভার্সন কন্ট্রোল winget install Git.Git
Visual Studio Code (VS Code)
code.visualstudio.com
Latest Stable প্রধান কোড এডিটর ও টার্মিনাল winget install Microsoft.VisualStudioCode
Google Chrome Browser
google.com/chrome
Latest ওয়েব প্রেভিউ ও ডিবাগিং সিস্টেম ব্রাউজার

প্রয়োজনীয় VS Code এক্সটেনশন (Plugins) ও সোর্স লিংক:

POWERSHELL (ADMIN) — এক ক্লিকে ইনস্টলেশন
winget install OpenJS.NodeJS.LTS --silent --accept-package-agreements --accept-source-agreements
winget install Git.Git --silent --accept-package-agreements --accept-source-agreements
winget install Microsoft.VisualStudioCode --silent --accept-package-agreements --accept-source-agreements

# ইনস্টলেশন যাচাই করুন:
node -v
npm -v
git --version

১৩. ট্রাবলশুটিং ও খুঁটিনাটি সমস্যার সমাধান (Troubleshooting FAQ)

সমস্যা: npm : The term 'npm' is not recognized বা node : The term 'node' is not recognized

নতুন Node.js ইনস্টল করার পর PowerShell টার্মিনালে npm run dev দিলে যদি এই এরর দেখায়, তবে আতঙ্কিত হবেন না। এটি একটি অতি পরিচিত ও স্বাভাবিক উইন্ডোজ টার্মিনাল আচরণ।

কেন এই সমস্যাটি হয়? (Root Cause Analysis):

Windows অপারেটিং সিস্টেমে যখন কোনো নতুন সফটওয়্যার ইনস্টল হয়, তখন সিস্টেম PATH ভ্যারিয়েবল আপডেট হয়। কিন্তু আপনি যদি Node.js ইনস্টল করার আগেই VS Code বা PowerShell টার্মিনাল খুলে রাখেন, তবে সেই চালু থাকা সেশনটি ইনস্টলেশনের আগের পুরোনো PATH মেমোরিতে ধরে রাখে। ফলে টার্মিনাল নতুন ইনস্টল হওয়া node বা npm খুঁজে পায় না।

সমাধানের পরীক্ষিত উপায়সমূহ:

উপায় ১ (সবচেয়ে দ্রুত): বর্তমান টার্মিনালেই ইনস্ট্যান্ট সলভ
# ১. বর্তমান ওপেন থাকা টার্মিনালে সরাসরি PATH রিফ্রেশ করুন:
$env:PATH = "C:\Program Files\nodejs;" + $env:PATH

# ২. সার্ভার ও ফ্রন্টএন্ড চালুর কমান্ড:
# Terminal 1 (API Server):
npm run server

# Terminal 2 (Vite Frontend):
npm run dev
উপায় ২: সরাসরি পাথ দিয়ে রান করা (পাথ পরিবর্তন না করেই)
# Terminal 1:
& 'C:\Program Files\nodejs\npm.cmd' run server

# Terminal 2:
& 'C:\Program Files\nodejs\npm.cmd' run dev
উপায় ৩ (স্থায়ী সমাধান): উইন্ডোজ এনভায়রনমেন্ট ভেরিয়েবলে PATH যুক্ত করা

টার্মিনালে একবার নিচের PowerShell কমান্ডটি চালালে ব্যবহারকারীর প্রোফাইলে Node.js স্থায়ীভাবে যুক্ত হয়ে যাবে:

[Environment]::SetEnvironmentVariable("PATH", [Environment]::GetEnvironmentVariable("PATH", "User") + ";C:\Program Files\nodejs", "User")

এরপর VS Code বা টার্মিনাল রিস্টার্ট করলেই যেকোনো নতুন টার্মিনালে সরাসরি npm run dev ও npm run server কাজ করবে।

অন্যান্য সাধারণ খুঁটিনাটি সমস্যার সমাধান:

১. PowerShell Script Execution Policy Error (PSSecurityException):
উইন্ডোজে কখনো vite.ps1 cannot be loaded because running scripts is disabled এরর আসলে PowerShell-এ একবার চালান:

POWERSHELL — স্ক্রিপ্ট রান পারমিশন ফিক্স
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

২. পোর্ট কনফ্লিক্ট (Port 5173 বা Port 3000 ইতোমধ্যে ব্যস্ত):
যদি পোর্ট ব্যস্ত থাকে, তবে Vite স্বয়ংক্রিয়ভাবে পরবর্তী পোর্ট (যেমন 5174) বেছে নেয়, অথবা আপনি ম্যানুয়ালি পোর্ট নির্ধারণ করে দিতে পারেন:

POWERSHELL — বিকল্প পোর্টে রান
npm run dev -- --port 5174

১৪. সিএলআই টেস্ট সুইট ও এভিডেন্স

প্রজেক্টের হিসাবের নির্ভুলতা, দূরত্ব নির্ণয় এবং ৳১০০ বাজেট এজ কেস যাচাই করার জন্য স্বয়ংক্রিয় টেস্ট স্ক্রিপ্ট অন্তর্ভুক্ত রয়েছে:

POWERSHELL — টেস্ট সুইট এক্সিকিউশন
# ইউনিট টেস্ট রান করুন
node server/test.cjs

# এন্ড-টু-এন্ড এইচটিটিপি ইন্টিগ্রেশন টেস্ট রান করুন
node server/integration_test.cjs
সফল টেস্ট আউটপুট (Evidence)
--- Running GhuriAI Acceptance Test Suite ---
✔ Test 1: Canonical 18 destinations verified
✔ Test 2: Low budget (৳100) edge case and shortfall calculated properly
✔ Test 3: AI Suggest sorting by nearest geographic distance confirmed
✔ Test 4: Deterministic cost breakdown arithmetic verified
✔ Test 5: 1-Day tour room cost calculation verified
✔ Test 6: Input validation and rejection of invalid data verified
✔ Test 7: Haversine distance formula sanity verified
====================================================
Result: 7 passed, 0 failed. All acceptance tests verified.

১৫. কাস্টম ড্রপডাউন ও ১০০% ভিজ্যুয়াল প্যারিটি (PROJECT_RULES.md)

PROJECT_RULES.md অনুসারে HTML ভার্সনই হলো প্রজেক্টের Authoritative Master Template। React অ্যাপ্লিকেশনটি (GhuriAI_React) অবশ্যই HTML ভার্সনের সাথে ১০০% হুবহু ভিজ্যুয়াল ও লেআউট ডুপ্লিকেট (Exact Clone) হতে হবে। কোনো পেজ বা কম্পোনেন্টে ইন্টারফেসের ভিন্নতা সম্পূর্ণ নিষিদ্ধ।

Page-by-Page 100% Parity Matrix
  • index.html ⟷ HomePage.jsx: হিরো ব্যানার, ফ্লোটিং কুইক প্ল্যানার কার্ড, ৪টি ফিচার পিল কার্ড (AI Itinerary, Budget Planner, Verified Info, Bangladesh Focus), ৬টি ডেসটিনেশন কার্ড উইশলিস্ট হার্ট বাটন সহ, এবং ৪-কলাম ডার্ক নেভি ফুটার।
  • planner.html ⟷ PlannerPage.jsx: ডার্ক টিল টপ ব্যানার, আনুভূমিক কনফিগারেশন কার্ড (বাজেট, ভ্রমণকারী, দিন, যাত্রা শুরু / গন্তব্য + Generate AI Plan বাটন), রেজাল্ট সামারি বার, ৩টি কস্ট কার্ড (৪০% যাতায়াত, ৩৫% থাকা, ২৫% খাবার), দিনভিত্তিক টাইমলাইন ও ৩টি পরামর্শ কার্ড।
  • explore.html ⟷ ExplorePage.jsx: লাইভ সার্চ বক্স, বিভাগ ড্রপডাউন, ৬টি ক্যাটাগরি পিল, সর্ট ড্রপডাউন এবং ১৮টি কার্ডের গ্রিড।
  • docs.html ⟷ DocsPage.jsx: সার্চ সাইডবার, ১৫টি বিস্তারিত টেকনিক্যাল সেকশন এবং ক্লিকের সুবিধা।

কাস্টম ড্রপডাউন স্পেসিফিকেশন (জিরো নেটিভ <select>):

  • ওপেন মেনু বর্ডার রেডিয়াস: border-radius: 12px
  • অন্যান্য সাধারণ উপাদান রেডিয়াস: সর্বোচ্চ border-radius: 6px (বৃত্তাকার উপাদান ব্যতীত)
  • শ্যাডো: box-shadow: 0 10px 30px rgba(0, 0, 0, 0.12), 0 2px 6px rgba(0, 0, 0, 0.04)
  • সার্চ বার: মেনুর শীর্ষে ইন্টিগ্রেটেড সার্চ ফিল্টার যা বাংলা ও ইংরেজি দুই ভাষাতেই অপশন ফিল্টার করে।
  • আইকন প্রিফিক্স সুরক্ষা: ফন্টঅসাম ৬-এর আইকন যেন চারকোনা বাক্স (□) না দেখায়, সেজন্য প্রতিটি আইকন স্ট্রিং স্বয়ংক্রিয়ভাবে fa-solid fa-... দিয়ে নরমালাইজ করা হয়।
  • ইন্টারঅ্যাকশন: বাইরে ক্লিক করলে বা Escape চাপলে স্বয়ংক্রিয়ভাবে বন্ধ হয়। একটি ড্রপডাউন খুললে অন্যগুলো বন্ধ হয়ে যায়।

১৬. গুগল এআই স্টুডিও API Key তৈরি, সিকিউর ভল্ট ও .gitignore সুরক্ষা

জিরো এক্সপোজার সিকিউরিটি নীতি (Zero Exposure Principle)

গুগল এআই স্টুডিও API Key আপনার ব্যক্তিগত ডিজিটাল সম্পদ। GhuriAI আর্কিটেকচারে কি-টি কখনোই কোনো এআই মডেল বা বাহ্যিক ব্যক্তির কাছে প্লেইন টেক্সট হিসেবে উন্মুক্ত হয় না। এটি ব্রাউজারের এনক্রিপ্টেড লোকাল ভল্টে অথবা পরিবেশ ভ্যারিয়েবল (.env.local)-এ সম্পূর্ণ সুরক্ষিত থাকে।

ধাপ ১: Google AI Studio থেকে ফ্রি API Key সংগ্রহ করার নিয়ম

Google AI Studio বিশ্বমানের Gemini 2.5 Flash মডেলের জন্য ডেভেলপারদের প্রতি মিনিটে ১৫টি রিকোয়েস্ট (15 RPM) এবং বিশাল টোকেন কোটা সম্পূর্ণ বিনামূল্যে (Free of Cost) প্রদান করে:

  1. যেকোনো ব্রাউজারে প্রবেশ করুন: https://aistudio.google.com/
  2. আপনার ব্যক্তিগত বা প্রাতিষ্ঠানিক Google Account দিয়ে Sign In করুন।
  3. স্ক্রিনের ওপরের বাঁ-পাশের সাইডবার মেনু থেকে "Get API key" বাটনে ক্লিক করুন।
  4. নতুন উইন্ডোতে "Create API key" বাটনে চাপ দিন এবং "Create key in new project" অথবা আপনার বিদ্যমান Google Cloud Project সিলেক্ট করুন।
  5. মুহূর্তের মধ্যে AIzaSy... দিয়ে শুরু হওয়া একটি সিক্রেট API Key তৈরি হবে। Copy আইকনে ক্লিক করে কি-টি কপি করে নিন।

ধাপ ২: GhuriAI অ্যাডমিন প্যানেলে সিকিউর ভল্টে সেট করার নিয়ম

কপি করা এপিআই কি-টি সহজে এবং নিরাপদে অ্যাপ্লিকেশনে সেট করতে অ্যাডমিন প্যানেল ব্যবহার করুন:

  1. ব্রাউজারে GhuriAI-এর অ্যাডমিন পেজে যান: http://localhost:5173/#admin (React) অথবা admin.html (HTML)।
  2. অ্যাডমিন পাসওয়ার্ড admin123 প্রবেশ করিয়ে লগইন করুন।
  3. ড্যাশবোর্ডের শীর্ষে "Google AI Studio Gemini API Key — সিকিউর ভল্ট" কার্ডটি দেখতে পাবেন।
  4. ইনপুট বক্সে আপনার কপি করা কি-টি পেস্ট করুন। লক্ষ করবেন, এটি পাসওয়ার্ড ফিল্ড (type="password") হওয়ার কারণে স্ক্রিনে বুলেট (••••••••••••) হিসেবে মাস্কড থাকে।
  5. "🔒 এনক্রিপ্ট করে সিকিউর ভল্টে সেভ করুন" বাটনে ক্লিক করুন।
  6. সিস্টেম সাথে সাথে কি-টিকে ক্রিপ্টোগ্রাফিক সল্ট সহ মেমোরিতে এনক্রিপ্ট করে localStorage-এ সংরক্ষণ করবে এবং স্ক্রিনে সেফ মাস্কড ফরম্যাট (যেমন: AIzaSy••••••••••••••••••••••••••••4bX9) প্রদর্শন করবে।
  7. "টেস্ট কানেকশন (Ping Gemini)" বাটনে ক্লিক করে সাথে সাথে যাচাই করুন যে Google Gemini API সক্রিয় ও সচল হয়েছে!

বিকল্প পদ্ধতি: .env.local ফাইলে সংরক্ষণ (Environment Variable)

আপনি যদি ব্রাউজারের পরিবর্তে পিসির ফাইলে কি রাখতে চান, তবে React প্রজেক্ট রুটে .env.local ব্যবহার করতে পারেন:

GHURIAI_REACT/.ENV.LOCAL — কনফিগারেশন ফাইল
# c:\Versity\GhuriAI\GhuriAI_React\.env.local
VITE_GEMINI_API_KEY=AIzaSyআপনার_কপি_করা_এপিআই_কি
VITE_GEMINI_MODEL=gemini-2.5-flash

সুরক্ষা কবচ: .gitignore ফাইলের গুরুত্ব ও ভূমিকা

কেন কোনো অবস্থাতেই API Key গিটহাবে পুশ করবেন না?

পাবলিক গিট রিপোজিটরিতে ভুলবশত এপিআই কি পুশ হয়ে গেলে স্বয়ংক্রিয় রোবট/বটরা কয়েক সেকেন্ডের মধ্যে সেই কি চুরি করে কোটা অপব্যবহার করতে পারে।

GhuriAI যেভাবে আপনাকে শতভাগ সুরক্ষা দেয়:
উভয় প্রজেক্ট রুটে (c:\Versity\GhuriAI\.gitignore এবং c:\Versity\GhuriAI\GhuriAI_React\.gitignore) নিচের প্যাটার্নগুলো যুক্ত রয়েছে:

.GITIGNORE — সিক্রেট ফাইল প্রটেকশন রুলস
# Environment & API Key Files (Never commit API keys!)
.env
.env.local
.env.*.local
*.env
*.local

এর ফলে আপনি টার্মিনালে git add . বা git commit করলেও Git স্বয়ংক্রিয়ভাবে .env.local ফাইলটিকে সম্পূর্ণ উপেক্ষা (ignore) করে। ফলে আপনার সিক্রেট কি কখনো গিটহাব বা ইন্টারনেটে ফাঁস হতে পারবে না।