# saugat-sapkota-2/python-port-scanner. architecture

> Architecture diagram of the GitHub repository saugat-sapkota-2/python-port-scanner., generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saugat-sapkota-2/python-port-scanner.
- Repository: https://github.com/saugat-sapkota-2/python-port-scanner.

## Overview

This is a TCP port-scanning application with two user-facing workflows: a Flask web interface and a Textual terminal UI. Each accepts a target and port range, runs a scan, enriches open ports with banners and optional OS fingerprinting, then generates a JSON report. The web workflow also exposes scan status and report downloads. The main orchestrators are shown separately from the scanner modules they invoke; the TUI excerpt omits some worker code, so only visible or indexed relationships are included.

Main entry points: [`app.py`](https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/app.py) (Flask App), [`tui.py`](https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/tui.py) (Terminal UI), [`scanner/tcp_scanner.py`](https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/scanner/tcp_scanner.py) (TCP Scanner), [`scanner/banner_grabber.py`](https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/scanner/banner_grabber.py) (Banner Grabber)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_web_page["Web Page<br/>[index.html]"]
  node_tui["Terminal UI<br/>[tui.py]"]
end

subgraph group_workflow["Scan Workflows"]
  node_web_app["Flask App<br/>[app.py]"]
  node_scan_state["Scan State<br/>[app.py]"]
end

subgraph group_analysis["Scan Analysis"]
  node_tcp_scan["TCP Scanner<br/>[tcp_scanner.py]"]
  node_banner_grab["Banner Grabber<br/>[banner_grabber.py]"]
  node_os_fingerprint["OS Fingerprinting<br/>[os_fingerprint.py]"]
end

subgraph group_outputs["Reports"]
  node_report_generator["Report Generator<br/>[report.py]"]
  node_report_files["JSON Report Files"]
end

node_web_user(("Web User"))
node_terminal_user(("Terminal User"))
node_nmap["Nmap"]
node_target_system(("Target System"))

node_web_user -->|"starts scan"| node_web_app
node_web_app -->|"renders"| node_web_page
node_web_app -->|"updates state"| node_scan_state
node_web_app -->|"scans ports"| node_tcp_scan
node_web_app -->|"grabs banners"| node_banner_grab
node_web_app -->|"detects OS"| node_os_fingerprint
node_web_app -->|"generates report"| node_report_generator
node_web_app -->|"serves download"| node_report_files
node_terminal_user -->|"starts scan"| node_tui
node_tui -->|"scans ports"| node_tcp_scan
node_tui -->|"grabs banners"| node_banner_grab
node_tui -->|"detects OS"| node_os_fingerprint
node_tui -->|"generates report"| node_report_generator
node_os_fingerprint -.->|"runs detection"| node_nmap
node_tcp_scan -->|"checks ports"| node_target_system
node_banner_grab -->|"reads banners"| node_target_system
node_report_generator -->|"writes JSON"| node_report_files

click node_web_page "https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/templates/index.html"
click node_web_app "https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/app.py"
click node_scan_state "https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/app.py"
click node_tui "https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/tui.py"
click node_tcp_scan "https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/scanner/tcp_scanner.py"
click node_banner_grab "https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/scanner/banner_grabber.py"
click node_os_fingerprint "https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/scanner/os_fingerprint.py"
click node_report_generator "https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/scanner/report.py"

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_web_page,node_tui,node_web_user,node_terminal_user toneBlue
class node_web_app,node_scan_state toneAmber
class node_tcp_scan,node_banner_grab,node_os_fingerprint toneMint
class node_report_generator,node_report_files toneRose
class node_nmap,node_target_system toneIndigo
```

## Components

### User Interfaces

- [Web Page](https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/templates/index.html): `templates/index.html`
- [Terminal UI](https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/tui.py): `tui.py`

### Scan Workflows

- [Flask App](https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/app.py): `app.py`
- [Scan State](https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/app.py): `app.py`

### Scan Analysis

- [TCP Scanner](https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/scanner/tcp_scanner.py): `scanner/tcp_scanner.py`
- [Banner Grabber](https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/scanner/banner_grabber.py): `scanner/banner_grabber.py`
- [OS Fingerprinting](https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/scanner/os_fingerprint.py): `scanner/os_fingerprint.py`

### Reports

- [Report Generator](https://github.com/saugat-sapkota-2/python-port-scanner./blob/main/scanner/report.py): `scanner/report.py`
- **JSON Report Files**

### Other components

- **Web User**
- **Terminal User**
- **Nmap**
- **Target System**

## Connections

- Web User → Flask App: starts scan (evidence: `app.py`)
- Flask App → Web Page: renders (evidence: `app.py`)
- Flask App → Scan State: updates state (evidence: `app.py`)
- Flask App → TCP Scanner: scans ports (evidence: `app.py`)
- Flask App → Banner Grabber: grabs banners (evidence: `app.py`)
- Flask App → OS Fingerprinting: detects OS (evidence: `app.py`)
- Flask App → Report Generator: generates report (evidence: `app.py`)
- Flask App → JSON Report Files: serves download (evidence: `app.py`)
- Terminal User → Terminal UI: starts scan (evidence: `tui.py`)
- Terminal UI → TCP Scanner: scans ports (evidence: `tui.py`)
- Terminal UI → Banner Grabber: grabs banners (evidence: `tui.py`)
- Terminal UI → OS Fingerprinting: detects OS (evidence: `tui.py`)
- Terminal UI → Report Generator: generates report (evidence: `tui.py`)
- OS Fingerprinting → Nmap: runs detection (evidence: `scanner/os_fingerprint.py`)
- TCP Scanner → Target System: checks ports (evidence: `scanner/tcp_scanner.py`)
- Banner Grabber → Target System: reads banners (evidence: `scanner/banner_grabber.py`)
- Report Generator → JSON Report Files: writes JSON (evidence: `scanner/report.py`)
