# accenture/dx-mate architecture

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

- Interactive diagram: https://gitdiagram.com/accenture/dx-mate
- Repository: https://github.com/accenture/dx-mate

## Overview

##### Project type and purpose
- This is a Visual Studio Code extension (“DX-Mate”) that streamlines Salesforce DX (SFDX) development.
- It registers a set of commands in VS Code (via the extension host) to create/fetch scratch orgs, chain org setup tasks, import/export data, deploy metadata, and automate recurring Salesforce CLI workflows.

##### File structure
- Top‐level manifest/config files: package.json (extension metadata and command registrations), tsconfig.json, .eslintrc.json
- src/extension.ts: entry point that activates the extension and registers commands/providers
- src/commands/: individual command handlers (commands.ts, dependencyCommands.ts, explorerCommands.ts, packageCommands.ts, userCommands.ts)
- src/RunningTaskProvider.ts: VS Code tree‐view provider to surface long-running tasks in the UI
- src/legacyHandlers/: older/deprecated command implementations (e.g., depLegacy.ts)
- src/models.ts, src/utils.ts, src/workspace.ts: shared data structures, helper functions, workspace‐level abstractions
- src/graphics/: static assets (screenshots/GIFs) used in documentation
- src/test/: test harness and unit/integration tests

##### README for additional insights
- Lists required external dependencies: Salesforce CLI, @salesforce/cli, sfpowerkit, sfdmu, @dxatscale/sfpowerscripts
- Describes the chained workflow triggered by “Create scratch org” command
- Shows UI screens (extension tree view, settings pane)

##### Main components and interactions (
A. VS Code UI Layer
- Command Palette & GUI contribution points (buttons, tree views)
- Settings UI (extension settings contributed via package.json)
B. VS Code Extension Host
- Activation lifecycle (extension.ts)
- Command registrar (registerCommand API)
- RunningTaskProvider (tree data provider)
C. Core Modules (TypeScript code)
- Command modules under src/commands
- Utility modules (utils.ts, workspace.ts, models.ts)
- Legacy handlers (for backward compatibility)
D. External CLI Interface
- Node child_process calls to Salesforce CLI (sfdx) and installed plugins (sfpowerkit, sfdmu, sfpowerscripts)
E. Salesforce Remote Services
- Scratch org pool (DebHub/unlocked package)
- Scratch orgs on Salesforce servers
- Metadata API endpoints
F. File System / Workspace
- Local project metadata, unpackagable folder, dummy data folder, package directories

##### Relationships and dataflow
1. User invokes a command (via Palette or tree) in VS Code UI.
2. Extension Host receives the event, routes to the appropriate command handler module.
3. Handler uses workspace.ts to resolve project paths, models.ts to structure parameters.
4. Handler spawns child_process calls to sfdx CLI or plugin binaries (e.g., “sfdx force:org:create …”).
5. CLI communicates with Salesforce remote services, pools scratch orgs, or performs metadata operations.
6. Handler parses CLI output, updates tree view via RunningTaskProvider, shows notifications in VS Code UI.
7. Settings (dummy data location, permission sets, dependency keys) are read via vscode.workspace.getConfiguration.

