# george3447/docker-run architecture

> Architecture diagram of the GitHub repository george3447/docker-run, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/george3447/docker-run
- Repository: https://github.com/george3447/docker-run

## Overview

##### Project Type and Purpose
- This is a Visual Studio Code Extension, named “Docker Run,” written in TypeScript.
- Purpose: Automatically start and stop Docker containers associated with the current workspace, expose state in the VS Code status bar, and provide manual commands and configuration via settings or a `.dockerrc` file.

##### File Structure Analysis
- Top-level: configuration files (`.eslintrc.json`, `tsconfig.json`, `webpack.config.js`, `.vscodeignore`), CI/CD workflows, `package.json`.
- `src/extension.ts`: entry point that hooks into VS Code activation events and registers commands.
- `src/commands/`: command handlers (`start.ts`, `stop.ts`, `add.ts`, `remove.ts`, etc.) using the Command pattern.
- `src/common/`: shared utilities and services (configuration loader, constants, error models, status-bar manager).
- `src/core/`: core domain logic—operations (start, stop, stop-non-related), domain models, and extension variables.
- `src/test/`: unit and integration tests organized by feature.

##### README Insights
- Activation triggers an initial configuration wizard on first open.
- Exposes six main commands and live status in the status bar.
- Integration point: Docker Engine (via underlying Docker API/CLI).
- Configuration sources: VS Code settings and a workspace‐local `.dockerrc` file.

a. Main Components
- VSCode Extension Host
- Extension Activation Module (`extension.ts`)
- Command Registry & Handlers (`src/commands`)
- Configuration Service (`src/common/config.ts`)
- Core Operations (Start, Stop, Stop-Non-Related in `src/core/operations`)
- Docker Engine Client (Dockerode or CLI wrapper)
- VSCode UI (Status Bar, Notifications)
- Workspace Configuration (`.dockerrc` / VS Code settings)

b. Relationships & Data Flows
1. VSCode Extension Host loads the bundled extension.
2. On activation event, `extension.ts` invokes the Configuration Service.
3. Configuration Service reads `.dockerrc` and VS Code settings.
4. Depending on workspace change or user command:
– Command Registry forwards to the appropriate command handler.
– Handler invokes a Core Operation (e.g., StartOperation).
– Core Operation calls the Docker Engine Client to start/stop containers.
5. Operation result is fed back to the Status-Bar Manager, updating UI.
6. Errors propagate through the common error model to VS Code notifications.

c. Architectural Patterns & Principles
- Command Pattern: decouples VSCode commands from core logic.
- Layered Architecture:
- Presentation (Status Bar, Notifications)
- Application (Command handlers, Activation)
- Domain (Core Operations, Models)
- Infrastructure (Configuration loader, Docker Client)
- Single Responsibility: Each module (commands, config, operations) has a focused role.

