# ricardoleal/bastionctl architecture

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

- Interactive diagram: https://gitdiagram.com/ricardoleal/bastionctl
- Repository: https://github.com/ricardoleal/bastionctl

## Overview

bastionctl discovers and ranks AWS EC2 pivots, saves named connections, then checks and hands tunnel operations to the host’s sshuttle binary. The main documented path is interactive discovery through reachability checks and candidate selection, followed by SSH verification and saving; later runs manage the saved tunnel. Separate capabilities include a terminal browser, split-DNS setup, and simulated demo mode. Edges rely on README workflow statements or shown package behavior; the full main/UI implementation was not sampled, so finer call ownership is not inferred.

Main entry points: [`main.go`](https://github.com/ricardoleal/bastionctl/blob/main/main.go) (CLI workflow), [`internal/dnsresolver/dnsresolver.go`](https://github.com/ricardoleal/bastionctl/blob/main/internal/dnsresolver/dnsresolver.go) (Split-DNS manager), [`internal/awsclient/aws.go`](https://github.com/ricardoleal/bastionctl/blob/main/internal/awsclient/aws.go) (AWS discovery), [`internal/dnsresolver/darwin.go`](https://github.com/ricardoleal/bastionctl/blob/main/internal/dnsresolver/darwin.go) (macOS resolver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application flow"]
  node_cli["CLI workflow<br/>[main.go]"]
end

subgraph group_discovery["Pivot discovery"]
  node_aws["AWS discovery<br/>[aws.go]"]
  node_profiles["AWS profiles<br/>[profiles.go]"]
  node_reachability["Candidate probing<br/>[probe.go]"]
  node_cidr["CIDR checks<br/>[netcidr.go]"]
  node_sshverify["SSH verification<br/>[sshtest.go]"]
end

subgraph group_connections["Connections and DNS"]
  node_saved[("Connection store<br/>[config.go]")]
  node_dns["Split-DNS manager<br/>[dnsresolver.go]"]
  node_darwin["macOS resolver<br/>[darwin.go]"]
  node_linuxdns["Linux resolver<br/>[linux.go]"]
end

subgraph group_operations["Terminal and tunnel"]
  node_browser["Connection browser<br/>[app.go]"]
  node_selection["Interactive selection<br/>[select.go]"]
  node_demo["Demo browser<br/>[demo.go]"]
  node_sshuttle["Tunnel control<br/>[sshuttlecmd.go]"]
end

node_operator(("Operator"))
node_systemsshuttle["System sshuttle"]
node_awsapi["AWS APIs"]
node_osresolver["OS resolver"]

node_operator -->|"invokes"| node_cli
node_cli -->|"discovers"| node_aws
node_cli -->|"resolves credentials"| node_profiles
node_aws -->|"queries"| node_awsapi
node_cli -->|"tests candidates"| node_reachability
node_cli -->|"checks egress"| node_cidr
node_cli -->|"presents candidates"| node_selection
node_cli -->|"re-verifies target"| node_sshverify
node_cli -->|"saves connection"| node_saved
node_cli -->|"manages tunnel"| node_sshuttle
node_sshuttle -->|"launches"| node_systemsshuttle
node_cli -->|"opens browser"| node_browser
node_operator -->|"requests demo"| node_demo
node_cli -->|"manages split DNS"| node_dns
node_dns -->|"installs on macOS"| node_darwin
node_dns -->|"installs on Linux"| node_linuxdns
node_darwin -->|"writes resolver files"| node_osresolver
node_linuxdns -->|"configures network"| node_osresolver

click node_cli "https://github.com/ricardoleal/bastionctl/blob/main/main.go"
click node_browser "https://github.com/ricardoleal/bastionctl/blob/main/internal/ui/app.go"
click node_selection "https://github.com/ricardoleal/bastionctl/blob/main/internal/ui/select.go"
click node_demo "https://github.com/ricardoleal/bastionctl/blob/main/demo.go"
click node_aws "https://github.com/ricardoleal/bastionctl/blob/main/internal/awsclient/aws.go"
click node_profiles "https://github.com/ricardoleal/bastionctl/blob/main/internal/awsclient/profiles.go"
click node_reachability "https://github.com/ricardoleal/bastionctl/blob/main/internal/probe/probe.go"
click node_cidr "https://github.com/ricardoleal/bastionctl/blob/main/internal/netcidr/netcidr.go"
click node_sshverify "https://github.com/ricardoleal/bastionctl/blob/main/internal/sshtest/sshtest.go"
click node_saved "https://github.com/ricardoleal/bastionctl/blob/main/internal/config/config.go"
click node_dns "https://github.com/ricardoleal/bastionctl/blob/main/internal/dnsresolver/dnsresolver.go"
click node_darwin "https://github.com/ricardoleal/bastionctl/blob/main/internal/dnsresolver/darwin.go"
click node_linuxdns "https://github.com/ricardoleal/bastionctl/blob/main/internal/dnsresolver/linux.go"
click node_sshuttle "https://github.com/ricardoleal/bastionctl/blob/main/internal/sshuttlecmd/sshuttlecmd.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_cli toneBlue
class node_aws,node_profiles,node_reachability,node_cidr,node_sshverify toneAmber
class node_saved,node_dns,node_darwin,node_linuxdns,node_awsapi toneMint
class node_browser,node_selection,node_demo,node_sshuttle toneRose
class node_operator,node_systemsshuttle,node_osresolver toneIndigo
```

## Components

### Application flow

- [CLI workflow](https://github.com/ricardoleal/bastionctl/blob/main/main.go): `main.go`

### Pivot discovery

- [AWS discovery](https://github.com/ricardoleal/bastionctl/blob/main/internal/awsclient/aws.go): `internal/awsclient/aws.go`
- [AWS profiles](https://github.com/ricardoleal/bastionctl/blob/main/internal/awsclient/profiles.go): `internal/awsclient/profiles.go`
- [Candidate probing](https://github.com/ricardoleal/bastionctl/blob/main/internal/probe/probe.go): `internal/probe/probe.go`
- [CIDR checks](https://github.com/ricardoleal/bastionctl/blob/main/internal/netcidr/netcidr.go): `internal/netcidr/netcidr.go`
- [SSH verification](https://github.com/ricardoleal/bastionctl/blob/main/internal/sshtest/sshtest.go): `internal/sshtest/sshtest.go`

### Connections and DNS

- [Connection store](https://github.com/ricardoleal/bastionctl/blob/main/internal/config/config.go): `internal/config/config.go`
- [Split-DNS manager](https://github.com/ricardoleal/bastionctl/blob/main/internal/dnsresolver/dnsresolver.go): `internal/dnsresolver/dnsresolver.go`
- [macOS resolver](https://github.com/ricardoleal/bastionctl/blob/main/internal/dnsresolver/darwin.go): `internal/dnsresolver/darwin.go`
- [Linux resolver](https://github.com/ricardoleal/bastionctl/blob/main/internal/dnsresolver/linux.go): `internal/dnsresolver/linux.go`

### Terminal and tunnel

- [Connection browser](https://github.com/ricardoleal/bastionctl/blob/main/internal/ui/app.go): `internal/ui/app.go`
- [Interactive selection](https://github.com/ricardoleal/bastionctl/blob/main/internal/ui/select.go): `internal/ui/select.go`
- [Demo browser](https://github.com/ricardoleal/bastionctl/blob/main/demo.go): `demo.go`
- [Tunnel control](https://github.com/ricardoleal/bastionctl/blob/main/internal/sshuttlecmd/sshuttlecmd.go): `internal/sshuttlecmd/sshuttlecmd.go`

### Other components

- **Operator**
- **System sshuttle**
- **AWS APIs**
- **OS resolver**

## Connections

- Operator → CLI workflow: invokes (evidence: `README.md`)
- CLI workflow → AWS discovery: discovers (evidence: `README.md`)
- CLI workflow → AWS profiles: resolves credentials (evidence: `README.md`)
- AWS discovery → AWS APIs: queries (evidence: `README.md`)
- CLI workflow → Candidate probing: tests candidates (evidence: `README.md`)
- CLI workflow → CIDR checks: checks egress (evidence: `README.md`)
- CLI workflow → Interactive selection: presents candidates (evidence: `README.md`)
- CLI workflow → SSH verification: re-verifies target (evidence: `README.md`)
- CLI workflow → Connection store: saves connection (evidence: `README.md`)
- CLI workflow → Tunnel control: manages tunnel (evidence: `README.md`)
- Tunnel control → System sshuttle: launches (evidence: `README.md`)
- CLI workflow → Connection browser: opens browser (evidence: `README.md`)
- Operator → Demo browser: requests demo (evidence: `README.md`)
- CLI workflow → Split-DNS manager: manages split DNS (evidence: `README.md`)
- Split-DNS manager → macOS resolver: installs on macOS (evidence: `internal/dnsresolver/dnsresolver.go`)
- Split-DNS manager → Linux resolver: installs on Linux (evidence: `internal/dnsresolver/dnsresolver.go`)
- macOS resolver → OS resolver: writes resolver files (evidence: `internal/dnsresolver/darwin.go`)
- Linux resolver → OS resolver: configures network (evidence: `README.md`)