# netwatchteam/netwatch architecture

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

- Interactive diagram: https://gitdiagram.com/netwatchteam/netwatch
- Repository: https://github.com/netwatchteam/netwatch

## Overview

Netwatch is a Flask-based network scanner and monitoring service. Its main workflow accepts scan targets over HTTP, discovers hosts and services, then enriches each machine with availability, TCP, TLS, and optional SSH system metrics before returning a snapshot. A separate endpoint checks configured TCP targets without running discovery. The graph reflects the documented composition root and sampled calls; unsampled API and presentation behavior is included only where the README or source index supports it.

Main entry points: [`scanner/src/main.py`](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/main.py) (Application wiring), [`scanner/src/usecases/machine_use_case.py`](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/machine_use_case.py) (Machine scan), [`scanner/src/controllers/main_controller.py`](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/controllers/main_controller.py) (Main controller), [`scanner/src/usecases/check_tcp_service.py`](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/check_tcp_service.py) (TCP service check)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP interface"]
  node_api["Flask API<br/>[api_resource.py]"]
  node_controller["Main controller<br/>[main_controller.py]"]
end

subgraph group_orchestration["Scan orchestration"]
  node_composition["Application wiring<br/>[main.py]"]
  node_scan_machines["Machine scan"]
  node_scan_network["Network discovery<br/>[scan_network.py]"]
  node_expected_services["Expected TCP checks"]
end

subgraph group_probes["Network probes"]
  node_availability["Availability check"]
  node_tcp_check["TCP service check"]
  node_tls_check["TLS certificate check"]
  node_system_metrics["System metrics"]
  node_network_port["Scanner interface<br/>[network_scanner.py]"]
  node_icmp_port["ICMP interface<br/>[icmp.py]"]
  node_tcp_port["TCP interface<br/>[tcp.py]"]
  node_tls_port["TLS interface<br/>[tls.py]"]
  node_ssh_port["SSH metrics interface<br/>[ssh.py]"]
  node_nmap["Nmap adapter<br/>[nmap_adapter.py]"]
  node_icmp["ICMP adapter<br/>[icmp_adapter.py]"]
  node_tcp["TCP adapter<br/>[tcp_adapter.py]"]
  node_tls["TLS adapter<br/>[tls_adapter.py]"]
  node_ssh["SSH metrics adapter<br/>[ssh_adapter.py]"]
end

