# thedhanawada/sf-monitor architecture

> Architecture diagram of the GitHub repository thedhanawada/sf-monitor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thedhanawada/sf-monitor
- Repository: https://github.com/thedhanawada/sf-monitor

## Overview

##### Project Type and Purpose
- This is an open-source, multi-package Node.js monorepo delivering a Salesforce observability platform.
- It consists of:
- A CLI tool (“packages/cli”) for terminal-based monitoring and deployment tracking
- A VS Code extension (“packages/vscode”) providing UI components (TreeView, Webviews, Status Bar)
- A shared core library (“packages/shared”) containing all monitoring and authentication logic

##### File Structure Highlights
- Root package.json likely configures npm workspaces for three child packages.
- packages/shared:
- Core modules: sfauth.js, monitor.js, deploymentMonitor.js, alerts.js
- packages/cli:
- Bin script (sf-monitor.js) invokes shared logic
- CLI-specific glue: cliMonitor.js, cliAlerts.js, config.js
- packages/vscode:
- extension.js as entry point to VS Code Extension Host
- UI modules: limitsTreeProvider.js, deploymentMonitorPanel.js, notificationManager.js, statusBarManager.js
- Webpack config to build dist/*.vsix

##### Key Architectural Concepts (from README)
- Core Monitoring
- Poll Salesforce Limits API via shared monitor module
- Authenticate via SF CLI (child process “sf org display --json”)
- Emit events on threshold breaches
- Deployment Tracking
- Wrap SF CLI commands in a child process to intercept deployments
- Poll Metadata API for real-time status, compute deltas
- VS Code Integration
- Extension Host communicates with Webview panels via message passing
- TreeView provider surfaces live metric updates

a. Main Components
- CLI Application
- VS Code Extension (Extension Host, Webview UI)
- Shared Core Library (Monitoring, Auth, Alerts, Deployment Monitor)
- Salesforce CLI (external process)
- Salesforce Org & APIs (Limits API, Metadata API)
b. Interactions and Data Flow
- CLI/VS Code → invoke shared sfauth to retrieve access tokens from SF CLI
- Shared monitor/deploymentMonitor modules → call Salesforce REST APIs
- Shared modules emit Node.js EventEmitter events → consumed by CLI console output or VS Code UI
- Deployment tracking wraps SF CLI commands, streams output back through shared event bus
c. Architectural Patterns and Principles
- Monorepo with clear separation of concerns (UI vs. business logic vs. external integration)
- Event‐driven core powered by EventEmitter
- Adapter pattern for SF CLI integration (child process wrapper)
- Observer pattern for real-time updates to UI (listeners in CLI and Extension Host)
d. Technologies & Frameworks
- Node.js 18+, npm workspaces
- jsforce or direct REST calls for Salesforce Limits API / Metadata API
- Salesforce CLI (sf or sfdx)
- VS Code Extension API (TreeView, Webview, StatusBar)
- Webpack for VS Code packaging

##### Essential Elements
- Arrowheads for data flow direction
- Notes on authentication flow (SF CLI → token → shared sfauth)
- Event bus between shared core and UI layers

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% UI Layer
  subgraph "UI Layer"
    direction TB
    CLI["CLI Tool"]:::ui
    VSCode["VS Code Extension Host"]:::ui
  end

  %% CLI internals
  subgraph "CLI Application (packages/cli)" 
    direction TB
    CliBin["sf-monitor.js"]:::ui
    CliMonitor["cliMonitor.js"]:::ui
    CliAlerts["cliAlerts.js"]:::ui
    CliConfig["config.js"]:::ui
    CliSfauth["sfauth.js"]:::ui
    CliMonShared["monitor.js"]:::ui
  end

  CLI -->|invokes| CliBin
  CliBin -->|requires| CliMonitor
  CliBin -->|requires| CliAlerts
  CliBin -->|requires| CliConfig
  CliBin -->|calls sfauth| CliSfauth
  CliBin -->|calls monitor| CliMonShared

  %% VS Code Extension internals
  subgraph "VS Code Extension (packages/vscode)"
    direction TB
    ExtEntry["extension.js"]:::ui
    LimitsTree["limitsTreeProvider.js"]:::ui
    DeployPanel["deploymentMonitorPanel.js"]:::ui
    Notifier["notificationManager.js"]:::ui
    StatusBar["statusBarManager.js"]:::ui
    WebpackCfg["webpack.config.js"]:::integr
    VscodeIgnore[".vscodeignore"]:::integr
  end

  VSCode -->|loads| ExtEntry
  ExtEntry -->|registers| LimitsTree
  ExtEntry -->|opens| DeployPanel
  ExtEntry -->|uses| Notifier
  ExtEntry -->|updates| StatusBar

  %% Core Layer
  subgraph "Shared Core Library (packages/shared)" 
    direction TB
    CoreIndex["index.js"]:::core
    Auth["sfauth.js"]:::core
    Monitor["monitor.js"]:::core
    DeployCore["deploymentMonitor.js"]:::core
    Alerts["alerts.js"]:::core
    EventBus["EventEmitter"]:::core
  end

  %% Integration Layer
  subgraph "Integration Layer"
    direction TB
    SFCLI["SF CLI (child_process)"]:::integr
    SFAPIs["Salesforce REST APIs"]:::integr
  end

  %% Salesforce Org external
  SFAPIs -->|HTTP REST /limits| Monitor
  SFAPIs -->|HTTP REST /metadata| DeployCore
  SFCLI -->|exec sf org display| Auth
  SFCLI -->|wrap deploy commands| DeployCore

  %% Data flows
  CliSfauth -->|get token| SFCLI
  CliMonitor -->|poll limits| Monitor
  CliMonShared -->|emit events| EventBus
  Monitor -->|emit breach| EventBus
  DeployCore -->|emit update| EventBus

  ExtEntry -->|calls| Auth
  LimitsTree -->|subscribes| EventBus
  DeployPanel -->|subscribes| EventBus
  Notifier -->|subscribes| EventBus
  StatusBar -->|subscribes| EventBus

  %% UI receives events
  EventBus -->|updates CLI| CLI
  EventBus -->|updates VSCode| VSCode

  %% Module connections to core
  CliSfauth -->|imports| Auth
  CliMonShared -->|imports| Monitor
  CliAlerts -->|imports| Alerts
  CliMonitor -->|imports| Monitor
  ExtEntry -->|imports| CoreIndex
  LimitsTree -->|imports| CoreIndex
  DeployPanel -->|imports| CoreIndex
  Notifier -->|imports| CoreIndex
  StatusBar -->|imports| CoreIndex

  %% Click Events
  click CliBin "https://github.com/thedhanawada/sf-monitor/blob/master/packages/cli/bin/sf-monitor.js"
  click CliMonitor "https://github.com/thedhanawada/sf-monitor/blob/master/packages/cli/src/cliMonitor.js"
  click CliAlerts "https://github.com/thedhanawada/sf-monitor/blob/master/packages/cli/src/cliAlerts.js"
  click CliConfig "https://github.com/thedhanawada/sf-monitor/blob/master/packages/cli/src/config.js"
  click CliSfauth "https://github.com/thedhanawada/sf-monitor/blob/master/packages/cli/src/sfauth.js"
  click CliMonShared "https://github.com/thedhanawada/sf-monitor/blob/master/packages/cli/src/monitor.js"
  click ExtEntry "https://github.com/thedhanawada/sf-monitor/blob/master/packages/vscode/src/extension.js"
  click LimitsTree "https://github.com/thedhanawada/sf-monitor/blob/master/packages/vscode/src/limitsTreeProvider.js"
  click DeployPanel "https://github.com/thedhanawada/sf-monitor/blob/master/packages/vscode/src/deploymentMonitorPanel.js"
  click Notifier "https://github.com/thedhanawada/sf-monitor/blob/master/packages/vscode/src/notificationManager.js"
  click StatusBar "https://github.com/thedhanawada/sf-monitor/blob/master/packages/vscode/src/statusBarManager.js"
  click WebpackCfg "https://github.com/thedhanawada/sf-monitor/blob/master/packages/vscode/webpack.config.js"
  click VscodeIgnore "https://github.com/thedhanawada/sf-monitor/blob/master/packages/vscode/.vscodeignore"
  click CoreIndex "https://github.com/thedhanawada/sf-monitor/blob/master/packages/shared/src/index.js"
  click Auth "https://github.com/thedhanawada/sf-monitor/blob/master/packages/shared/src/sfauth.js"
  click Monitor "https://github.com/thedhanawada/sf-monitor/blob/master/packages/shared/src/monitor.js"
  click DeployCore "https://github.com/thedhanawada/sf-monitor/blob/master/packages/shared/src/deploymentMonitor.js"
  click Alerts "https://github.com/thedhanawada/sf-monitor/blob/master/packages/shared/src/alerts.js"

  %% Styles
  classDef ui fill:#e0ffe0,stroke:#2f6627,stroke-width:1px
  classDef core fill:#e0f0ff,stroke:#1f3f7a,stroke-width:1px
  classDef integr fill:#fff0e0,stroke:#aa5500,stroke-width:1px
```
