معماری (Architecture)#

برنامه bgscan ساختاری لایه‌بندی‌شده دارد. یک نقطه ورود (Entry Point) سبک، بررسی‌های سلامت اولیه (Health Checks) را هنگام راه‌اندازی سیستم اجرا می‌کند و سپس کنترل برنامه را به رابط کاربری متنی BubbleTea TUI می‌سپارد. این رابط کاربری متنی، یک موتور اسکنر چندمرحله‌ای را هدایت می‌کند که پروب‌ها (Probes) و سیستم ورودی/خروجی (I/O) آن به صورت ماژولار و قابل تعویض (Pluggable) طراحی شده‌اند.

ساختار دایرکتوری‌ها (Directory Layout)#

.
├── assets
│   └── xray
│       └── outbounds
├── cmd
│   └── bgscan
│       └── main.go
├── docs
├── go.mod
├── internal
│   ├── core
│   │   ├── config
│   │   ├── dns
│   │   ├── fileutil
│   │   ├── ip
│   │   ├── iplist
│   │   ├── process
│   │   ├── result
│   │   ├── scanner
│   │   └── xray
│   ├── logger
│   ├── startup
│   └── ui
│       ├── components
│       ├── main
│       ├── shared
│       └── theme
├── ips
├── scripts
└── settings

نمای کلی لایه‌ها (Layer Overview)#

┌─────────────────────────────────────────────┐
│                  cmd/bgscan                 │
│                (نقطه ورود برنامه)             │
├─────────────────────────────────────────────┤
│               internal/startup              │
│        (بررسی سلامت، مقداردهی تنظیمات)         │
├─────────────────────────────────────────────┤
│                 internal/ui                 │
│  ┌─────────────────────────────────────┐    │
│  │  main (مدل ریشه، چیدمان، دیالوگ‌ها)     │    │
│  │  components (منوها، جدول‌ها، فرم‌ها)   │    │
│  │  shared (زیرساخت چیدمان، محیط، دیالوگ)│    │
│  │  theme (تم‌ها)                      │    │
│  └─────────────────────────────────────┘    │
├─────────────────────────────────────────────┤
│                internal/core                │
│  ┌──────────────┐ ┌──────────┐ ┌─────────┐  │
│  │   scanner    │ │  config  │ │  result │  │
│  │ (موتور، پروب) │ │  (TOML)  │ │(نویسنده)│  │
│  └──────────────┘ └──────────┘ └─────────┘  │
│  ┌──────────┐ ┌─────────┐ ┌──────────────┐  │
│  │  iplist  │ │   dns   │ │ xray/process │  │
│  └──────────┘ └─────────┘ └──────────────┘  │
├─────────────────────────────────────────────┤
│               internal/logger               │
├─────────────────────────────────────────────┤
│            assets/  ips/  settings/         │
│               (فایل‌های داده)               │
└─────────────────────────────────────────────┘

راهنمای دایرکتوری‌ها (Directory Reference)#

مسیر	توضیحات
`cmd/bgscan`	نقطه ورود اصلی برنامه (`main.go`). مدل ریشه TUI را ایجاد و آن را اجرا می‌کند.
`internal/core`	منطق و هسته اصلی: تنظیمات، دی‌ان‌اس، ابزارهای کمکی فایل، مدیریت آی‌پي‌ها، مدیریت پروسس‌ها، نتایج، اسکنر و یکپارچه‌سازی Xray.
`internal/core/config`	پکیج سینگلتون (Singleton) تنظیمات مبتنی بر TOML با قابلیت دسترسی ایمن در محیط‌های چندنخی (Thread-safe).
`internal/core/scanner`	هماهنگ‌کننده اسکنر، موتور (خط‌لوله)، اینترفیس پروب‌ها، مدیریت پورت‌ها و ابزارهای کمکی شبکه.
`internal/core/result`	نویسنده ناهمگام نتایج (Asynchronous Writer)، ادغام/مرتب‌سازی فایل‌های CSV، رجیستری و بارگذاری‌کننده فایل نتایج.
`internal/core/iplist`	بارگذاری‌کننده فایل‌های CSV لیست آی‌پي، پارسر، رجیستری و برهم‌زننده تصادفی (Shuffle) لیست‌ها.
`internal/core/dns`	ابزارهای کمکی برای کوئری‌های DNS، ابزارهای DNSTT، SlipStream و SOCKS5.
`internal/core/xray`	اجراکننده دستورات Xray، مدیریت اینباندها/آوتباندها (Inbound/Outbound) و تست سرعت.
`internal/core/process`	مدیریت چرخه حیات پروسس‌ها به صورت چندسکویی (ایجاد، خاتمه و ارسال سیگنال).
`internal/core/fileutil`	ابزارهای کمکی برای کار با فایل‌های CSV، JSON، TOML، متن، فایل‌های موقت و مدیریت مسیرها.
`internal/core/ip`	پارس کردن آدرس‌های آی‌پي و باز کردن رنج‌های CIDR.
`internal/logger`	ثبت لاگ‌های سطح‌بندی‌شده با قابلیت جابه‌جایی و چرخش خودکار فایل‌ها (Lumberjack Rotation). شامل سه جریان: هسته، رابط کاربری و دباگ.
`internal/startup`	بررسی‌های ترتیبی سلامت سیستم در زمان راه‌اندازی: لاگر، تم، تنظیمات، باینری Xray، باینری DNSTT و Slipstream.
`internal/ui/main`	مدل ریشه BubbleTea — مدیریت چیدمان هدر/بدنه/فوتر و مدیریت دیالوگ‌های لایه‌رویی (Overlay Dialogs).
`internal/ui/components`	اجزای قابل استفاده مجدد رابط کاربری: ویجت‌های پایه، فرم‌های بازرس، منوها، جدول‌ها و نمای اسکنر.
`internal/ui/shared`	زیرساخت مشترک UI: هندسه و ابعاد چیدمان، سیستم دیالوگ، کلیدها/محیط، اینترفیس کامپوننت‌ها و اعتبارسنجی ورودی‌ها.
`internal/ui/theme`	پالت‌های رنگی تاریک، روشن و خودکار (بر پایه استایل Catppuccin).
`assets/xray/outbounds`	فایل‌های پیکربندی آوتباند Xray که به همراه برنامه توزیع می‌شوند.
`assets/dnstt-client`, `assets/slipstream-client`	باینری‌های مربوط به تونل‌زنی دی‌ان‌اس.
`ips`	لیست پیش‌فرض رنج‌های آی‌پي به تفکیک ارائه‌دهندگان (Cloudflare، AWS، Azure و غیره) در قالب فایل‌های CSV.
`settings`	فایل‌های تنظیمات پیش‌فرض با فرمت `.toml`. فایل‌های با پسوند `.default` به عنوان قالب‌های زاپاس و پشتیبان عمل می‌کنند.
`scripts`	اسکریپت‌های کمکی برای نصب، کامپایل و ریلیز پروژه.
`docs`	وب‌سایت مستندات پروژه که با Hugo Book ساخته شده است.

