প্রকল্প সম্পর্কে

## ওভারভিউ Traffic Analytics হলো Ghost সাইটগুলোর জন্য ডিজাইন করা একটি ওয়েব-অ্যানালিটিক্স প্রক্সি। এটি Ghost-এর `ghost-stats.js` স্ক্রিপ্ট দ্বারা করা `POST /api/v1/page_hit` কলগুলোকে ইন্টারসেপ্ট করে, পেলোডটিকে সমৃদ্ধ করে (ইউজার-এজেন্ট পার্সিং, রেফারার বিশ্লেষণ, ইউজার সিগনেচার জেনারেশন) এবং ডেটাটিকে Tinybird-এর `/v0/events` API-তে পাঠায়, যেখানে এটি একটি ClickHouse ডেটাবেসে সংরক্ষিত হয়। ## আর্কিটেকচার এবং রান মোড - **ব্যাচ মোড (ডিফল্ট)** – ইনজেস্ট সার্ভিস রিকোয়েস্টগুলো যাচাই করে, বট ফিল্টার করে এবং র-ইভেন্টগুলোকে একটি Google Cloud Pub/Sub টপিকে পাবলিশ করে। একটি আলাদা ওয়ার্কার সাবস্ক্রিপশন থেকে ডেটা গ্রহণ করে, প্রতিটি ইভেন্টকে সমৃদ্ধ করে, সেগুলোকে ব্যাচ করে এবং Tinybird-এ পাঠায়। এটি রিকোয়েস্ট হ্যান্ডলিং এবং ইনজেশনের মধ্যে পার্থক্য তৈরি করে এবং থ্রুপুট উন্নত করে। - **প্রক্সি মোড (সিনক্রোনাস)** – যখন কোনো Pub/Sub টপিক কনফিগার করা থাকে না, তখন ইনজেস্ট সার্ভিস সরাসরি ইনলাইন সমৃদ্ধকরণ সম্পন্ন করে এবং একই HTTP সাইকেলে রিকোয়েস্টটি সরাসরি Tinybird-এ প্রক্সি করে। মোডটি `WORKER_MODE` এনভায়রনমেন্ট ভেরিয়েবল এবং `PUBSUB_TOPIC_PAGE_HITS_RAW`-এর উপস্থিতির মাধ্যমে নির্বাচন করা হয়। ## মূল বৈশিষ্ট্যসমূহ - OS, ব্রাউজার এবং ডিভাইস শনাক্তকরণের জন্য ইউজার-এজেন্ট পার্সিং। - রেফারার URL পার্সিং এবং ক্যাটাগরাইজেশন। - দৈনিক পরিবর্তনশীল সল্ট (salts) সহ প্রাইভেসী-প্রিজার্ভিং ইউজার সিগনেচার। - ফিল্টার করা বট ট্রাফিকের জন্য ঐচ্ছিক `x-ghost-bot-detected: true` হেডার। ## কনফিগারেশন `.env.example` ফাইলটি `.env`-এ কপি করুন এবং মানগুলো পরিবর্তন করুন। গুরুত্বপূর্ণ ভেরিয়েবলগুলোর মধ্যে রয়েছে: - `WORKER_MODE` – `worker` অথবা `ingest`। - `PUBSUB_TOPIC_PAGE_HITS_RAW` – ব্যাচ মোড নির্ধারণ করে। - `ENABLE_BOT_DETECTION_HEADER` – বট-ডিটেকশন রেসপন্স হেডার চালু বা বন্ধ করে। ## ডেভেলপমেন্ট ওয়ার্কফ্লো ১. **প্রয়োজনীয়তা** – Docker (Desktop অথবা Orbstack) এবং Docker Compose। ২. রিপোজিটরি ক্লোন করুন এবং সব সার্ভিস শুরু করতে `pnpm dev` চালান; অ্যানালিটিক্স API `http://localhost:3000`-এ উপলব্ধ হবে। ৩. Ghost চেকআউটের সাথে লোকাল ইন্টিগ্রেশনের জন্য, এই রিপোতে `pnpm dev:ghost` এবং Ghost রিপোতে `pnpm dev:analytics:local` চালান। এটি একটি শেয়ারড Docker নেটওয়ার্কের মাধ্যমে দুটি কন্টেইনারকে সংযুক্ত করে। ### মাল্টি-ওয়ার্কট্রি সাপোর্ট প্রজেক্টটি একসাথে একাধিক Git ওয়ার্কট্রি চালাতে পারে। প্রতিটি ওয়ার্কট্রি অনন্য পোর্ট, Docker compose প্রজেক্ট নাম এবং আইসোলেটেড ভলিউম সেট করতে নিজস্ব `.env` ফাইল ব্যবহার করে, যা পোর্ট কনফ্লিক্ট ছাড়াই প্যারালাল ডেভেলপমেন্টের সুযোগ দেয়। ## টেস্টিং এবং লিন্টিং - `pnpm test:types` – TypeScript টাইপ চেক। - `pnpm test:unit` – ইউনিট টেস্ট। - `pnpm test:integration` – ইন্টিগ্রেশন টেস্ট। - `pnpm test:e2e` – WireMock সহ এন্ড-টু-এন্ড টেস্ট। - `pnpm lint` – ESLint লিন্টিং। এনভায়রনমেন্টের সামঞ্জস্যতার জন্য সমস্ত টেস্ট কমান্ড Docker কন্টেইনারের ভেতরে চলে। ## ডেপ্লয়মেন্ট পাইপলাইন - **ব্রাঞ্চ ওয়ার্কফ্লো** – একটি PR ওপেন করুন, স্টেজিং ডেপ্লয়মেন্ট ট্রিগার করতে ঐচ্ছিকভাবে `deploy-staging` লেবেল যুক্ত করুন। - **মার্জ অ্যাকশন** – স্বয়ংক্রিয় প্যাচ ভার্সন বাম্প, Git ট্যাগ তৈরি, Docker Hub ইমেজ পাবলিশ, স্টেজিং এবং প্রোডাকশনে Cloud Run ডেপ্লয়মেন্ট, হেলথ চেক এবং Slack নোটিফিকেশন। - **ম্যানুয়াল ট্রিগার** – `workflow_dispatch`-এর মাধ্যমে "Deploy" ওয়ার্কফ্লো চালাতে GitHub Actions UI ব্যবহার করুন। সম্পূর্ণ CI/CD বিবরণ `docs/deployment.md`-এ রয়েছে। ## ডকুমেন্টেশন - `docs/architecture.md` – ব্যাচ বনাম প্রক্সি মোড, Pub/Sub পাইপলাইন, OpenTelemetry এবং ওয়ার্কার ডিজাইনের বিস্তারিত ডায়াগ্রাম। - `docs/deployment.md` – CI/CD পাইপলাইন, স্টেজিং/প্রোডাকশন ফ্লো এবং রোলব্যাক পদ্ধতি। ## লাইসেন্স MIT © Ghost Foundation (2013‑2026).