Developer on Documentation

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Getting Started (Developer)#

This guide explains how to set up your environment, build, and run bgscan locally for development.

Read first: Contributing — branching, commit conventions, and PR workflow.

Prerequisites#

Go 1.26.3+ (see go.mod for the exact version)
Git
For Android builds: Android NDK

1. Clone the repository#

git clone https://github.com/MohsenBg/bgscan.git
cd bgscan

2. Create a branch#

git checkout -b feature/my-change

See Contributing for branch naming conventions.

3. Install dependencies#

bgscan uses a companion tool called bgscan-builder to fetch and build the project’s dependencies. The install scripts download it for you, place it in the project root, and use it to fetch the correct dependency build for your OS/architecture.

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Architecture#

bgscan is a layered application. A lightweight entry point boots startup health checks, then hands control to a BubbleTea TUI. The TUI drives a multi-stage scanner engine whose probes and I/O are 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 │
│ (entry point) │
├─────────────────────────────────────────────┤
│ internal/startup │
│ (health checks, config init) │
├─────────────────────────────────────────────┤
│ internal/ui │
│ ┌─────────────────────────────────────┐ │
│ │ main (root model, layout, dialogs) │ │
│ │ components (menus, tables, forms) │ │
│ │ shared (layout, env, dialog, ui) │ │
│ │ theme │ │
│ └─────────────────────────────────────┘ │
├─────────────────────────────────────────────┤
│ internal/core │
│ ┌──────────────┐ ┌──────────┐ ┌─────────┐ │
│ │ scanner │ │ config │ │ result │ │
│ │ (engine, │ │ (TOML) │ │ (writer)│ │
│ │ probe, port) │ │ │ │ │ │
│ └──────────────┘ └──────────┘ └─────────┘ │
│ ┌──────────┐ ┌─────────┐ ┌──────────────┐ │
│ │ iplist │ │ dns │ │ xray/process │ │
│ └──────────┘ └─────────┘ └──────────────┘ │
├─────────────────────────────────────────────┤
│ internal/logger │
├─────────────────────────────────────────────┤
│ assets/ ips/ settings/ │
│ (data files) │
└─────────────────────────────────────────────┘

Directory reference#

Path	Description
`cmd/bgscan`	Application entry point (`main.go`). Creates the root TUI model and runs it.
`internal/core`	Core logic: config, DNS, file utilities, IP handling, process management, results, scanner, and Xray integration.
`internal/core/config`	TOML-based configuration singleton with thread-safe accessors.
`internal/core/scanner`	Scanner orchestrator, engine (pipeline), probe interface, port manager, and net utilities.
`internal/core/result`	Asynchronous result writer, CSV merge/sort, result file registry, and loader.
`internal/core/iplist`	IP list CSV loader, parser, registry, and shuffle.
`internal/core/dns`	DNS query, DNSTT, SlipStream, and SOCKS5 helpers.
`internal/core/xray`	Xray command runner, inbound/outbound management, and speed test.
`internal/core/process`	Cross-platform process lifecycle (spawn, kill, signal).
`internal/core/fileutil`	CSV, JSON, TOML, text, temp-file, and path helpers.
`internal/core/ip`	IP parsing and CIDR expansion.
`internal/logger`	Leveled logging with lumberjack rotation. Three streams: core, ui, debug.
`internal/startup`	Sequential startup health checks: logger, theme, config, Xray, DNSTT, Slipstream.
`internal/ui/main`	Root BubbleTea model — header/body/footer layout, overlay dialog manager.
`internal/ui/components`	Reusable UI: basic widgets, inspector forms, menus, tables, scanner view.
`internal/ui/shared`	Shared UI infrastructure: layout geometry, dialog system, env/keys, component interface, validation.
`internal/ui/theme`	Dark/light/auto color palettes (Catppuccin-based).
`assets/xray/outbounds`	Bundled Xray outbound config assets.
`assets/dnstt-client`, `assets/slipstream-client`	DNS tunneling binaries.
`ips`	Default IP range lists per provider (Cloudflare, AWS, Azure, etc.) as CSV.
`settings`	Default `.toml` settings files. `.default` copies are fallback templates.
`scripts`	Install, build, and release helper scripts.
`docs`	Hugo Book documentation site.

Application flow#

main()
 │
 ├─ startup.RunHealthChecks()
 │ ├─ logger init
 │ ├─ theme init
 │ ├─ config load + validate
 │ ├─ xray binary check
 │ ├─ dnstt binary check
 │ └─ slipstream binary check
 │
 ├─ tea.NewProgram(app.New()).Run()
 │ │
 │ ├─ header (title bar)
 │ ├─ body (component stack: main menu → scan/settings/logs/...)
 │ └─ footer (status bar, key hints)
 │
 └─ when user selects Run Scan:
 ├─ scanner.NewScanner(ctx, inputPath)
 ├─ scanner.AddStage(BuildICMPStage)
 ├─ scanner.AddStage(BuildTCPStage)
 ├─ ...
 ├─ scanner.Run()
 │ ├─ single stage → engine.RunScan
 │ └─ multi stage → engine.RunScanWithChain
 │ ├─ sequential
 │ ├─ streaming
 │ └─ batch
 │
 └─ results written via result.Writer → CSV merge → disk

