# robotics-now/localhost-manager architecture

> Architecture diagram of the GitHub repository robotics-now/localhost-manager, 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/robotics-now/localhost-manager
- Repository: https://github.com/robotics-now/localhost-manager

## Overview

Localhost Manager is a Chrome extension for discovering local services and optionally hosting HTML projects through a separately run local control server. The main workflow is popup-driven port scanning and display, with optional auto-scan caching, network discovery, and HTML hosting; settings configure these behaviors, while a background worker maintains the toolbar badge. Server details are sampled only partially, so the graph includes documented API capabilities and omits uncertain internal wiring.

Main entry points: [`port_ext/scripts/popup.js`](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/scripts/popup.js) (Popup Logic), [`port_ext/scripts/settings.js`](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/scripts/settings.js) (Settings Logic), [`port_ext/background.js`](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/background.js) (Badge Worker), [`port_ext/servers/server.js`](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/servers/server.js) (Control API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Browser Extension"]
  node_popup["Popup Interface<br/>[popup.html]"]
  node_popup_logic["Popup Logic<br/>[popup.js]"]
  node_settings["Settings Page<br/>[settings.html]"]
  node_settings_logic["Settings Logic<br/>[settings.js]"]
  node_background["Badge Worker<br/>[background.js]"]
  node_storage[("Extension Storage")]
  node_themes["Appearance Settings<br/>[settings.js]"]
end

subgraph group_discovery["Port Discovery"]
  node_local_ports(("Local Services"))
  node_port_scan["Port Scanner<br/>[popup.js]"]
  node_auto_scan["Auto Scan Cache<br/>[popup.js]"]
  node_network_scan["Network Scanner<br/>[popup.js]"]
  node_network_devices(("Network Devices"))
end

subgraph group_hosting["Local Hosting"]
  node_hosted_site["Hosted HTTP Site<br/>[server.js]"]
  node_html_files["HTML Project Files"]
  node_browser(("Browser Tabs"))
end

subgraph group_control["Control Server"]
  node_control_api["Control API<br/>[server.js]"]
  node_python_api["Python API<br/>[server.py]"]
  node_host_manager["Hosted Server Manager<br/>[server.js]"]
  node_multi_host["Project File Hosting<br/>[server.js]"]
  node_host_state[("Hosted Servers<br/>[server.js]")]
end

node_user(("User"))

node_user -->|"opens"| node_popup
node_popup -->|"dispatches"| node_popup_logic
node_popup_logic -->|"scans"| node_port_scan
node_port_scan -->|"probes"| node_local_ports
node_port_scan -->|"reads/writes cache"| node_storage
node_popup_logic -.->|"runs optionally"| node_auto_scan
node_auto_scan -->|"reads/writes cache"| node_storage
node_popup_logic -.->|"runs optionally"| node_network_scan
node_network_scan -->|"probes"| node_network_devices
node_popup_logic -->|"reads/writes preferences"| node_storage
node_popup_logic -->|"reports status"| node_background
node_background -->|"reads preferences"| node_storage
node_background -->|"probes"| node_local_ports
node_background -->|"checks health"| node_control_api
node_user -->|"opens"| node_settings
node_settings -->|"dispatches"| node_settings_logic
node_settings_logic -->|"reads/writes settings"| node_storage
node_settings_logic -->|"updates badge"| node_background
node_settings_logic -->|"checks status"| node_control_api
node_settings_logic -->|"configures"| node_themes
node_popup_logic -->|"checks status"| node_control_api
node_popup_logic -->|"starts/stops hosting"| node_host_manager
node_popup_logic -->|"uploads project"| node_multi_host
node_html_files -->|"file selection"| node_popup_logic
node_control_api -->|"dispatches"| node_host_manager
node_control_api -->|"dispatches"| node_multi_host
node_host_manager -->|"records hosted server"| node_host_state
node_multi_host -->|"records hosted server"| node_host_state
node_host_manager -->|"starts/stops"| node_hosted_site
node_multi_host -->|"starts/stops"| node_hosted_site
node_hosted_site -->|"serves pages"| node_browser
node_python_api -.->|"provides equivalent hosting"| node_hosted_site
node_popup_logic -->|"opens service"| node_browser

click node_popup "https://github.com/robotics-now/localhost-manager/blob/main/port_ext/templates/popup.html"
click node_popup_logic "https://github.com/robotics-now/localhost-manager/blob/main/port_ext/scripts/popup.js"
click node_settings "https://github.com/robotics-now/localhost-manager/blob/main/port_ext/templates/settings.html"
click node_settings_logic "https://github.com/robotics-now/localhost-manager/blob/main/port_ext/scripts/settings.js"
click node_background "https://github.com/robotics-now/localhost-manager/blob/main/port_ext/background.js"
click node_port_scan "https://github.com/robotics-now/localhost-manager/blob/main/port_ext/scripts/popup.js"
click node_auto_scan "https://github.com/robotics-now/localhost-manager/blob/main/port_ext/scripts/popup.js"
click node_network_scan "https://github.com/robotics-now/localhost-manager/blob/main/port_ext/scripts/popup.js"
click node_control_api "https://github.com/robotics-now/localhost-manager/blob/main/port_ext/servers/server.js"
click node_python_api "https://github.com/robotics-now/localhost-manager/blob/main/port_ext/servers/server.py"
click node_host_manager "https://github.com/robotics-now/localhost-manager/blob/main/port_ext/servers/server.js"
click node_multi_host "https://github.com/robotics-now/localhost-manager/blob/main/port_ext/servers/server.js"
click node_host_state "https://github.com/robotics-now/localhost-manager/blob/main/port_ext/servers/server.js"
click node_hosted_site "https://github.com/robotics-now/localhost-manager/blob/main/port_ext/servers/server.js"
click node_themes "https://github.com/robotics-now/localhost-manager/blob/main/port_ext/scripts/settings.js"

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_popup,node_popup_logic,node_settings,node_settings_logic,node_background,node_storage,node_themes,node_user toneBlue
class node_local_ports,node_port_scan,node_auto_scan,node_network_scan,node_network_devices toneAmber
class node_hosted_site,node_html_files,node_browser toneMint
class node_control_api,node_python_api,node_host_manager,node_multi_host,node_host_state toneRose
```

## Components

### Browser Extension

- [Popup Interface](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/templates/popup.html): `port_ext/templates/popup.html`
- [Popup Logic](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/scripts/popup.js): `port_ext/scripts/popup.js`
- [Settings Page](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/templates/settings.html): `port_ext/templates/settings.html`
- [Settings Logic](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/scripts/settings.js): `port_ext/scripts/settings.js`
- [Badge Worker](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/background.js): `port_ext/background.js`
- **Extension Storage**
- [Appearance Settings](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/scripts/settings.js): `port_ext/scripts/settings.js`

### Port Discovery

- **Local Services**
- [Port Scanner](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/scripts/popup.js): `port_ext/scripts/popup.js`
- [Auto Scan Cache](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/scripts/popup.js): `port_ext/scripts/popup.js`
- [Network Scanner](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/scripts/popup.js): `port_ext/scripts/popup.js`
- **Network Devices**

### Local Hosting

- [Hosted HTTP Site](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/servers/server.js): `port_ext/servers/server.js`
- **HTML Project Files**
- **Browser Tabs**

### Control Server

- [Control API](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/servers/server.js): `port_ext/servers/server.js`
- [Python API](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/servers/server.py): `port_ext/servers/server.py`
- [Hosted Server Manager](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/servers/server.js): `port_ext/servers/server.js`
- [Project File Hosting](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/servers/server.js): `port_ext/servers/server.js`
- [Hosted Servers](https://github.com/robotics-now/localhost-manager/blob/main/port_ext/servers/server.js): `port_ext/servers/server.js`

### Other components

- **User**

## Connections

- User → Popup Interface: opens
- Popup Interface → Popup Logic: dispatches
- Popup Logic → Port Scanner: scans
- Port Scanner → Local Services: probes
- Port Scanner → Extension Storage: reads/writes cache
- Popup Logic → Auto Scan Cache: runs optionally
- Auto Scan Cache → Extension Storage: reads/writes cache
- Popup Logic → Network Scanner: runs optionally
- Network Scanner → Network Devices: probes
- Popup Logic → Extension Storage: reads/writes preferences
- Popup Logic → Badge Worker: reports status
- Badge Worker → Extension Storage: reads preferences
- Badge Worker → Local Services: probes
- Badge Worker → Control API: checks health
- User → Settings Page: opens
- Settings Page → Settings Logic: dispatches
- Settings Logic → Extension Storage: reads/writes settings
- Settings Logic → Badge Worker: updates badge
- Settings Logic → Control API: checks status
- Settings Logic → Appearance Settings: configures
- Popup Logic → Control API: checks status
- Popup Logic → Hosted Server Manager: starts/stops hosting
- Popup Logic → Project File Hosting: uploads project
- HTML Project Files → Popup Logic: file selection
- Control API → Hosted Server Manager: dispatches
- Control API → Project File Hosting: dispatches
- Hosted Server Manager → Hosted Servers: records hosted server
- Project File Hosting → Hosted Servers: records hosted server
- Hosted Server Manager → Hosted HTTP Site: starts/stops
- Project File Hosting → Hosted HTTP Site: starts/stops
- Hosted HTTP Site → Browser Tabs: serves pages
- Python API → Hosted HTTP Site: provides equivalent hosting
- Popup Logic → Browser Tabs: opens service