##### Architectural patterns / design principles
- Modular command pattern: each operation lives in its own module under src/commands
- Provider pattern: RunningTaskProvider implements VS Code TreeDataProvider interface
- Separation of concerns: utils.ts and workspace.ts abstract file system and CLI invocation logic
- Backwards compatibility: legacyHandlers encapsulate deprecated flows without cluttering new code

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers and Components
    subgraph "VS Code Editor / UI" 
        direction TB
        VSCodeUI["Command Palette & Tree View"]:::ui
        SettingsUI["Settings UI"]:::ui
    end

    subgraph "Extension Host Process" 
        direction TB
        ExtensionTS["Extension Activation & Command Registrar"]:::core
        RunningProvider["RunningTaskProvider (Tree View)"]:::core
        subgraph "Core Modules"
            direction TB
            Utils["Shared Utilities"]:::core
            Workspace["Workspace & FS Abstractions"]:::core
            Models["Data Models & Interfaces"]:::core
            subgraph "Commands"
                direction TB
                CommandsGen["General Commands"]:::core
                CommandsDep["Dependency Commands"]:::core
                CommandsExp["Explorer Commands"]:::core
                CommandsPkg["Package Commands"]:::core
                CommandsUser["User Commands"]:::core
            end
            Legacy["Legacy Command Handlers"]:::core
        end
    end

    NodeChild["Node Child Process\n(child_process)"]:::cli
    CLIPlugins["Salesforce CLI + Plugins\n(sfdx, sfpowerkit,\n sfdmu, sfpowerscripts)"]:::cli

    subgraph "Salesforce Remote Services"
        direction TB
        ScratchPool["Scratch Org Pool & Metadata APIs"]:::service
    end

    WorkspaceFS["Local Workspace File System\n(metadata, dummy data)"]:::fs

    subgraph "Configurations & Manifests"
        direction TB
        PackageJSON["package.json"]:::core
        TSConfig["tsconfig.json"]:::core
        ESLint[".eslintrc.json"]:::core
    end

    subgraph "Graphics & Tests"
        direction TB
        Graphics["Static Graphics Assets"]:::fs
        RunTest["Test Runner Entry Point"]:::test
        UnitTests["Unit/Integration Tests"]:::test
    end

    %% Connections
    VSCodeUI -->|trigger command| ExtensionTS
    SettingsUI -->|reads settings| ExtensionTS

    ExtensionTS -->|registers commands| CommandsGen
    ExtensionTS --> RunningProvider

    CommandsGen -->|uses| Utils
    CommandsGen -->|uses| Workspace
    CommandsGen -->|uses| Models
    CommandsDep -->|uses| Utils
    CommandsExp -->|uses| Utils
    CommandsPkg -->|uses| Workspace
    CommandsUser -->|uses| Workspace
    Legacy -->|fallback flows| CommandsGen

    CommandsGen -->|spawn sfdx CLI| NodeChild
    CommandsDep -->|spawn CLI| NodeChild
    CommandsExp -->|spawn CLI| NodeChild
    CommandsPkg -->|spawn CLI| NodeChild
    CommandsUser -->|spawn CLI| NodeChild
    Legacy -->|spawn CLI| NodeChild

    NodeChild --> CLIPlugins
    CLIPlugins -->|API calls| ScratchPool
    ScratchPool -->|response| CLIPlugins
    CLIPlugins --> NodeChild
    NodeChild -->|CLI output| RunningProvider
    RunningProvider -->|update UI| VSCodeUI

    CommandsGen -->|read/write| WorkspaceFS
    CommandsPkg -->|read/write| WorkspaceFS
    CommandsUser -->|read/write| WorkspaceFS

    %% Configurations & Graphics & Tests links
    ExtensionTS --> PackageJSON
    ExtensionTS --> TSConfig
    ExtensionTS --> ESLint
    ExtensionTS --> Graphics
    RunTest --> CommandsGen
    RunTest --> ExtensionTS
    UnitTests --> RunTest

    %% Click Events
    click PackageJSON "https://github.com/accenture/dx-mate/blob/main/package.json"
    click TSConfig "https://github.com/accenture/dx-mate/blob/main/tsconfig.json"
    click ESLint "https://github.com/accenture/dx-mate/blob/main/.eslintrc.json"
    click ExtensionTS "https://github.com/accenture/dx-mate/blob/main/src/extension.ts"
    click RunningProvider "https://github.com/accenture/dx-mate/blob/main/src/RunningTaskProvider.ts"
    click CommandsGen "https://github.com/accenture/dx-mate/blob/main/src/commands/commands.ts"
    click CommandsDep "https://github.com/accenture/dx-mate/blob/main/src/commands/dependencyCommands.ts"
    click CommandsExp "https://github.com/accenture/dx-mate/blob/main/src/commands/explorerCommands.ts"
    click CommandsPkg "https://github.com/accenture/dx-mate/blob/main/src/commands/packageCommands.ts"
    click CommandsUser "https://github.com/accenture/dx-mate/blob/main/src/commands/userCommands.ts"
    click Legacy "https://github.com/accenture/dx-mate/blob/main/src/legacyHandlers/depLegacy.ts"
    click Utils "https://github.com/accenture/dx-mate/blob/main/src/utils.ts"
    click Workspace "https://github.com/accenture/dx-mate/blob/main/src/workspace.ts"
    click Models "https://github.com/accenture/dx-mate/blob/main/src/models.ts"
    click Graphics "https://github.com/accenture/dx-mate/tree/main/src/graphics"
    click RunTest "https://github.com/accenture/dx-mate/blob/main/src/test/runTest.ts"
    click UnitTests "https://github.com/accenture/dx-mate/blob/main/src/test/suite/extension.test.ts"
    click UnitTests "https://github.com/accenture/dx-mate/blob/main/src/test/suite/index.ts"

    %% Styles
    classDef ui fill:#BBE1FA,stroke:#0B3C5D,color:#000;
    classDef core fill:#A1EFD3,stroke:#0B9F6E,color:#000;
    classDef cli fill:#FFD662,stroke:#E69A02,color:#000;
    classDef service fill:#FFADAD,stroke:#D6001C,color:#000;
    classDef fs fill:#E0E0E0,stroke:#888,color:#000;
    classDef test fill:#D3C0EB,stroke:#7D3C98,color:#000;
```