Key design principles#

No external runtime deps for core scans. ICMP, TCP, and HTTP probes use Go stdlib. Xray, DNSTT, and Slipstream are optional binaries validated at startup.
Configuration is file-first. All settings live in settings/*.toml. The in-app inspector reads and writes the same files.
Probes are pluggable. The probe.Probe interface is the only contract. Adding a new scan type means implementing Init/Run/Close and registering a stage builder.
Engine is pipeline-agnostic. The engine does not know what the probes do — it just feeds IPs, collects results, and flushes to disk. The pipeline mode (sequential/streaming/batch) is a config choice.
UI is a component tree. Every screen is a ui.Component with Init/Update/View/OnClose/Mode. Overlays (dialogs, pickers) stack on top; the top overlay consumes all input.

Core — scanner engine, probe interface, config, and result pipeline in detail
UI — TUI architecture, component model, layout, and theming
Getting Started — build and run instructions

Core

Mon, 01 Jan 0001 00:00:00 +0000

Core#

The internal/core package contains all non-UI logic: configuration, the scanner engine, probe implementations, IP list handling, results, DNS, Xray integration, and process management.

Package map#

Package	Responsibility
`config`	Thread-safe singleton holding all TOML settings; load/save helpers; validation entry points.
`config/validate`	Per-protocol validators (ICMP, TCP, HTTP, DNS, Xray, writer, general).
`scanner`	`Scanner` orchestrator and stage builders.
`scanner/engine`	Pipeline execution: single scan, sequential chain, streaming pipeline, batch pipeline.
`scanner/probe`	`Probe` interface and all concrete probes (ICMP, TCP, HTTP, HTTP/3, DNS, DNSTT, SlipStream, Resolve, Xray).
`scanner/portmgr`	Ephemeral port pool for probes that need local bind ports (Xray, DNSTT, SlipStream).
`scanner/netutil`	Shared network utilities.
`result`	`Writer` (async batch+merge), CSV format, loader, registry, ordering.
`iplist`	CSV IP list loader, parser, registry, shuffle, streaming.
`ip`	IPv4 parsing and CIDR expansion.
`dns`	DNS query helpers, transport parsing, DNSTT/SlipStream SOCKS5 client.
`xray`	Xray binary runner, inbound/outbound config, link parsing, speed test.
`process`	Cross-platform process spawn/kill (Unix + Windows split).
`fileutil`	CSV, JSON, TOML, text, temp-file, and path helpers.
`logger`	Leveled logging (core, ui, debug) with lumberjack rotation.

Scanner#

internal/core/scanner/scanner.go defines the Scanner struct — the public API the UI calls to run a scan.

UI

Mon, 01 Jan 0001 00:00:00 +0000

UI#

bgscan’s terminal UI is built on BubbleTea (the Elvish v2 fork at charm.land/bubbletea/v2) and Lipgloss for styling. The architecture is a component tree with an overlay dialog system and a centralized layout manager.

Package map#

Package	Responsibility
`ui/main/app`	Root BubbleTea model. Manages layout, header/body/footer, and overlay dialog stack.
`ui/main/header`	Top bar — app title and branding.
`ui/main/body`	Central content area — holds a component stack (main menu → sub-screens).
`ui/main/footer`	Status bar — app version, current screen name, goroutine count, memory usage.
`ui/components/basic`	Reusable widgets: confirm, crud, input, inspector, logview, menu, notice, picker, progress, table, tabs.
`ui/components/inspector`	Per-protocol settings forms (DNS, general, HTTP, ICMP, TCP, Xray).
`ui/components/menus`	Screen-level menus: entry (main), logs, outbound, scantype, settings, targetsource.
`ui/components/tables`	Data tables: iplist, ipviewer, outbounds, resultlist.
`ui/components/scanner`	Live scan view — tabbed progress bars + result tables per stage.
`ui/shared`	Shared infrastructure: layout, dialog, env (keys/modes), component interface, validation.
`ui/theme`	Dark/light/auto color palettes + huh form theme adapter.

Component interface#

Every screen, widget, and dialog implements ui.shared.ui.Component:

Contributing

Mon, 01 Jan 0001 00:00:00 +0000

Contributing Guide#

Thank you for your interest in contributing to bgscan! Every contribution is appreciated, whether it’s fixing bugs, improving documentation, or implementing new features.

Before You Start#

Search existing Issues before opening a new one.
If you’re planning a large feature or major change, please open an Issue first to discuss it.
Keep pull requests focused on a single change.

Branch Strategy#

Please do not commit directly to the main branch.

Developer on Documentation

Getting Started

Getting Started (Developer)#

Prerequisites#

1. Clone the repository#

2. Create a branch#

3. Install dependencies#

Architecture

Architecture#

Directory layout#

Layer overview#

Directory reference#

Application flow#

Key design principles#

Related pages#

Core

Core#

Package map#

Scanner#

UI

UI#

Package map#

Component interface#

Contributing

Contributing Guide#

Before You Start#

Branch Strategy#