# ramonvermeulen/whosthere architecture

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

- Interactive diagram: https://gitdiagram.com/ramonvermeulen/whosthere
- Repository: https://github.com/ramonvermeulen/whosthere

## Overview

Whosthere discovers and enriches LAN devices, then presents results through an interactive terminal UI or a single-scan CLI; daemon mode exposes live device data over HTTP. The main discovery path configures concurrent mDNS, SSDP, and ARP scanners plus an optional subnet sweeper, merging observations and looking up manufacturers. Other product branches include port scanning, persistent device aliases, YAML configuration, and theming. Relationships for unsampled capabilities are included only where documented by the README; source-level edges cite the available excerpts or index references.

Main entry points: [`internal/core/engine_builder.go`](https://github.com/ramonvermeulen/whosthere/blob/main/internal/core/engine_builder.go) (Engine builder), [`pkg/discovery/engine.go`](https://github.com/ramonvermeulen/whosthere/blob/main/pkg/discovery/engine.go) (Discovery engine), [`internal/cmd`](https://github.com/ramonvermeulen/whosthere/tree/main/internal/cmd) (CLI commands), [`internal/ui/app.go`](https://github.com/ramonvermeulen/whosthere/blob/main/internal/ui/app.go) (Interactive TUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Commands and configuration"]
  node_commands["CLI commands"]
  node_configuration["Configuration"]
  node_daemon_api["Daemon HTTP API<br/>[daemon.go]"]
  node_output["Scan output<br/>[output.go]"]
end

subgraph group_discovery["LAN discovery"]
  node_engine_builder["Engine builder<br/>[engine_builder.go]"]
  node_engine["Discovery engine<br/>[engine.go]"]
  node_mdns["mDNS scanner<br/>[mdns.go]"]
  node_ssdp["SSDP scanner<br/>[ssdp.go]"]
  node_arp["ARP scanner<br/>[arp.go]"]
  node_sweeper["Subnet sweeper<br/>[sweeper.go]"]
  node_oui["OUI enrichment<br/>[oui.go]"]
  node_port_scanner["Port scanner<br/>[port_scanner.go]"]
end

subgraph group_presentation["User experience and state"]
  node_app["Interactive TUI<br/>[app.go]"]
  node_app_state["Device state<br/>[state.go]"]
  node_dashboard["Device dashboard<br/>[dashboard.go]"]
  node_device_table["Device table<br/>[device_table.go]"]
  node_detail_view["Device details<br/>[detail.go]"]
  node_theme["Themes<br/>[theme.go]"]
end

subgraph group_persistence["Device metadata"]
  node_aliases["Alias import/export<br/>[importer.go]"]
  node_alias_store[("Alias database<br/>[bbolt_store.go]")]
end

node_operator(("Network operator"))
node_lan{{"Local network"}}
node_api_client(("HTTP API client"))

node_operator -->|"runs"| node_commands
node_commands -->|"loads"| node_configuration
node_commands -->|"builds engine"| node_engine_builder
node_engine_builder -->|"configures"| node_engine
node_engine_builder -->|"registers"| node_mdns
node_engine_builder -->|"registers"| node_ssdp
node_engine_builder -->|"registers"| node_arp
node_engine_builder -->|"configures"| node_sweeper
node_engine_builder -->|"initializes"| node_oui
node_engine -->|"runs concurrently"| node_mdns
node_engine -->|"runs concurrently"| node_ssdp
node_engine -->|"runs concurrently"| node_arp
node_engine -->|"starts"| node_sweeper
node_engine -->|"enriches devices"| node_oui
node_mdns -->|"discovers devices"| node_lan
node_ssdp -->|"discovers devices"| node_lan
node_arp -->|"reads ARP cache"| node_lan
node_sweeper -->|"probes subnet"| node_lan
node_commands -->|"formats results"| node_output
node_commands -->|"starts TUI"| node_app
node_app -->|"starts scans"| node_engine
node_app -->|"creates state"| node_app_state
node_app -->|"shows views"| node_dashboard
node_dashboard -->|"renders"| node_device_table
node_device_table -->|"reads devices"| node_app_state
node_detail_view -->|"reads selection"| node_app_state
node_app -->|"applies theme"| node_theme
node_operator -->|"starts daemon"| node_daemon_api
node_daemon_api -->|"builds engine"| node_engine_builder
node_daemon_api -->|"starts scans"| node_engine
node_daemon_api -->|"stores discoveries"| node_app_state
node_api_client -->|"requests devices"| node_daemon_api
node_commands -->|"imports or exports"| node_aliases
node_aliases -->|"reads and writes"| node_alias_store
node_app -->|"loads and saves aliases"| node_alias_store
node_detail_view -->|"requests scan"| node_port_scanner

click node_commands "https://github.com/ramonvermeulen/whosthere/tree/main/internal/cmd"
click node_configuration "https://github.com/ramonvermeulen/whosthere/tree/main/internal/core/config"
click node_engine_builder "https://github.com/ramonvermeulen/whosthere/blob/main/internal/core/engine_builder.go"
click node_engine "https://github.com/ramonvermeulen/whosthere/blob/main/pkg/discovery/engine.go"
click node_mdns "https://github.com/ramonvermeulen/whosthere/blob/main/pkg/discovery/scanners/mdns/mdns.go"
click node_ssdp "https://github.com/ramonvermeulen/whosthere/blob/main/pkg/discovery/scanners/ssdp/ssdp.go"
click node_arp "https://github.com/ramonvermeulen/whosthere/blob/main/pkg/discovery/scanners/arp/arp.go"
click node_sweeper "https://github.com/ramonvermeulen/whosthere/blob/main/pkg/discovery/sweeper/sweeper.go"
click node_oui "https://github.com/ramonvermeulen/whosthere/blob/main/pkg/discovery/oui/oui.go"
click node_port_scanner "https://github.com/ramonvermeulen/whosthere/blob/main/pkg/discovery/port_scanner.go"
click node_app "https://github.com/ramonvermeulen/whosthere/blob/main/internal/ui/app.go"
click node_app_state "https://github.com/ramonvermeulen/whosthere/blob/main/internal/core/state/state.go"
click node_dashboard "https://github.com/ramonvermeulen/whosthere/blob/main/internal/ui/views/dashboard.go"
click node_device_table "https://github.com/ramonvermeulen/whosthere/blob/main/internal/ui/components/device_table.go"
click node_detail_view "https://github.com/ramonvermeulen/whosthere/blob/main/internal/ui/views/detail.go"
click node_theme "https://github.com/ramonvermeulen/whosthere/blob/main/internal/ui/theme/theme.go"
click node_daemon_api "https://github.com/ramonvermeulen/whosthere/blob/main/internal/cmd/daemon.go"
click node_aliases "https://github.com/ramonvermeulen/whosthere/blob/main/internal/core/aliases/importer.go"
click node_alias_store "https://github.com/ramonvermeulen/whosthere/blob/main/internal/core/devicemeta/bbolt_store.go"
click node_output "https://github.com/ramonvermeulen/whosthere/blob/main/internal/core/output/output.go"

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_commands,node_configuration,node_daemon_api,node_output,node_api_client toneBlue
class node_engine_builder,node_engine,node_mdns,node_ssdp,node_arp,node_sweeper,node_oui,node_port_scanner toneAmber
class node_app,node_app_state,node_dashboard,node_device_table,node_detail_view,node_theme toneMint
class node_aliases,node_alias_store toneRose
class node_operator,node_lan toneIndigo
```

## Components

### Commands and configuration

- [CLI commands](https://github.com/ramonvermeulen/whosthere/tree/main/internal/cmd): `internal/cmd`
- [Configuration](https://github.com/ramonvermeulen/whosthere/tree/main/internal/core/config): `internal/core/config`
- [Daemon HTTP API](https://github.com/ramonvermeulen/whosthere/blob/main/internal/cmd/daemon.go): `internal/cmd/daemon.go`
- [Scan output](https://github.com/ramonvermeulen/whosthere/blob/main/internal/core/output/output.go): `internal/core/output/output.go`

### LAN discovery

- [Engine builder](https://github.com/ramonvermeulen/whosthere/blob/main/internal/core/engine_builder.go): `internal/core/engine_builder.go`
- [Discovery engine](https://github.com/ramonvermeulen/whosthere/blob/main/pkg/discovery/engine.go): `pkg/discovery/engine.go`
- [mDNS scanner](https://github.com/ramonvermeulen/whosthere/blob/main/pkg/discovery/scanners/mdns/mdns.go): `pkg/discovery/scanners/mdns/mdns.go`
- [SSDP scanner](https://github.com/ramonvermeulen/whosthere/blob/main/pkg/discovery/scanners/ssdp/ssdp.go): `pkg/discovery/scanners/ssdp/ssdp.go`
- [ARP scanner](https://github.com/ramonvermeulen/whosthere/blob/main/pkg/discovery/scanners/arp/arp.go): `pkg/discovery/scanners/arp/arp.go`
- [Subnet sweeper](https://github.com/ramonvermeulen/whosthere/blob/main/pkg/discovery/sweeper/sweeper.go): `pkg/discovery/sweeper/sweeper.go`
- [OUI enrichment](https://github.com/ramonvermeulen/whosthere/blob/main/pkg/discovery/oui/oui.go): `pkg/discovery/oui/oui.go`
- [Port scanner](https://github.com/ramonvermeulen/whosthere/blob/main/pkg/discovery/port_scanner.go): `pkg/discovery/port_scanner.go`

### User experience and state

- [Interactive TUI](https://github.com/ramonvermeulen/whosthere/blob/main/internal/ui/app.go): `internal/ui/app.go`
- [Device state](https://github.com/ramonvermeulen/whosthere/blob/main/internal/core/state/state.go): `internal/core/state/state.go`
- [Device dashboard](https://github.com/ramonvermeulen/whosthere/blob/main/internal/ui/views/dashboard.go): `internal/ui/views/dashboard.go`
- [Device table](https://github.com/ramonvermeulen/whosthere/blob/main/internal/ui/components/device_table.go): `internal/ui/components/device_table.go`
- [Device details](https://github.com/ramonvermeulen/whosthere/blob/main/internal/ui/views/detail.go): `internal/ui/views/detail.go`
- [Themes](https://github.com/ramonvermeulen/whosthere/blob/main/internal/ui/theme/theme.go): `internal/ui/theme/theme.go`

### Device metadata

- [Alias import/export](https://github.com/ramonvermeulen/whosthere/blob/main/internal/core/aliases/importer.go): `internal/core/aliases/importer.go`
- [Alias database](https://github.com/ramonvermeulen/whosthere/blob/main/internal/core/devicemeta/bbolt_store.go): `internal/core/devicemeta/bbolt_store.go`

### Other components

- **Network operator**
- **Local network**
- **HTTP API client**

## Connections

- Network operator → CLI commands: runs
- CLI commands → Configuration: loads (evidence: `internal/cmd/scan.go`)
- CLI commands → Engine builder: builds engine (evidence: `internal/cmd/scan.go`)
- Engine builder → Discovery engine: configures (evidence: `internal/core/engine_builder.go`)
- Engine builder → mDNS scanner: registers (evidence: `internal/core/engine_builder.go`)
- Engine builder → SSDP scanner: registers (evidence: `internal/core/engine_builder.go`)
- Engine builder → ARP scanner: registers (evidence: `internal/core/engine_builder.go`)
- Engine builder → Subnet sweeper: configures (evidence: `internal/core/engine_builder.go`)
- Engine builder → OUI enrichment: initializes (evidence: `internal/core/engine_builder.go`)
- Discovery engine → mDNS scanner: runs concurrently (evidence: `pkg/discovery/engine.go`)
- Discovery engine → SSDP scanner: runs concurrently (evidence: `pkg/discovery/engine.go`)
- Discovery engine → ARP scanner: runs concurrently (evidence: `pkg/discovery/engine.go`)
- Discovery engine → Subnet sweeper: starts (evidence: `pkg/discovery/engine.go`)
- Discovery engine → OUI enrichment: enriches devices (evidence: `pkg/discovery/engine.go`)
- mDNS scanner → Local network: discovers devices
- SSDP scanner → Local network: discovers devices
- ARP scanner → Local network: reads ARP cache
- Subnet sweeper → Local network: probes subnet
- CLI commands → Scan output: formats results (evidence: `internal/cmd/scan.go`)
- CLI commands → Interactive TUI: starts TUI (evidence: `internal/cmd/root.go`)
- Interactive TUI → Discovery engine: starts scans (evidence: `internal/ui/app.go`)
- Interactive TUI → Device state: creates state (evidence: `internal/ui/app.go`)
- Interactive TUI → Device dashboard: shows views (evidence: `internal/ui/app.go`)
- Device dashboard → Device table: renders (evidence: `internal/ui/views/dashboard.go`)
- Device table → Device state: reads devices (evidence: `internal/ui/components/device_table.go`)
- Device details → Device state: reads selection (evidence: `internal/ui/views/detail.go`)
- Interactive TUI → Themes: applies theme
- Network operator → Daemon HTTP API: starts daemon
- Daemon HTTP API → Engine builder: builds engine (evidence: `internal/cmd/daemon.go`)
- Daemon HTTP API → Discovery engine: starts scans (evidence: `internal/cmd/daemon.go`)
- Daemon HTTP API → Device state: stores discoveries (evidence: `internal/cmd/daemon.go`)
- HTTP API client → Daemon HTTP API: requests devices
- CLI commands → Alias import/export: imports or exports (evidence: `internal/cmd/aliases.go`)
- Alias import/export → Alias database: reads and writes (evidence: `internal/core/aliases/importer.go`)
- Interactive TUI → Alias database: loads and saves aliases (evidence: `internal/ui/app.go`)
- Device details → Port scanner: requests scan