subgraph group_domain["Domain and presentation"]
  node_machine["Machine model<br/>[machine.py]"]
  node_service["Service model<br/>[service.py]"]
  node_certificate["Certificate model<br/>[certificate.py]"]
  node_system_entities["Metrics models<br/>[system_metrics.py]"]
  node_tcp_entity["TCP result model<br/>[tcp_check.py]"]
  node_snapshot["Snapshot presenter"]
  node_scan_presenter["Scan presenter<br/>[scan_presenter.py]"]
  node_machine_presenter["Machine presenter"]
  node_scan_response["Scan response<br/>[scan_response.py]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_api
node_api -->|"delegates scans"| node_controller
node_controller -->|"runs scan"| node_scan_machines
node_controller -->|"runs checks"| node_expected_services
node_controller -->|"formats snapshot"| node_snapshot
node_composition -->|"creates app"| node_api
node_composition -->|"builds controller"| node_controller
node_composition -->|"injects dependencies"| node_scan_machines
node_composition -->|"injects scanner"| node_scan_network
node_composition -->|"injects checker"| node_expected_services
node_composition -->|"constructs adapter"| node_nmap
node_composition -->|"constructs adapter"| node_icmp
node_composition -->|"constructs adapter"| node_tcp
node_composition -->|"constructs adapter"| node_tls
node_composition -->|"constructs adapter"| node_ssh
node_scan_machines -->|"discovers hosts"| node_scan_network
node_scan_machines -->|"checks availability"| node_availability
node_scan_machines -->|"checks ports"| node_tcp_check
node_scan_machines -->|"reads certificates"| node_tls_check
node_scan_machines -->|"collects metrics"| node_system_metrics
node_expected_services -->|"checks targets"| node_tcp_check
node_scan_network -->|"scans hosts"| node_network_port
node_nmap -->|"implements"| node_network_port
node_icmp -->|"implements"| node_icmp_port
node_tcp -->|"implements"| node_tcp_port
node_tls -->|"implements"| node_tls_port
node_ssh -->|"implements"| node_ssh_port
node_availability -->|"probes through"| node_icmp_port
node_tcp_check -->|"probes through"| node_tcp_port
node_tcp_check -->|"creates result"| node_tcp_entity
node_tls_check -->|"reads through"| node_tls_port
node_system_metrics -->|"fetches metrics"| node_ssh_port
node_system_metrics -->|"builds metrics"| node_system_entities
node_machine -->|"contains certificates"| node_certificate
node_machine -->|"contains services"| node_service
node_service -.->|"none"| node_certificate
node_scan_presenter -->|"uses"| node_machine_presenter
node_scan_presenter -->|"formats response"| node_scan_response

click node_api "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/api/api_resource.py"
click node_controller "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/controllers/main_controller.py"
click node_composition "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/main.py"
click node_scan_machines "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/machine_use_case.py"
click node_scan_network "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/scan_network.py"
click node_expected_services "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/check_expected_services.py"
click node_availability "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/check_availability.py"
click node_tcp_check "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/check_tcp_service.py"
click node_tls_check "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/check_tls_use_case.py"
click node_system_metrics "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/collect_system_metrics.py"
click node_network_port "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/ports/network_scanner.py"
click node_icmp_port "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/ports/icmp.py"
click node_tcp_port "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/ports/tcp.py"
click node_tls_port "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/ports/tls.py"
click node_ssh_port "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/ports/ssh.py"
click node_nmap "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/adapters/nmap_adapter.py"
click node_icmp "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/adapters/icmp_adapter.py"
click node_tcp "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/adapters/tcp_adapter.py"
click node_tls "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/adapters/tls_adapter.py"
click node_ssh "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/adapters/ssh_adapter.py"
click node_machine "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/entities/machine.py"
click node_service "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/entities/service.py"
click node_certificate "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/entities/certificate.py"
click node_system_entities "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/entities/system_metrics.py"
click node_tcp_entity "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/entities/tcp_check.py"
click node_snapshot "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/presenters/snapshot_presenter.py"
click node_scan_presenter "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/presenters/scan_presenter.py"
click node_machine_presenter "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/presenters/machine_presenter.py"
click node_scan_response "https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/responses/scan_response.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_api,node_controller,node_client toneBlue
class node_composition,node_scan_machines,node_scan_network,node_expected_services toneAmber
class node_availability,node_tcp_check,node_tls_check,node_system_metrics,node_network_port,node_icmp_port,node_tcp_port,node_tls_port,node_ssh_port,node_nmap,node_icmp,node_tcp,node_tls,node_ssh toneMint
class node_machine,node_service,node_certificate,node_system_entities,node_tcp_entity,node_snapshot,node_scan_presenter,node_machine_presenter,node_scan_response toneRose
```

## Components

### HTTP interface

- [Flask API](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/api/api_resource.py): `scanner/src/api/api_resource.py`
- [Main controller](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/controllers/main_controller.py): `scanner/src/controllers/main_controller.py`

### Scan orchestration

- [Application wiring](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/main.py): `scanner/src/main.py`
- [Machine scan](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/machine_use_case.py): `scanner/src/usecases/machine_use_case.py`
- [Network discovery](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/scan_network.py): `scanner/src/usecases/scan_network.py`
- [Expected TCP checks](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/check_expected_services.py): `scanner/src/usecases/check_expected_services.py`

### Network probes

- [Availability check](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/check_availability.py): `scanner/src/usecases/check_availability.py`
- [TCP service check](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/check_tcp_service.py): `scanner/src/usecases/check_tcp_service.py`
- [TLS certificate check](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/check_tls_use_case.py): `scanner/src/usecases/check_tls_use_case.py`
- [System metrics](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/collect_system_metrics.py): `scanner/src/usecases/collect_system_metrics.py`
- [Scanner interface](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/ports/network_scanner.py): `scanner/src/usecases/ports/network_scanner.py`
- [ICMP interface](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/ports/icmp.py): `scanner/src/usecases/ports/icmp.py`
- [TCP interface](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/ports/tcp.py): `scanner/src/usecases/ports/tcp.py`
- [TLS interface](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/ports/tls.py): `scanner/src/usecases/ports/tls.py`
- [SSH metrics interface](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/ports/ssh.py): `scanner/src/usecases/ports/ssh.py`
- [Nmap adapter](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/adapters/nmap_adapter.py): `scanner/src/adapters/nmap_adapter.py`
- [ICMP adapter](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/adapters/icmp_adapter.py): `scanner/src/adapters/icmp_adapter.py`
- [TCP adapter](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/adapters/tcp_adapter.py): `scanner/src/adapters/tcp_adapter.py`
- [TLS adapter](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/adapters/tls_adapter.py): `scanner/src/adapters/tls_adapter.py`
- [SSH metrics adapter](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/adapters/ssh_adapter.py): `scanner/src/adapters/ssh_adapter.py`

### Domain and presentation

- [Machine model](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/entities/machine.py): `scanner/src/entities/machine.py`
- [Service model](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/entities/service.py): `scanner/src/entities/service.py`
- [Certificate model](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/entities/certificate.py): `scanner/src/entities/certificate.py`
- [Metrics models](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/entities/system_metrics.py): `scanner/src/entities/system_metrics.py`
- [TCP result model](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/entities/tcp_check.py): `scanner/src/entities/tcp_check.py`
- [Snapshot presenter](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/presenters/snapshot_presenter.py): `scanner/src/presenters/snapshot_presenter.py`
- [Scan presenter](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/presenters/scan_presenter.py): `scanner/src/presenters/scan_presenter.py`
- [Machine presenter](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/presenters/machine_presenter.py): `scanner/src/presenters/machine_presenter.py`
- [Scan response](https://github.com/netwatchteam/netwatch/blob/dev/scanner/src/usecases/responses/scan_response.py): `scanner/src/usecases/responses/scan_response.py`

### Other components

- **API client**

## Connections

- API client → Flask API: sends requests (evidence: `scanner/src/api/api_resource.py`)
- Flask API → Main controller: delegates scans (evidence: `scanner/src/api/api_resource.py`)
- Main controller → Machine scan: runs scan (evidence: `scanner/src/controllers/main_controller.py`)
- Main controller → Expected TCP checks: runs checks (evidence: `scanner/src/controllers/main_controller.py`)
- Main controller → Snapshot presenter: formats snapshot (evidence: `scanner/src/controllers/main_controller.py`)
- Application wiring → Flask API: creates app (evidence: `scanner/src/main.py`)
- Application wiring → Main controller: builds controller (evidence: `scanner/src/main.py`)
- Application wiring → Machine scan: injects dependencies (evidence: `scanner/src/main.py`)
- Application wiring → Network discovery: injects scanner (evidence: `scanner/src/main.py`)
- Application wiring → Expected TCP checks: injects checker (evidence: `scanner/src/main.py`)
- Application wiring → Nmap adapter: constructs adapter (evidence: `scanner/src/main.py`)
- Application wiring → ICMP adapter: constructs adapter (evidence: `scanner/src/main.py`)
- Application wiring → TCP adapter: constructs adapter (evidence: `scanner/src/main.py`)
- Application wiring → TLS adapter: constructs adapter (evidence: `scanner/src/main.py`)
- Application wiring → SSH metrics adapter: constructs adapter (evidence: `scanner/src/main.py`)
- Machine scan → Network discovery: discovers hosts (evidence: `scanner/src/usecases/machine_use_case.py`)
- Machine scan → Availability check: checks availability (evidence: `scanner/src/usecases/machine_use_case.py`)
- Machine scan → TCP service check: checks ports (evidence: `scanner/src/usecases/machine_use_case.py`)
- Machine scan → TLS certificate check: reads certificates (evidence: `scanner/src/usecases/machine_use_case.py`)
- Machine scan → System metrics: collects metrics (evidence: `scanner/src/usecases/machine_use_case.py`)
- Expected TCP checks → TCP service check: checks targets (evidence: `scanner/src/usecases/check_expected_services.py`)
- Network discovery → Scanner interface: scans hosts (evidence: `scanner/src/usecases/scan_network.py`)
- Nmap adapter → Scanner interface: implements (evidence: `scanner/src/adapters/nmap_adapter.py`)
- ICMP adapter → ICMP interface: implements (evidence: `scanner/src/adapters/icmp_adapter.py`)
- TCP adapter → TCP interface: implements (evidence: `scanner/src/adapters/tcp_adapter.py`)
- TLS adapter → TLS interface: implements (evidence: `scanner/src/adapters/tls_adapter.py`)
- SSH metrics adapter → SSH metrics interface: implements (evidence: `scanner/src/adapters/ssh_adapter.py`)
- Availability check → ICMP interface: probes through (evidence: `scanner/src/usecases/check_availability.py`)
- TCP service check → TCP interface: probes through (evidence: `scanner/src/usecases/check_tcp_service.py`)
- TCP service check → TCP result model: creates result (evidence: `scanner/src/usecases/check_tcp_service.py`)
- TLS certificate check → TLS interface: reads through (evidence: `scanner/src/usecases/check_tls_use_case.py`)
- System metrics → SSH metrics interface: fetches metrics (evidence: `scanner/src/usecases/collect_system_metrics.py`)
- System metrics → Metrics models: builds metrics (evidence: `scanner/src/usecases/collect_system_metrics.py`)
- Machine model → Certificate model: contains certificates (evidence: `scanner/src/entities/machine.py`)
- Machine model → Service model: contains services (evidence: `scanner/src/entities/machine.py`)
- Service model → Certificate model: none
- Scan presenter → Machine presenter: uses (evidence: `scanner/src/presenters/scan_presenter.py`)
- Scan presenter → Scan response: formats response (evidence: `scanner/src/presenters/scan_presenter.py`)