d. Key Technologies
- TypeScript & Node.js
- VS Code Extension API
- Webpack bundling
- Docker Engine API/CLI wrapper
- Mocha & Chai for testing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% VSCode Host and Activation
    VSCode["VSCode Extension Host"]:::vscodeUI
    Activation["extension.ts"]:::application
    click Activation "https://github.com/george3447/docker-run/blob/master/src/extension.ts"
    VSCode --> Activation

    %% Configuration Layer (Infrastructure)
    subgraph "Configuration Service" 
        direction TB
        ConfigService["ConfigService"]:::infra
        click ConfigService "https://github.com/george3447/docker-run/blob/master/src/common/config.ts"
        SettingsLoader["settings.ts"]:::infra
        click SettingsLoader "https://github.com/george3447/docker-run/blob/master/src/common/settings.ts"
        Dockerrc[".dockerrc"]:::infra
        click Dockerrc "https://github.com/george3447/docker-run/blob/master/src/test/workspace-v1/.dockerrc"
    end
    Activation --> ConfigService
    ConfigService --> SettingsLoader
    ConfigService --> Dockerrc

    %% Application Layer: Command Handlers
    subgraph "Command Handlers" 
        direction TB
        AddCmd["add.ts"]:::application
        click AddCmd "https://github.com/george3447/docker-run/blob/master/src/commands/add.ts"
        RemoveCmd["remove.ts"]:::application
        click RemoveCmd "https://github.com/george3447/docker-run/blob/master/src/commands/remove.ts"
        ShowCmds["show-commands.ts"]:::application
        click ShowCmds "https://github.com/george3447/docker-run/blob/master/src/commands/show-commands.ts"
        StartCmd["start.ts"]:::application
        click StartCmd "https://github.com/george3447/docker-run/blob/master/src/commands/start.ts"
        StartAllCmd["start-all.ts"]:::application
        click StartAllCmd "https://github.com/george3447/docker-run/blob/master/src/commands/start-all.ts"
        StopCmd["stop.ts"]:::application
        click StopCmd "https://github.com/george3447/docker-run/blob/master/src/commands/stop.ts"
        StopAllCmd["stop-all.ts"]:::application
        click StopAllCmd "https://github.com/george3447/docker-run/blob/master/src/commands/stop-all.ts"
        StopNonRelCmd["stop-non-related.ts"]:::application
        click StopNonRelCmd "https://github.com/george3447/docker-run/blob/master/src/commands/stop-non-related.ts"
    end
    Activation --> AddCmd
    Activation --> RemoveCmd
    Activation --> ShowCmds
    Activation --> StartCmd
    Activation --> StartAllCmd
    Activation --> StopCmd
    Activation --> StopAllCmd
    Activation --> StopNonRelCmd

    %% Domain Core Entry
    CoreEntry["core.ts"]:::domain
    click CoreEntry "https://github.com/george3447/docker-run/blob/master/src/core/core.ts"
    ExtVars["ext-variables.ts"]:::domain
    click ExtVars "https://github.com/george3447/docker-run/blob/master/src/core/ext-variables.ts"
    AddCmd --> CoreEntry
    RemoveCmd --> CoreEntry
    ShowCmds --> CoreEntry
    StartCmd --> CoreEntry
    StartAllCmd --> CoreEntry
    StopCmd --> CoreEntry
    StopAllCmd --> CoreEntry
    StopNonRelCmd --> CoreEntry
    CoreEntry --> ExtVars

    %% Domain Operations
    subgraph "Core Operations" 
        direction TB
        OpsIndex["index.ts"]:::domain
        click OpsIndex "https://github.com/george3447/docker-run/blob/master/src/core/operations/index.ts"
        Operation["operation.ts"]:::domain
        click Operation "https://github.com/george3447/docker-run/blob/master/src/core/operations/operation.ts"
        StartOp["start-operation.ts"]:::domain
        click StartOp "https://github.com/george3447/docker-run/blob/master/src/core/operations/start-operation.ts"
        StopOp["stop-operation.ts"]:::domain
        click StopOp "https://github.com/george3447/docker-run/blob/master/src/core/operations/stop-operation.ts"
        StopNonRelOp["stop-non-related-operation.ts"]:::domain
        click StopNonRelOp "https://github.com/george3447/docker-run/blob/master/src/core/operations/stop-non-related-operation.ts"
    end
    ExtVars --> OpsIndex
    OpsIndex --> Operation
    Operation --> StartOp
    Operation --> StopOp
    Operation --> StopNonRelOp

    %% Infrastructure Utilities
    subgraph "Infrastructure & Utilities"
        direction TB
        FileIO["file.ts"]:::infra
        click FileIO "https://github.com/george3447/docker-run/blob/master/src/common/file.ts"
        ListUtil["list.ts"]:::infra
        click ListUtil "https://github.com/george3447/docker-run/blob/master/src/common/list.ts"
        ErrorModel["error.ts"]:::infra
        click ErrorModel "https://github.com/george3447/docker-run/blob/master/src/common/error.ts"
        Messages["messages.ts"]:::infra
        click Messages "https://github.com/george3447/docker-run/blob/master/src/common/messages.ts"
        Constants["constants.ts"]:::infra
        click Constants "https://github.com/george3447/docker-run/blob/master/src/common/constants.ts"
        Enums["enums.ts"]:::infra
        click Enums "https://github.com/george3447/docker-run/blob/master/src/common/enums.ts"
        Models["models.ts"]:::infra
        click Models "https://github.com/george3447/docker-run/blob/master/src/common/models.ts"
    end
    ConfigService --> FileIO
    Operation --> FileIO
    Operation --> ListUtil
    Operation --> ErrorModel
    Operation --> Messages
    Operation --> Constants
    Operation --> Enums
    CoreEntry --> Models

    %% Docker Client and Engine
    DockerClient["Docker Client"]:::infra
    DockerClient --> DockerEngine["Docker Engine"]:::external
    StartOp --> DockerClient
    StopOp --> DockerClient
    StopNonRelOp --> DockerClient

    %% VSCode UI: Status Bar and Notifications
    subgraph "VSCode UI" 
        direction TB
        StatusBar["status-bar.ts"]:::vscodeUI
        click StatusBar "https://github.com/george3447/docker-run/blob/master/src/common/status-bar.ts"
        Notifications["VSCode Notifications"]:::vscodeUI
    end
    StartOp --> StatusBar
    StopOp --> StatusBar
    StopNonRelOp --> StatusBar
    ErrorModel --> Notifications

    %% Styles
    classDef vscodeUI fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef application fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef domain fill:#fff3cd,stroke:#333,stroke-width:1px;
    classDef infra fill:#e2e3e5,stroke:#333,stroke-width:1px;
    classDef external fill:#f8d7da,stroke:#333,stroke-width:1px;
```
