# heymaikol/network-doctor architecture

> Architecture diagram of the GitHub repository heymaikol/network-doctor, 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/heymaikol/network-doctor
- Repository: https://github.com/heymaikol/network-doctor

## Overview

Network Doctor is a cross-platform network troubleshooting CLI/TUI. Its main workflow accepts a target or local-network request, runs independent network probes, interprets their evidence into a diagnosis and remediation hints, then presents results interactively or as structured output. Additional documented capabilities include service profiles, watch-mode incident reconstruction, saved snapshots and comparisons, remote and two-ended diagnoses, and a Linux simulator used by Challenge Mode. Source excerpts are partial, so edges to unsampled subsystems are included only where the README or source index supports them.

Main entry points: [`internal/app/app.go`](https://github.com/heymaikol/network-doctor/blob/main/internal/app/app.go) (Mode orchestration), [`cmd/netdoc-sim/main.go`](https://github.com/heymaikol/network-doctor/blob/main/cmd/netdoc-sim/main.go) (Simulator commands), [`cmd/netdoc/main.go`](https://github.com/heymaikol/network-doctor/blob/main/cmd/netdoc/main.go) (CLI entrypoints), [`internal/diagnostic/checks.go`](https://github.com/heymaikol/network-doctor/blob/main/internal/diagnostic/checks.go) (Network probes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command and app"]
  node_commands["CLI entrypoints<br/>[main.go]"]
  node_app["Mode orchestration<br/>[app.go]"]
end

subgraph group_diagnostics["Diagnosis"]
  node_probe["Network probes<br/>[checks.go]"]
  node_interpret["Diagnosis and fixes<br/>[diagnosis.go]"]
  node_profile["Service profiles<br/>[profile.go]"]
end

subgraph group_experience["Results and history"]
  node_ui["Interactive TUI<br/>[model.go]"]
  node_view["Results view<br/>[view.go]"]
  node_incident["Watch incidents<br/>[incident.go]"]
  node_report["Reports<br/>[report.go]"]
  node_snapshot["Diagnostic snapshots<br/>[snapshot.go]"]
  node_compare["Snapshot comparison<br/>[compare.go]"]
  node_two_compare["Two-sided comparison<br/>[twosided.go]"]
end

subgraph group_distributed["Remote diagnosis"]
  node_peer["Peer sessions<br/>[session.go]"]
  node_peer_protocol["Peer protocol<br/>[protocol.go]"]
  node_remote["SSH remote client<br/>[client.go]"]
end

subgraph group_challenge["Simulation"]
  node_sim_command["Simulator commands<br/>[main.go]"]
  node_challenge["Challenge runner<br/>[challenge.go]"]
  node_triage["Simulation triage<br/>[triage.go]"]
  node_simulation["Virtual network engine"]
  node_fieldcase["Field replay corpus<br/>[corpus.go]"]
end

node_user(("User or script"))

node_user -->|"invokes"| node_commands
node_commands -->|"starts"| node_app
node_app -->|"runs checks"| node_probe
node_probe -->|"supplies evidence"| node_interpret
node_app -->|"composes runs"| node_profile
node_app -->|"starts TUI"| node_ui
node_ui -->|"renders"| node_view
node_app -->|"emits report"| node_report
node_app -->|"saves snapshot"| node_snapshot
node_app -->|"runs remotely"| node_remote
node_app -->|"starts peer mode"| node_peer
node_peer -->|"exchanges messages"| node_peer_protocol
node_app -->|"compares sides"| node_two_compare
node_two_compare -->|"compares snapshots"| node_compare
node_incident -->|"derives changes"| node_compare
node_app -.->|"tracks watch"| node_incident
node_app -.->|"offers challenge mode"| node_sim_command
node_sim_command -->|"dispatches"| node_challenge
node_sim_command -->|"runs scenarios"| node_simulation
node_challenge -->|"uses scenarios"| node_simulation
node_sim_command -->|"dispatches"| node_triage
node_user -.->|"provides replay"| node_fieldcase

click node_commands "https://github.com/heymaikol/network-doctor/blob/main/cmd/netdoc/main.go"
click node_app "https://github.com/heymaikol/network-doctor/blob/main/internal/app/app.go"
click node_probe "https://github.com/heymaikol/network-doctor/blob/main/internal/diagnostic/checks.go"
click node_interpret "https://github.com/heymaikol/network-doctor/blob/main/internal/diagnostic/diagnosis.go"
click node_profile "https://github.com/heymaikol/network-doctor/blob/main/internal/profile/profile.go"
click node_ui "https://github.com/heymaikol/network-doctor/blob/main/internal/ui/model.go"
click node_view "https://github.com/heymaikol/network-doctor/blob/main/internal/ui/view.go"
click node_incident "https://github.com/heymaikol/network-doctor/blob/main/internal/incident/incident.go"
click node_report "https://github.com/heymaikol/network-doctor/blob/main/internal/report/report.go"
click node_snapshot "https://github.com/heymaikol/network-doctor/blob/main/internal/snapshot/snapshot.go"
click node_compare "https://github.com/heymaikol/network-doctor/blob/main/internal/compare/compare.go"
click node_two_compare "https://github.com/heymaikol/network-doctor/blob/main/internal/compare/twosided.go"
click node_peer "https://github.com/heymaikol/network-doctor/blob/main/internal/peer/session.go"
click node_peer_protocol "https://github.com/heymaikol/network-doctor/blob/main/internal/peer/protocol.go"
click node_remote "https://github.com/heymaikol/network-doctor/blob/main/internal/remote/client.go"
click node_sim_command "https://github.com/heymaikol/network-doctor/blob/main/cmd/netdoc-sim/main.go"
click node_challenge "https://github.com/heymaikol/network-doctor/blob/main/cmd/netdoc-sim/challenge.go"
click node_triage "https://github.com/heymaikol/network-doctor/blob/main/cmd/netdoc-sim/triage.go"
click node_simulation "https://github.com/heymaikol/network-doctor/tree/main/internal/simulation"
click node_fieldcase "https://github.com/heymaikol/network-doctor/blob/main/internal/fieldcase/corpus.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_app,node_user toneBlue
class node_probe,node_interpret,node_profile toneAmber
class node_ui,node_view,node_incident,node_report,node_snapshot,node_compare,node_two_compare toneMint
class node_peer,node_peer_protocol,node_remote toneRose
class node_sim_command,node_challenge,node_triage,node_simulation,node_fieldcase toneIndigo
```

## Components

### Command and app

- [CLI entrypoints](https://github.com/heymaikol/network-doctor/blob/main/cmd/netdoc/main.go): `cmd/netdoc/main.go`
- [Mode orchestration](https://github.com/heymaikol/network-doctor/blob/main/internal/app/app.go): `internal/app/app.go`

### Diagnosis

- [Network probes](https://github.com/heymaikol/network-doctor/blob/main/internal/diagnostic/checks.go): `internal/diagnostic/checks.go`
- [Diagnosis and fixes](https://github.com/heymaikol/network-doctor/blob/main/internal/diagnostic/diagnosis.go): `internal/diagnostic/diagnosis.go`
- [Service profiles](https://github.com/heymaikol/network-doctor/blob/main/internal/profile/profile.go): `internal/profile/profile.go`

### Results and history

- [Interactive TUI](https://github.com/heymaikol/network-doctor/blob/main/internal/ui/model.go): `internal/ui/model.go`
- [Results view](https://github.com/heymaikol/network-doctor/blob/main/internal/ui/view.go): `internal/ui/view.go`
- [Watch incidents](https://github.com/heymaikol/network-doctor/blob/main/internal/incident/incident.go): `internal/incident/incident.go`
- [Reports](https://github.com/heymaikol/network-doctor/blob/main/internal/report/report.go): `internal/report/report.go`
- [Diagnostic snapshots](https://github.com/heymaikol/network-doctor/blob/main/internal/snapshot/snapshot.go): `internal/snapshot/snapshot.go`
- [Snapshot comparison](https://github.com/heymaikol/network-doctor/blob/main/internal/compare/compare.go): `internal/compare/compare.go`
- [Two-sided comparison](https://github.com/heymaikol/network-doctor/blob/main/internal/compare/twosided.go): `internal/compare/twosided.go`

### Remote diagnosis

- [Peer sessions](https://github.com/heymaikol/network-doctor/blob/main/internal/peer/session.go): `internal/peer/session.go`
- [Peer protocol](https://github.com/heymaikol/network-doctor/blob/main/internal/peer/protocol.go): `internal/peer/protocol.go`
- [SSH remote client](https://github.com/heymaikol/network-doctor/blob/main/internal/remote/client.go): `internal/remote/client.go`

### Simulation

- [Simulator commands](https://github.com/heymaikol/network-doctor/blob/main/cmd/netdoc-sim/main.go): `cmd/netdoc-sim/main.go`
- [Challenge runner](https://github.com/heymaikol/network-doctor/blob/main/cmd/netdoc-sim/challenge.go): `cmd/netdoc-sim/challenge.go`
- [Simulation triage](https://github.com/heymaikol/network-doctor/blob/main/cmd/netdoc-sim/triage.go): `cmd/netdoc-sim/triage.go`
- [Virtual network engine](https://github.com/heymaikol/network-doctor/tree/main/internal/simulation): `internal/simulation`
- [Field replay corpus](https://github.com/heymaikol/network-doctor/blob/main/internal/fieldcase/corpus.go): `internal/fieldcase/corpus.go`

### Other components

- **User or script**

## Connections

- User or script → CLI entrypoints: invokes (evidence: `README.md`)
- CLI entrypoints → Mode orchestration: starts (evidence: `cmd/netdoc/main.go`)
- Mode orchestration → Network probes: runs checks (evidence: `internal/app/app.go`)
- Network probes → Diagnosis and fixes: supplies evidence (evidence: `README.md`)
- Mode orchestration → Service profiles: composes runs (evidence: `internal/app/app.go`)
- Mode orchestration → Interactive TUI: starts TUI (evidence: `internal/app/app.go`)
- Interactive TUI → Results view: renders
- Mode orchestration → Reports: emits report
- Mode orchestration → Diagnostic snapshots: saves snapshot (evidence: `internal/app/app.go`)
- Mode orchestration → SSH remote client: runs remotely
- Mode orchestration → Peer sessions: starts peer mode (evidence: `internal/app/app.go`)
- Peer sessions → Peer protocol: exchanges messages (evidence: `internal/peer/session.go`)
- Mode orchestration → Two-sided comparison: compares sides (evidence: `internal/app/app.go`)
- Two-sided comparison → Snapshot comparison: compares snapshots (evidence: `internal/compare/twosided.go`)
- Watch incidents → Snapshot comparison: derives changes (evidence: `internal/incident/incident.go`)
- Mode orchestration → Watch incidents: tracks watch (evidence: `README.md`)
- Mode orchestration → Simulator commands: offers challenge mode (evidence: `README.md`)
- Simulator commands → Challenge runner: dispatches (evidence: `cmd/netdoc-sim/main.go`)
- Simulator commands → Virtual network engine: runs scenarios (evidence: `cmd/netdoc-sim/main.go`)
- Challenge runner → Virtual network engine: uses scenarios (evidence: `cmd/netdoc-sim/challenge.go`)
- Simulator commands → Simulation triage: dispatches (evidence: `cmd/netdoc-sim/main.go`)
- User or script → Field replay corpus: provides replay
