# dukedesouth/portwatch architecture

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

- Interactive diagram: https://gitdiagram.com/dukedesouth/portwatch
- Repository: https://github.com/dukedesouth/portwatch

## Overview

portwatch is a terminal port and process monitor. Its main workflow scans listening ports, enriches them with process metrics, classifies them by service and risk, and presents a refreshable interactive view with filtering, sorting, and confirmed process termination. The CLI also supports JSON and direct-kill modes, plus demo data. The process-enrichment implementation was not sampled, so its internal data sources are not shown.

Main entry points: [`src/app.tsx`](https://github.com/dukedesouth/portwatch/blob/main/src/app.tsx) (Interactive app), [`src/cli.tsx`](https://github.com/dukedesouth/portwatch/blob/main/src/cli.tsx) (CLI modes), [`src/components/PortTable.tsx`](https://github.com/dukedesouth/portwatch/blob/main/src/components/PortTable.tsx) (Port table), [`src/hooks/usePortData.ts`](https://github.com/dukedesouth/portwatch/blob/main/src/hooks/usePortData.ts) (Refresh and state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and interaction"]
  node_cli["CLI modes<br/>[cli.tsx]"]
  node_app["Interactive app<br/>[app.tsx]"]
end

subgraph group_discovery["Port discovery"]
  node_datahook["Refresh and state<br/>[usePortData.ts]"]
  node_scanner["Listening-port scan<br/>[ports.ts]"]
end

subgraph group_analysis["Enrichment and classification"]
  node_enrichment["Process enrichment<br/>[processes.ts]"]
  node_catalog["Service and risk catalog<br/>[portdb.ts]"]
end

subgraph group_presentation["Terminal presentation"]
  node_header["Status header<br/>[Header.tsx]"]
  node_table["Port table<br/>[PortTable.tsx]"]
  node_status["Shortcut bar<br/>[StatusBar.tsx]"]
  node_confirm["Kill confirmation<br/>[KillConfirm.tsx]"]
  node_json["JSON output<br/>[cli.tsx]"]
end

subgraph group_actions["Demo and termination"]
  node_demo["Sample port data<br/>[demo.ts]"]
  node_killer["Process termination<br/>[killer.ts]"]
end

node_user(("Terminal user"))
node_osutils["OS port utilities"]
node_terminal["Terminal display"]

node_user -->|"runs"| node_cli
node_cli -->|"renders TUI"| node_app
node_cli -->|"scans ports"| node_scanner
node_cli -->|"enriches data"| node_enrichment
node_cli -->|"classifies ports"| node_catalog
node_cli -->|"kills process"| node_killer
node_cli -->|"prints JSON"| node_json
node_datahook -->|"scans ports"| node_scanner
node_datahook -->|"enriches data"| node_enrichment
node_scanner -->|"queries listeners"| node_osutils
node_app -->|"reads refreshed data"| node_datahook
node_app -->|"loads sample data"| node_demo
node_app -->|"counts risk levels"| node_catalog
node_app -->|"kills selected process"| node_killer
node_app -->|"supplies status"| node_header
node_app -->|"supplies port rows"| node_table
node_app -->|"supplies filter state"| node_status
node_app -->|"shows confirmation"| node_confirm
node_table -->|"looks up metadata"| node_catalog
node_header -->|"renders status"| node_terminal
node_table -->|"renders ports"| node_terminal
node_status -->|"renders shortcuts"| node_terminal
node_confirm -->|"renders prompt"| node_terminal
node_json -->|"prints result"| node_terminal

click node_cli "https://github.com/dukedesouth/portwatch/blob/main/src/cli.tsx"
click node_app "https://github.com/dukedesouth/portwatch/blob/main/src/app.tsx"
click node_datahook "https://github.com/dukedesouth/portwatch/blob/main/src/hooks/usePortData.ts"
click node_scanner "https://github.com/dukedesouth/portwatch/blob/main/src/services/ports.ts"
click node_enrichment "https://github.com/dukedesouth/portwatch/blob/main/src/services/processes.ts"
click node_catalog "https://github.com/dukedesouth/portwatch/blob/main/src/services/portdb.ts"
click node_demo "https://github.com/dukedesouth/portwatch/blob/main/src/services/demo.ts"
click node_killer "https://github.com/dukedesouth/portwatch/blob/main/src/services/killer.ts"
click node_header "https://github.com/dukedesouth/portwatch/blob/main/src/components/Header.tsx"
click node_table "https://github.com/dukedesouth/portwatch/blob/main/src/components/PortTable.tsx"
click node_status "https://github.com/dukedesouth/portwatch/blob/main/src/components/StatusBar.tsx"
click node_confirm "https://github.com/dukedesouth/portwatch/blob/main/src/components/KillConfirm.tsx"
click node_json "https://github.com/dukedesouth/portwatch/blob/main/src/cli.tsx"

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_cli,node_app,node_user toneBlue
class node_datahook,node_scanner toneAmber
class node_enrichment,node_catalog toneMint
class node_header,node_table,node_status,node_confirm,node_json toneRose
class node_demo,node_killer,node_osutils,node_terminal toneIndigo
```

## Components

### CLI and interaction

- [CLI modes](https://github.com/dukedesouth/portwatch/blob/main/src/cli.tsx): `src/cli.tsx`
- [Interactive app](https://github.com/dukedesouth/portwatch/blob/main/src/app.tsx): `src/app.tsx`

### Port discovery

- [Refresh and state](https://github.com/dukedesouth/portwatch/blob/main/src/hooks/usePortData.ts): `src/hooks/usePortData.ts`
- [Listening-port scan](https://github.com/dukedesouth/portwatch/blob/main/src/services/ports.ts): `src/services/ports.ts`

### Enrichment and classification

- [Process enrichment](https://github.com/dukedesouth/portwatch/blob/main/src/services/processes.ts): `src/services/processes.ts`
- [Service and risk catalog](https://github.com/dukedesouth/portwatch/blob/main/src/services/portdb.ts): `src/services/portdb.ts`

### Terminal presentation

- [Status header](https://github.com/dukedesouth/portwatch/blob/main/src/components/Header.tsx): `src/components/Header.tsx`
- [Port table](https://github.com/dukedesouth/portwatch/blob/main/src/components/PortTable.tsx): `src/components/PortTable.tsx`
- [Shortcut bar](https://github.com/dukedesouth/portwatch/blob/main/src/components/StatusBar.tsx): `src/components/StatusBar.tsx`
- [Kill confirmation](https://github.com/dukedesouth/portwatch/blob/main/src/components/KillConfirm.tsx): `src/components/KillConfirm.tsx`
- [JSON output](https://github.com/dukedesouth/portwatch/blob/main/src/cli.tsx): `src/cli.tsx`

### Demo and termination

- [Sample port data](https://github.com/dukedesouth/portwatch/blob/main/src/services/demo.ts): `src/services/demo.ts`
- [Process termination](https://github.com/dukedesouth/portwatch/blob/main/src/services/killer.ts): `src/services/killer.ts`

### Other components

- **Terminal user**
- **OS port utilities**
- **Terminal display**

## Connections

- Terminal user → CLI modes: runs
- CLI modes → Interactive app: renders TUI
- CLI modes → Listening-port scan: scans ports
- CLI modes → Process enrichment: enriches data
- CLI modes → Service and risk catalog: classifies ports
- CLI modes → Process termination: kills process
- CLI modes → JSON output: prints JSON
- Refresh and state → Listening-port scan: scans ports
- Refresh and state → Process enrichment: enriches data
- Listening-port scan → OS port utilities: queries listeners
- Interactive app → Refresh and state: reads refreshed data
- Interactive app → Sample port data: loads sample data
- Interactive app → Service and risk catalog: counts risk levels
- Interactive app → Process termination: kills selected process
- Interactive app → Status header: supplies status
- Interactive app → Port table: supplies port rows
- Interactive app → Shortcut bar: supplies filter state
- Interactive app → Kill confirmation: shows confirmation
- Port table → Service and risk catalog: looks up metadata
- Status header → Terminal display: renders status
- Port table → Terminal display: renders ports
- Shortcut bar → Terminal display: renders shortcuts
- Kill confirmation → Terminal display: renders prompt
- JSON output → Terminal display: prints result