منصوبے کے بارے میں

## جائزہ ٹریفک اینالٹیکس ایک ویب اینالٹیکس پراکسی ہے جو گوسٹ سائٹس کے لیے تیار کیا گیا ہے۔ یہ گوسٹ کے 'ghost-stats.js' اسکرپٹ کے ذریعے کیے گئے 'POST /api/v1/page_hit' کالوں کو روکتا ہے، پیلڈ کو غنی فرما دیتا ہے (صارف-ایجنٹ پارس کرنا، ریفرر تجزیہ، صارف سائنیچر جنریشن) اور اس ڈیٹا کو ٹائینی بارڈ کے '/v0/events' API کو فارورڈ کرتا ہے، جہاں یہ کلک ہاؤس ڈیٹا بیس میں محفوظ ہوتا ہے۔ ## آرکیٹیکچر اور رن موڈز - **بیچ موڈ (ڈیفالٹ)** – انگیسٹ سروس درخواستوں کی تصدیق کرتا ہے، باتس کو فلٹر کرتا ہے، اور خام واقعات کو گوگل کلاؤڈ پبلِش/سب سکرپشن ٹاپک پر شائع کرتا ہے۔ ایک الگ ورکر سبسکریپشن کو کھولتا ہے، ہر واقعہ کو غنی فرما دیتا ہے، انہیں بیچ میں جمع کرتا ہے، اور ٹائینی بارڈ کو فارورڈ کرتا ہے۔ یہ درخواست کے نظم کو انگیسٹ سے الگ کرتا ہے اور تھروٹ پروسیس کو بہتر بناتا ہے۔ - **پراکسی موڈ (سنکرون)** – جب کوئی پبلِش/سب سکرپشن ٹاپک مقرر نہ ہو، تو انگیسٹ سروس غنی فرما دیتا ہے اور درخواست کو ایک ہی HTTP سائیکل میں ٹائینی بارڈ کو پراکسی کرتا ہے۔ موڈ 'WORKER_MODE' ماحولی متغیر اور 'PUBSUB_TOPIC_PAGE_HITS_RAW' کی موجودگی کے ذریعے منتخب کیا جاتا ہے۔ ## کلیدی خصوصیات - صارف-ایجنٹ پارس کرنا، او ایس، براؤزر اور آلہ کی پہچان کے لیے۔ - ریفرر یو آر ایل پارس کرنا اور کیٹیگرائزیشن۔ - خصوصیات کی حفاظت کے ساتھ روزانہ گردش والے سالٹس کے ساتھ صارف سائنیچرز۔ - اختیاری 'x-ghost-bot-detected: true' ہیڈر، فلٹرڈ باتس ٹریفک کے لیے۔ ## کنفیگریشن '.env.example' کو '.env' میں کاپی کریں اور اقدار کو سیٹ کریں۔ اہم متغیرات شامل ہیں: - 'WORKER_MODE' – 'worker' یا 'ingest' - 'PUBSUB_TOPIC_PAGE_HITS_RAW' – بیچ موڈ کی وضاحت کرتا ہے۔ - 'ENABLE_BOT_DETECTION_HEADER' – باتس کی پہچان کے ریسپونس ہیڈر کو ٹوگل کرتا ہے۔ ## ڈویلپمنٹ ورک فلو 1. **پری ریکوائرمنٹ** – ڈوکر (ڈیسک یا اورب اسٹیک) اور ڈوکر کمپوز۔ 2. ریپوزٹری کلون کریں اور 'pnpm dev' چلانے سے تمام سروسز شروع ہو جائیں گے؛ اینالٹیکس API 'http://localhost:3000' پر دستیاب ہوگا۔ 3. مقامی انسٹیگریشن کے لیے گوسٹ چیک آؤٹ کے ساتھ 'pnpm dev:ghost' اور گوسٹ ریپوزٹری میں 'pnpm dev:analytics:local' چلانا۔ یہ دونوں کنٹینرز کو مشترکہ ڈوکر نیٹ ورک کے ذریعے جوڑ دیتا ہے۔ ### ملٹی ورک ٹری ویلیو سپورٹ پروجیکٹ متعدد گٹ ورک ٹریوں کو ایک ساتھ چلانے کے قابل ہے۔ ہر ورک ٹری اپنی خاص '.env' فائل استعمال کرتا ہے تاکہ منفرد پورٹس، ڈوکر کمپوز پروجیکٹ نام اور عزل شدہ ولیومز سیٹ کیے جا سکیں، جس سے موازنہ ڈویلپمنٹ کے دوران پورٹ کنفلکٹس کو روکا جا سکے۔ ## ٹیسٹنگ اور لِنٹنگ - 'pnpm test:types' – ٹائپ سکرپٹ ٹائپ چیکس۔ - 'pnpm test:unit' – یونٹ ٹیسٹس۔ - 'pnpm test:integration' – انسٹیگریشن ٹیسٹس۔ - 'pnpm test:e2e' – وائر ماک کے ساتھ اینڈ-ٹو-اینڈ ٹیسٹس۔ - 'pnpm lint' – ESLint لِنٹنگ۔ تمام ٹیسٹ کمانڈس ڈوکر کنٹینرز میں چلاتے ہیں تاکہ ماحول کی مطابقت ہو۔ ## ڈیپلومینٹ پائپ لائن - **برینچ ورک فلو** – PR کھولیں، اختیاری طور پر 'deploy-staging' لیبل لگائیں تاکہ ایک اسٹیجنگ ڈیپلومینٹ ٹرگر کیا جائے۔ - **مرج ایکشنز** – خودکار پیچ ورژن بمپ، گٹ ٹیگ کریشن، ڈوکر ہب امیج پبلش، کلاؤڈ رن اسٹیجنگ اور پروڈکشن ڈیپلومینٹس، ہیلتھ چیکس، اور اسلاک نوٹیفیکیشنز۔ - **دستی ٹرگر** – گٹ ہب ایکشنز یو آئی کو استعمال کرکے 'Deploy' ورک فلو کو 'workflow_dispatch' کے ذریعے چلانا۔ مکمل سی آئی/سی ڈی تفصیلات 'docs/deployment.md' میں موجود ہیں۔ ## دستاویزات - 'docs/architecture.md' – بیچ اور پراکسی موڈز، پبلِش/سب پائپ لائن، اوپن ٹیلی میٹری، اور ورکر ڈیزائن کے تفصیلی ڈائیاگرام۔ - 'docs/deployment.md' – سی آئی/سی ڈی پائپ لائن، اسٹیجنگ/پروڈکشن فلو، اور رول بیک عملیات۔ ## لائسنس MIT © گوسٹ فاؤنڈیشن (2013-2026)