گردش کار برنامه (Application Flow)#

()main
 │
 ├─ ()startup.RunHealthChecks
 │     ├─ مقداردهی اولیه لاگر (logger init)
 │     ├─ مقداردهی اولیه تم (theme init)
 │     ├─ بارگذاری و اعتبارسنجی تنظیمات (config load + validate)
 │     ├─ بررسی وجود باینری xray
 │     ├─ بررسی وجود باینری dnstt
 │     └─ بررسی وجود باینری slipstream
 │
 ├─ ()tea.NewProgram(app.New()).Run
 │     │
 │     ├─ هدر (نوار عنوان بالای صفحه)
 │     ├─ بدنه (پشته کامپوننت‌ها: منوی اصلی ← اسکن/تنظیمات/لاگ‌ها/...)
 │     └─ فوتر (نوار وضعیت پایین صفحه، کلیدهای راهنما)
 │
 └─ هنگامی که کاربر گزینه شروع اسکن را انتخاب می‌کند:
       ├─ ()scanner.NewScanner(ctx, inputPath)
       ├─ (scanner.AddStage(BuildICMPStage
       ├─ (scanner.AddStage(BuildTCPStage
       ├─ ...
       ├─ ()scanner.Run
       │     ├─ اسکن تک‌مرحله‌ای ← engine.RunScan
       │     └─ اسکن چندمرحله‌ای ← engine.RunScanWithChain
       │           ├─ به صورت ترتیبی (sequential)
       │           ├─ به صورت جریانی (streaming)
       │           └─ به صورت دسته‌ای (batch)
       │
       └─ نتایج از طریق ثبت‌کننده نتایج روی دیسک ذخیره می‌شوند: result.Writer ← ادغام فایل‌های CSV ← ذخیره نهایی

اصول کلیدی طراحی (Key Design Principles)#

عدم وابستگی به ابزارهای خارجی برای اسکن‌های پایه: پروب‌های ICMP، TCP و HTTP کاملاً از کتابخانه‌های استاندارد خود زبان Go (go stdlib) استفاده می‌کنند. ابزارهای Xray، DNSTT و Slipstream باینری‌های اختیاری هستند که وجود و سلامت آن‌ها در زمان راه‌اندازی (Startup) اعتبارسنجی می‌شود.
تنظیمات فایل‌محور: تمام تنظیمات و پیکربندی‌ها در مسیر settings/*.toml زندگی می‌کنند. بخش بازرس (Inspector) درون برنامه نیز دقیقاً همین فایل‌ها را خوانده و بازنویسی می‌کند.
پروب‌های ماژولار و قابل تعویض: تنها قرارداد موجود برای افزودن اسکنر جدید، اینترفیس probe.Probe است. برای افزودن یک نوع اسکن جدید، کافی است متدهای Init/Run/Close را پیاده‌سازی کرده و سازنده مرحله (Stage Builder) آن را ثبت کنید.
موتور مستقل از نوع خط‌لوله (Pipeline-agnostic): موتور اصلی اسکنر اطلاعی از ماهیت و کارکرد پروب‌ها ندارد — وظیفه آن صرفاً تزریق آی‌پي‌ها، جمع‌آوری نتایج و تخلیه آن‌ها روی دیسک است. حالت خط‌لوله (ترتیبی/جریانی/دسته‌ای) بر اساس ترجیحات فایل تنظیمات تعیین می‌شود.
رابط کاربری درختی از کامپوننت‌ها: هر صفحه در برنامه یک ui.Component مجزا است که از متدهای Init/Update/View/OnClose/Mode پیروی می‌کند. لایه‌های رویی (دیالوگ‌ها، انتخاب‌گرها) روی لایه‌های قبلی پشته می‌شوند و بالاترین لایه، تمامی ورودی‌های کاربر را به خود اختصاص می‌دهد.

صفحات مرتبط#

هسته اصلی (Core) — جزئیات موتور اسکنر، اینترفیس پروب‌ها، سیستم پیکربندی و خط‌لوله نتایج
رابط کاربری (UI) — معماری TUI، مدل کامپوننت‌ها، چیدمان و سیستم تم‌ها
شروع به کار (Getting Started) — دستورالعمل‌های کامپایل و اجرای پروژه