# mohsenbg/bgscan architecture

> Architecture diagram of the GitHub repository mohsenbg/bgscan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mohsenbg/bgscan
- Repository: https://github.com/mohsenbg/bgscan

## Overview

bgscan is a keyboard-driven terminal application for chained, multi-protocol IP scanning. The documented workflow is to choose targets and scan stages in the TUI, run concurrent probes, and persist results for review or reuse as later scan input. The graph also preserves configuration, Xray outbound validation/speed testing, and logging capabilities. Probe-family wiring is summarized from the README; sampled source confirms IP streaming, worker execution, DNS query behavior, result persistence, and embedded Xray operation, but not every stage-builder connection.

Main entry points: [`internal/ui/main/app`](https://github.com/mohsenbg/bgscan/tree/main/internal/ui/main/app) (TUI application), [`internal/core/scanner/probe`](https://github.com/mohsenbg/bgscan/tree/main/internal/core/scanner/probe) (Protocol probes), [`cmd/bgscan/main.go`](https://github.com/mohsenbg/bgscan/blob/main/cmd/bgscan/main.go) (Program entry), [`internal/ui/components/scanner`](https://github.com/mohsenbg/bgscan/tree/main/internal/ui/components/scanner) (Scan dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Terminal interface"]
  node_entry["Program entry<br/>[main.go]"]
  node_app["TUI application"]
  node_scanui["Scan dashboard"]
  node_settings["Settings inspector"]
  node_outboundui["Outbound manager"]
  node_inputui["Target selection"]
  node_resultui["Result browser"]
end

subgraph group_scan["Scan pipeline"]
  node_engine["Pipeline engine"]
  node_builder["Stage builder<br/>[stagebuilder.go]"]
  node_probes["Protocol probes"]
  node_dnsquery["DNS resolver<br/>[query.go]"]
end

subgraph group_data["Inputs and results"]
  node_iplist["IP list streamer"]
  node_results[("Result writer<br/>[manager.go]")]
end

subgraph group_services["Supporting services"]
  node_config["Configuration"]
  node_xray["Embedded Xray<br/>[service.go]"]
  node_speedtest["Outbound speed test<br/>[service.go]"]
  node_logs["Logging"]
end

node_user(("Operator"))
node_network(("Target networks"))
node_slipstream["Slipstream binary"]

node_user -->|"launches"| node_entry
node_entry -->|"starts"| node_app
node_app -->|"presents"| node_scanui
node_app -->|"presents"| node_settings
node_app -->|"presents"| node_outboundui
node_app -->|"presents"| node_resultui
node_settings -->|"edits"| node_config
node_scanui -->|"selects targets"| node_inputui
node_inputui -->|"streams targets"| node_iplist
node_iplist -->|"feeds IPs"| node_engine
node_scanui -->|"starts scan"| node_engine
node_engine -->|"builds stages"| node_builder
node_builder -->|"selects probes"| node_probes
node_probes -->|"probes"| node_network
node_probes -->|"queries DNS"| node_dnsquery
node_probes -->|"writes results"| node_results
node_resultui -->|"reads results"| node_results
node_outboundui -->|"manages outbounds"| node_xray
node_xray -->|"supports testing"| node_speedtest
node_entry -->|"initializes"| node_logs
node_probes -.->|"uses when enabled"| node_slipstream

click node_entry "https://github.com/mohsenbg/bgscan/blob/main/cmd/bgscan/main.go"
click node_app "https://github.com/mohsenbg/bgscan/tree/main/internal/ui/main/app"
click node_scanui "https://github.com/mohsenbg/bgscan/tree/main/internal/ui/components/scanner"
click node_settings "https://github.com/mohsenbg/bgscan/tree/main/internal/ui/components/inspector"
click node_outboundui "https://github.com/mohsenbg/bgscan/tree/main/internal/ui/components/tables/outbounds"
click node_config "https://github.com/mohsenbg/bgscan/tree/main/internal/core/config"
click node_inputui "https://github.com/mohsenbg/bgscan/tree/main/internal/ui/components/menus/targetsource"
click node_iplist "https://github.com/mohsenbg/bgscan/tree/main/internal/core/iplist"
click node_engine "https://github.com/mohsenbg/bgscan/tree/main/internal/core/scanner/engine"
click node_builder "https://github.com/mohsenbg/bgscan/blob/main/internal/core/scanner/stagebuilder.go"
click node_probes "https://github.com/mohsenbg/bgscan/tree/main/internal/core/scanner/probe"
click node_dnsquery "https://github.com/mohsenbg/bgscan/blob/main/internal/core/dns/query.go"
click node_results "https://github.com/mohsenbg/bgscan/blob/main/internal/core/result/manager.go"
click node_resultui "https://github.com/mohsenbg/bgscan/tree/main/internal/ui/components/tables/resultlist"
click node_xray "https://github.com/mohsenbg/bgscan/blob/main/internal/core/xray/service.go"
click node_speedtest "https://github.com/mohsenbg/bgscan/blob/main/internal/core/speedtest/service.go"
click node_logs "https://github.com/mohsenbg/bgscan/tree/main/internal/logger"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_app,node_scanui,node_settings,node_outboundui,node_inputui,node_resultui toneBlue
class node_engine,node_builder,node_probes,node_dnsquery toneAmber
class node_iplist,node_results toneMint
class node_config,node_xray,node_speedtest,node_logs toneRose
class node_user,node_network,node_slipstream toneIndigo
```

## Components

### Terminal interface

- [Program entry](https://github.com/mohsenbg/bgscan/blob/main/cmd/bgscan/main.go): `cmd/bgscan/main.go`
- [TUI application](https://github.com/mohsenbg/bgscan/tree/main/internal/ui/main/app): `internal/ui/main/app`
- [Scan dashboard](https://github.com/mohsenbg/bgscan/tree/main/internal/ui/components/scanner): `internal/ui/components/scanner`
- [Settings inspector](https://github.com/mohsenbg/bgscan/tree/main/internal/ui/components/inspector): `internal/ui/components/inspector`
- [Outbound manager](https://github.com/mohsenbg/bgscan/tree/main/internal/ui/components/tables/outbounds): `internal/ui/components/tables/outbounds`
- [Target selection](https://github.com/mohsenbg/bgscan/tree/main/internal/ui/components/menus/targetsource): `internal/ui/components/menus/targetsource`
- [Result browser](https://github.com/mohsenbg/bgscan/tree/main/internal/ui/components/tables/resultlist): `internal/ui/components/tables/resultlist`

### Scan pipeline

- [Pipeline engine](https://github.com/mohsenbg/bgscan/tree/main/internal/core/scanner/engine): `internal/core/scanner/engine`
- [Stage builder](https://github.com/mohsenbg/bgscan/blob/main/internal/core/scanner/stagebuilder.go): `internal/core/scanner/stagebuilder.go`
- [Protocol probes](https://github.com/mohsenbg/bgscan/tree/main/internal/core/scanner/probe): `internal/core/scanner/probe`
- [DNS resolver](https://github.com/mohsenbg/bgscan/blob/main/internal/core/dns/query.go): `internal/core/dns/query.go`

### Inputs and results

- [IP list streamer](https://github.com/mohsenbg/bgscan/tree/main/internal/core/iplist): `internal/core/iplist`
- [Result writer](https://github.com/mohsenbg/bgscan/blob/main/internal/core/result/manager.go): `internal/core/result/manager.go`

### Supporting services

- [Configuration](https://github.com/mohsenbg/bgscan/tree/main/internal/core/config): `internal/core/config`
- [Embedded Xray](https://github.com/mohsenbg/bgscan/blob/main/internal/core/xray/service.go): `internal/core/xray/service.go`
- [Outbound speed test](https://github.com/mohsenbg/bgscan/blob/main/internal/core/speedtest/service.go): `internal/core/speedtest/service.go`
- [Logging](https://github.com/mohsenbg/bgscan/tree/main/internal/logger): `internal/logger`

### Other components

- **Operator**
- **Target networks**
- **Slipstream binary**

## Connections

- Operator → Program entry: launches
- Program entry → TUI application: starts
- TUI application → Scan dashboard: presents
- TUI application → Settings inspector: presents
- TUI application → Outbound manager: presents
- TUI application → Result browser: presents
- Settings inspector → Configuration: edits
- Scan dashboard → Target selection: selects targets
- Target selection → IP list streamer: streams targets
- IP list streamer → Pipeline engine: feeds IPs
- Scan dashboard → Pipeline engine: starts scan
- Pipeline engine → Stage builder: builds stages
- Stage builder → Protocol probes: selects probes
- Protocol probes → Target networks: probes
- Protocol probes → DNS resolver: queries DNS
- Protocol probes → Result writer: writes results
- Result browser → Result writer: reads results
- Outbound manager → Embedded Xray: manages outbounds
- Embedded Xray → Outbound speed test: supports testing
- Program entry → Logging: initializes
- Protocol probes → Slipstream binary: uses when enabled