# ne0ekspert/webnowplaying-vscode architecture

> Architecture diagram of the GitHub repository ne0ekspert/webnowplaying-vscode, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ne0ekspert/webnowplaying-vscode
- Repository: https://github.com/ne0ekspert/webnowplaying-vscode

## Overview

##### Project Type and Purpose
- This is a VSCode editor extension (full‐stack isn’t applicable here).
- Its sole purpose is to surface “Now Playing” metadata (artist, title, album, etc.) inside VSCode using data published by the companion WebNowPlaying-Redux browser extension.

##### File Structure
Top‐level artifacts:
- package.json, tsconfig.json, .vscodeignore – build and packaging config for a VSCode extension
- src/extension.ts – entry point: activation(), sets up the extension host
- src/commands.ts – implements user‐invokable VSCode commands
- src/webview.ts – manages an optional custom Webview panel (e.g., lyrics display)
- src/WNPRedux.ts – handles WebSocket client connection to the browser extension
- src/WNPCallbacks.ts – defines callbacks to process incoming track data
- src/test/… – unit/integration tests
Other files (README.md, CHANGELOG.md, media/style.css) are documentation or assets.

##### Pull Architecture Hints from README
- Extension Settings define host/port for the WebSocket server.
- Requires “WebNowPlaying-Redux” Browser Extension (this is an external component publishing music info).
- Webview controllers added in v0.0.4 suggest a UI panel beyond the status bar.

##### Main Components
a. VSCode Extension Host
– Activation module (extension.ts)
– Configuration subsystem (reads settings: host, port, format strings)
– Command registry (commands.ts)
– StatusBarItem updater (in extension.ts + WNPCallbacks)
b. WebSocket Client (WNPRedux.ts)
– Connects to external Browser Extension on configured host/port
– Emits incoming payloads (track info, playback state)
c. Callbacks Handler (WNPCallbacks.ts)
– Maps raw WebSocket messages → formatted status bar updates / webview messages
d. Webview Panel (webview.ts + media/style.css)
– Optional UI (lyrics LRC display, controls)
– Communicates with extension host via the VSCode Webview messaging API
e. External Browser Extension (“WebNowPlaying-Redux”)
– Publishes now‐playing data over WebSocket

##### Relationships & Data Flows
1) User starts VSCode → extension activates (extension.ts).
2) extension.ts reads configuration → instantiates WNPRedux (WebSocket client).
3) WNPRedux establishes WebSocket → Browser Extension.
4) Incoming messages → WNPCallbacks → extension.ts updates StatusBarItem or forwards to Webview.
5) User clicks StatusBarItem → commands.ts handles click, possibly toggles Webview or runs other commands.
6) Webview (if opened) → uses postMessage → triggers handlers in extension.ts/webview.ts.
7) Tests (in src/test/) simulate calls to commands, callbacks, and WebSocket events.

##### Architectural Patterns & Principles
- Event‐driven: WebSocket events trigger UI updates.
- Modular separation:
– Networking layer (WNPRedux)
– Callback/logic layer (WNPCallbacks)
– UI layer (status bar + optional Webview)
- Configuration‐driven: host/port and format strings are fully user‐configurable.
- VSCode API usage: activation lifecycle, status bar items, Webviews, commands.

##### Technologies & Frameworks
- TypeScript for all source code
- VSCode Extension API (vscode module)
- WebSocket (built‐in or ws library)
- Optional Redux concepts in the browser extension (outside this project)
- Mocha + VSCode Test Runner for tests (runTest.ts)

##### Customizing for This VSCode Extension
– Emphasize the bidirectional flow between the extension host and Webview (if used).
– Highlight configuration reading in activation (host/port, format strings).
– Show where styling (media/style.css) is applied within the Webview.
– Include a test stub area to indicate how the test suite simulates messages.

