# ozdadirri/port-show architecture

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

- Interactive diagram: https://gitdiagram.com/ozdadirri/port-show
- Repository: https://github.com/ozdadirri/port-show

## Overview

PortShow is a macOS menu-bar app for discovering listening ports and managing their owning processes. The workflow starts when the user opens the popover: AppState scans ports, applies filters and favorites, and the UI presents grouped rows with actions to open, copy, reveal, pin, or stop a process. Settings, launch-at-login, and pinned-port notifications are supporting capabilities. The graph follows excerpted calls and README-documented behavior; unsampled implementation details are represented only where documented.

Main entry points: [`Sources/AppState.swift`](https://github.com/ozdadirri/port-show/blob/main/Sources/AppState.swift) (App state), [`Sources/PortScanner.swift`](https://github.com/ozdadirri/port-show/blob/main/Sources/PortScanner.swift) (Port scanner), [`Sources/main.swift`](https://github.com/ozdadirri/port-show/blob/main/Sources/main.swift) (Menu-bar app), [`Sources/PopoverViewController.swift`](https://github.com/ozdadirri/port-show/blob/main/Sources/PopoverViewController.swift) (Port popover)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and UI"]
  node_menu["Menu-bar app<br/>[main.swift]"]
  node_popover["Port popover"]
  node_row["Port row actions<br/>[PortRowView.swift]"]
end

subgraph group_ports["Port discovery"]
  node_entry["Port entry model<br/>[PortEntry.swift]"]
  node_scanner["Port scanner<br/>[PortScanner.swift]"]
end

subgraph group_state["State and preferences"]
  node_state["App state<br/>[AppState.swift]"]
  node_favorites["Pinned ports"]
  node_preferences[("App preferences<br/>[AppState.swift]")]
end

subgraph group_integrations["macOS integrations"]
  node_login["Launch-at-login"]
  node_notifications["Port notifications"]
  node_workspace["Workspace actions"]
end

node_user(("Mac user"))
node_lsof["Socket/process data"]
node_launchagent["User LaunchAgent"]
node_launchctl["launchctl"]
node_notification_service["macOS notifications"]
node_browser["Default browser"]
node_finder["Finder"]
node_pasteboard["Pasteboard"]
node_process["Owned process"]

node_user -->|"opens popover"| node_menu
node_menu -->|"starts and refreshes"| node_state
node_menu -->|"shows"| node_popover
node_popover -->|"reads settings and entries"| node_state
node_popover -->|"creates and configures"| node_row
node_row -->|"invokes row actions"| node_state
node_state -->|"requests scan"| node_scanner
node_scanner -->|"reads socket data"| node_lsof
node_scanner -->|"produces entries"| node_entry
node_state -->|"filters and groups"| node_entry
node_state -->|"checks and toggles pins"| node_favorites
node_favorites -->|"persists favorites"| node_preferences
node_state -->|"persists settings"| node_preferences
node_state -->|"toggles login launch"| node_login
node_login -->|"writes or removes"| node_launchagent
node_login -->|"loads or unloads"| node_launchctl
node_state -->|"requests and sends"| node_notifications
node_notifications -->|"posts alerts"| node_notification_service
node_state -->|"opens and copies"| node_workspace
node_workspace -->|"opens port URL"| node_browser
node_workspace -->|"copies text"| node_pasteboard
node_state -->|"kills or reveals process"| node_scanner
node_scanner -->|"reveals start file"| node_finder
node_scanner -->|"sends SIGTERM"| node_process

click node_menu "https://github.com/ozdadirri/port-show/blob/main/Sources/main.swift"
click node_popover "https://github.com/ozdadirri/port-show/blob/main/Sources/PopoverViewController.swift"
click node_row "https://github.com/ozdadirri/port-show/blob/main/Sources/PortRowView.swift"
click node_state "https://github.com/ozdadirri/port-show/blob/main/Sources/AppState.swift"
click node_entry "https://github.com/ozdadirri/port-show/blob/main/Sources/PortEntry.swift"
click node_scanner "https://github.com/ozdadirri/port-show/blob/main/Sources/PortScanner.swift"
click node_favorites "https://github.com/ozdadirri/port-show/blob/main/Sources/FavoritesStore.swift"
click node_preferences "https://github.com/ozdadirri/port-show/blob/main/Sources/AppState.swift"
click node_login "https://github.com/ozdadirri/port-show/blob/main/Sources/LoginItemManager.swift"
click node_notifications "https://github.com/ozdadirri/port-show/blob/main/Sources/NotificationManager.swift"
click node_workspace "https://github.com/ozdadirri/port-show/blob/main/Sources/NSWorkspaceHelper.swift"

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_menu,node_popover,node_row,node_user,node_launchagent,node_browser toneBlue
class node_entry,node_scanner toneAmber
class node_state,node_favorites,node_preferences toneMint
class node_login,node_notifications,node_workspace toneRose
class node_lsof,node_launchctl,node_notification_service,node_finder,node_pasteboard,node_process toneIndigo
```

## Components

### App and UI

- [Menu-bar app](https://github.com/ozdadirri/port-show/blob/main/Sources/main.swift): `Sources/main.swift`
- [Port popover](https://github.com/ozdadirri/port-show/blob/main/Sources/PopoverViewController.swift): `Sources/PopoverViewController.swift`
- [Port row actions](https://github.com/ozdadirri/port-show/blob/main/Sources/PortRowView.swift): `Sources/PortRowView.swift`

### Port discovery

- [Port entry model](https://github.com/ozdadirri/port-show/blob/main/Sources/PortEntry.swift): `Sources/PortEntry.swift`
- [Port scanner](https://github.com/ozdadirri/port-show/blob/main/Sources/PortScanner.swift): `Sources/PortScanner.swift`

### State and preferences

- [App state](https://github.com/ozdadirri/port-show/blob/main/Sources/AppState.swift): `Sources/AppState.swift`
- [Pinned ports](https://github.com/ozdadirri/port-show/blob/main/Sources/FavoritesStore.swift): `Sources/FavoritesStore.swift`
- [App preferences](https://github.com/ozdadirri/port-show/blob/main/Sources/AppState.swift): `Sources/AppState.swift`

### macOS integrations

- [Launch-at-login](https://github.com/ozdadirri/port-show/blob/main/Sources/LoginItemManager.swift): `Sources/LoginItemManager.swift`
- [Port notifications](https://github.com/ozdadirri/port-show/blob/main/Sources/NotificationManager.swift): `Sources/NotificationManager.swift`
- [Workspace actions](https://github.com/ozdadirri/port-show/blob/main/Sources/NSWorkspaceHelper.swift): `Sources/NSWorkspaceHelper.swift`

### Other components

- **Mac user**
- **Socket/process data**
- **User LaunchAgent**
- **launchctl**
- **macOS notifications**
- **Default browser**
- **Finder**
- **Pasteboard**
- **Owned process**

## Connections

- Mac user → Menu-bar app: opens popover (evidence: `Sources/main.swift`)
- Menu-bar app → App state: starts and refreshes (evidence: `Sources/main.swift`)
- Menu-bar app → Port popover: shows (evidence: `Sources/main.swift`)
- Port popover → App state: reads settings and entries (evidence: `Sources/PopoverViewController.swift`)
- Port popover → Port row actions: creates and configures (evidence: `Sources/PopoverViewController.swift`)
- Port row actions → App state: invokes row actions (evidence: `Sources/PopoverViewController.swift`)
- App state → Port scanner: requests scan (evidence: `Sources/AppState.swift`)
- Port scanner → Socket/process data: reads socket data (evidence: `Sources/PortScanner.swift`)
- Port scanner → Port entry model: produces entries (evidence: `Sources/PortScanner.swift`)
- App state → Port entry model: filters and groups (evidence: `Sources/AppState.swift`)
- App state → Pinned ports: checks and toggles pins (evidence: `Sources/AppState.swift`)
- Pinned ports → App preferences: persists favorites (evidence: `Sources/FavoritesStore.swift`)
- App state → App preferences: persists settings (evidence: `Sources/AppState.swift`)
- App state → Launch-at-login: toggles login launch (evidence: `Sources/AppState.swift`)
- Launch-at-login → User LaunchAgent: writes or removes (evidence: `Sources/LoginItemManager.swift`)
- Launch-at-login → launchctl: loads or unloads (evidence: `Sources/LoginItemManager.swift`)
- App state → Port notifications: requests and sends (evidence: `Sources/AppState.swift`)
- Port notifications → macOS notifications: posts alerts (evidence: `Sources/NotificationManager.swift`)
- App state → Workspace actions: opens and copies (evidence: `Sources/AppState.swift`)
- Workspace actions → Default browser: opens port URL (evidence: `Sources/NSWorkspaceHelper.swift`)
- Workspace actions → Pasteboard: copies text (evidence: `Sources/NSWorkspaceHelper.swift`)
- App state → Port scanner: kills or reveals process (evidence: `Sources/AppState.swift`)
- Port scanner → Finder: reveals start file (evidence: `README.md`)
- Port scanner → Owned process: sends SIGTERM (evidence: `README.md`)