##### Essential Elements Checklist
– Components: Activation, Networking, Callbacks, Status Bar, Commands, Webview
– External Service: Browser Extension (WebNowPlaying-Redux)
– Clear labels and annotations for message types

## Diagram (Mermaid)

```mermaid
graph TB

subgraph "Build & Packaging Configuration"
  Pkg["package.json"]:::core
  Ts["tsconfig.json"]:::core
  VSI[".vscodeignore"]:::core
end

subgraph "VSCode Extension Host"
  Activation["Activation & Configuration"]:::core
  Commands["Command Registry"]:::core
  StatusExt["StatusBarItem Updater (Activation)"]:::core
  StatusCB["StatusBarItem Updater (Callbacks)"]:::core
  WebviewCtrl["Webview Panel Controller"]:::ui
end

subgraph "Networking Layer"
  WSClient["WNPRedux: WebSocket Client"]:::nw
end

External["WebNowPlaying-Redux (Browser Extension)"]:::ext

Style["Webview Stylesheet"]:::ui

subgraph "Tests"
  TestRun["runTest.ts"]:::test
  TestSuite1["extension.test.ts"]:::test
  TestSuite2["index.ts"]:::test
end

Activation -->|"reads host/port config"| WSClient
Activation -->|"register commands"| Commands
Activation -->|"initial status setup"| StatusExt
WSClient -->|"trackInfo payload"| Callbacks
Callbacks -->|"update status"| StatusCB
Callbacks -->|"forward message"| WebviewCtrl
WSClient <-->|"WebSocket"| External
Commands -->|"click event"| WebviewCtrl
WebviewCtrl -->|"apply style.css"| Style

TestRun --> Commands
TestRun --> Callbacks
TestRun --> WSClient
TestSuite1 --> Commands
TestSuite1 --> Callbacks
TestSuite1 --> WSClient
TestSuite2 --> Commands
TestSuite2 --> Callbacks
TestSuite2 --> WSClient

click Activation "https://github.com/ne0ekspert/webnowplaying-vscode/blob/main/src/extension.ts"
click Commands "https://github.com/ne0ekspert/webnowplaying-vscode/blob/main/src/commands.ts"
click StatusExt "https://github.com/ne0ekspert/webnowplaying-vscode/blob/main/src/extension.ts"
click StatusCB "https://github.com/ne0ekspert/webnowplaying-vscode/blob/main/src/WNPCallbacks.ts"
click WSClient "https://github.com/ne0ekspert/webnowplaying-vscode/blob/main/src/WNPRedux.ts"
click Callbacks "https://github.com/ne0ekspert/webnowplaying-vscode/blob/main/src/WNPCallbacks.ts"
click WebviewCtrl "https://github.com/ne0ekspert/webnowplaying-vscode/blob/main/src/webview.ts"
click Style "https://github.com/ne0ekspert/webnowplaying-vscode/blob/main/media/style.css"
click TestRun "https://github.com/ne0ekspert/webnowplaying-vscode/blob/main/src/test/runTest.ts"
click TestSuite1 "https://github.com/ne0ekspert/webnowplaying-vscode/blob/main/src/test/suite/extension.test.ts"
click TestSuite2 "https://github.com/ne0ekspert/webnowplaying-vscode/blob/main/src/test/suite/index.ts"
click Pkg "https://github.com/ne0ekspert/webnowplaying-vscode/blob/main/package.json"
click Ts "https://github.com/ne0ekspert/webnowplaying-vscode/blob/main/tsconfig.json"
click VSI "https://github.com/ne0ekspert/webnowplaying-vscode/blob/main/.vscodeignore"

classDef core fill:#87CEFA,stroke:#4682B4,color:#000
classDef nw fill:#98FB98,stroke:#228B22,color:#000
classDef ext fill:#D3D3D3,stroke:#A9A9A9,color:#000
classDef ui fill:#FFFACD,stroke:#FFD700,color:#000
classDef test fill:#FFC0CB,stroke:#FF69B4,color:#000
```
