# badie005/bdev-cli architecture

> Architecture diagram of the GitHub repository badie005/bdev-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/badie005/bdev-cli
- Repository: https://github.com/badie005/bdev-cli

## Overview

##### Project Type and Purpose
- B.DEV CLI is a Python-based command-line interface (“personal development assistant”) with a plugin architecture.
- It provides over 150 commands via 12 plugins, plus a REPL mode, custom scripts, snippets, templates, and security/configuration management.

##### High-Level Architectural Components
a. CLI Launcher
- Entry scripts: bdev.py, cli/__main__.py, cli/main.py
- Windows wrappers: .ps1 and .bat scripts for install, uninstall, direct mode, profile loading
b. Core Engine
- Configuration (cli/core/config.py)
- REPL and direct modes (cli/core/repl.py, bdev_direct.py)
- Security sandbox and MFA (cli/core/security.py)
- Command dispatch & plugin loader
c. Plugin Subsystem
- Plugin registry & context (cli/plugins/__init__.py, context.py)
- Individual plugins (docker, npm, database, git_tools, system, project, doctor, scripts, snippets, templates, todo, shell)
- Each plugin implements a set of subcommands using a common CLI API
d. Utilities
- UI helper (cli/utils/ui.py)
- Theming (cli/utils/theme.py)
- Error handling (cli/utils/errors.py)
e. Persistence & Storage
- Local file system for templates, snippets, scripts
- Configuration files / profiles loaded via add-to-profile.ps1
- Command history (likely stored under user home or project context)
f. External Integrations
- Docker daemon (via Docker SDK or CLI)
- NPM registry / node CLI
- Git executable
- Relational databases (via CLI clients or drivers)
- System shell (bash/pwsh)

##### Interactions and Data Flows
- User Input (terminal) → Launcher → Core Engine
- Core Engine → Plugin Manager → Selected Plugin
- Plugins communicate with external systems and may read/write:
- File system (templates, scripts, snippets)
- Network services (Docker, NPM, DB servers)
- Core Engine collects plugin responses and renders output via UI utils

##### Architectural Patterns and Principles
- Plugin-based architecture: decouples command implementations
- Command pattern: each CLI command is an object/module
- Separation of concerns:
- Core for plumbing (config, REPL, security)
- Plugins for domain logic
- Utils for cross-cutting concerns (UI, theme, errors)
- Extensibility: new plugins drop into cli/plugins folder
- Shell wrappers provide cross-platform entrypoints without modifying code

##### Technologies and Frameworks
- Python 3.10+
- Packaging: setup.py, pyproject.toml, requirements.txt
- Shell scripting: PowerShell (.ps1), Windows batch (.bat)
- Potential use of Click or argparse (inferred for command parsing)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User (Terminal)"]:::user

    %% Launcher Layer
    subgraph "CLI Launcher" 
        direction TB
        BDEV_py["bdev.py"]:::code
        CLI_main["cli/__main__.py"]:::code
        CLI_main2["cli/main.py"]:::code
        subgraph "Windows Wrappers & Scripts"
            direction TB
            PS1_Install["install.ps1"]:::code
            PS1_AddProfile["add-to-profile.ps1"]:::code
            PS1_Load["load-bdev.ps1"]:::code
            PS1_CopyBin["copy-to-bin.ps1"]:::code
            PS1_CreateShortcut["create-shortcut.ps1"]:::code
            PS1_Start["Start-BDEV.ps1"]:::code
            PS1_SetupSession["setup-session.ps1"]:::code
            PS1_UseNow["use-bdev-now.ps1"]:::code
            PS1_Uninstall["uninstall.ps1"]:::code
            PS1_Verify["verify-install.ps1"]:::code
            BAT_BDEV["B.DEV.bat"]:::code
            CMD_bdev["bdev.cmd"]:::code
            CMD_bdev_direct["bdev-direct.cmd"]:::code
        end
    end

    %% Core Engine
    subgraph "Core Engine" 
        direction TB
        Config["cli/core/config.py"]:::code
        REPL["cli/core/repl.py"]:::code
        Security["cli/core/security.py"]:::code
        Direct["bdev_direct.py"]:::code
    end

    %% Plugin Subsystem
    subgraph "Plugin Subsystem\n(Plugin Architecture: Discovery & Dispatch)" 
        direction TB
        SubReg["cli/plugins/__init__.py"]:::code
        Context["cli/plugins/context.py"]:::code
        Docker["cli/plugins/docker.py"]:::code
        NPM["cli/plugins/npm.py"]:::code
        Database["cli/plugins/database.py"]:::code
        GitTools["cli/plugins/git_tools.py"]:::code
        SystemP["cli/plugins/system.py"]:::code
        ProjectP["cli/plugins/project.py"]:::code
        Doctor["cli/plugins/doctor.py"]:::code
        Scripts["cli/plugins/scripts.py"]:::code
        Snippets["cli/plugins/snippets.py"]:::code
        Templates["cli/plugins/templates.py"]:::code
        Todo["cli/plugins/todo.py"]:::code
        ShellP["cli/plugins/shell.py"]:::code
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        UI["cli/utils/ui.py"]:::code
        Theme["cli/utils/theme.py"]:::code
        Errors["cli/utils/errors.py"]:::code
    end

    %% Persistence & Storage
    FS["File System\n(templates, snippets, scripts,\ncommand history)"]:::storage

    %% External Integrations
    subgraph "External Services"
        direction TB
        DockerExt["Docker Daemon"]:::external
        NPMExt["NPM Registry/CLI"]:::external
        DBExt["Databases"]:::external
        GitExt["Git Executable"]:::external
        ShellExt["System Shell"]:::external
    end

    %% Flows
    User -->|"enter command"| BDEV_py
    User -->|"enter command"| CLI_main
    BDEV_py -->|"bootstrap"| Config
    CLI_main -->|"bootstrap"| Config
    Config --> REPL
    Config --> Direct
    REPL -->|"invoke repl"| REPL
    Direct -->|"direct mode"| Direct
    REPL -->|"dispatch"| SubReg
    Direct -->|"dispatch"| SubReg
    SubReg --> Context
    Context --> Docker
    Context --> NPM
    Context --> Database
    Context --> GitTools
    Context --> SystemP
    Context --> ProjectP
    Context --> Doctor
    Context --> Scripts
    Context --> Snippets
    Context --> Templates
    Context --> Todo
    Context --> ShellP

    Config -->| uses | UI
    Config -->| uses | Theme
    Config -->| uses | Errors

    Docker -->|read/write| FS
    NPM -->|read/write| FS
    Scripts -->|read/write| FS
    Snippets -->|read/write| FS
    Templates -->|read/write| FS
    Todo -->|read/write| FS

    Docker -->|invoke| DockerExt
    NPM -->|invoke| NPMExt
    Database -->|invoke| DBExt
    GitTools -->|invoke| GitExt
    ShellP -->|invoke| ShellExt

    %% Click Events Launcher
    click BDEV_py "https://github.com/badie005/bdev-cli/blob/main/bdev.py"
    click CLI_main "https://github.com/badie005/bdev-cli/blob/main/cli/__main__.py"
    click CLI_main2 "https://github.com/badie005/bdev-cli/blob/main/cli/main.py"
    click PS1_Install "https://github.com/badie005/bdev-cli/blob/main/install.ps1"
    click PS1_AddProfile "https://github.com/badie005/bdev-cli/blob/main/add-to-profile.ps1"
    click PS1_Load "https://github.com/badie005/bdev-cli/blob/main/load-bdev.ps1"
    click PS1_CopyBin "https://github.com/badie005/bdev-cli/blob/main/copy-to-bin.ps1"
    click PS1_CreateShortcut "https://github.com/badie005/bdev-cli/blob/main/create-shortcut.ps1"
    click PS1_Start "https://github.com/badie005/bdev-cli/blob/main/Start-BDEV.ps1"
    click PS1_SetupSession "https://github.com/badie005/bdev-cli/blob/main/setup-session.ps1"
    click PS1_UseNow "https://github.com/badie005/bdev-cli/blob/main/use-bdev-now.ps1"
    click PS1_Uninstall "https://github.com/badie005/bdev-cli/blob/main/uninstall.ps1"
    click PS1_Verify "https://github.com/badie005/bdev-cli/blob/main/verify-install.ps1"
    click BAT_BDEV "https://github.com/badie005/bdev-cli/blob/main/B.DEV.bat"
    click CMD_bdev "https://github.com/badie005/bdev-cli/blob/main/bdev.cmd"
    click CMD_bdev_direct "https://github.com/badie005/bdev-cli/blob/main/bdev-direct.cmd"

    %% Click Events Core
    click Config "https://github.com/badie005/bdev-cli/blob/main/cli/core/config.py"
    click REPL "https://github.com/badie005/bdev-cli/blob/main/cli/core/repl.py"
    click Security "https://github.com/badie005/bdev-cli/blob/main/cli/core/security.py"
    click Direct "https://github.com/badie005/bdev-cli/blob/main/bdev_direct.py"

    %% Click Events Plugins
    click SubReg "https://github.com/badie005/bdev-cli/blob/main/cli/plugins/__init__.py"
    click Context "https://github.com/badie005/bdev-cli/blob/main/cli/plugins/context.py"
    click Docker "https://github.com/badie005/bdev-cli/blob/main/cli/plugins/docker.py"
    click NPM "https://github.com/badie005/bdev-cli/blob/main/cli/plugins/npm.py"
    click Database "https://github.com/badie005/bdev-cli/blob/main/cli/plugins/database.py"
    click GitTools "https://github.com/badie005/bdev-cli/blob/main/cli/plugins/git_tools.py"
    click SystemP "https://github.com/badie005/bdev-cli/blob/main/cli/plugins/system.py"
    click ProjectP "https://github.com/badie005/bdev-cli/blob/main/cli/plugins/project.py"
    click Doctor "https://github.com/badie005/bdev-cli/blob/main/cli/plugins/doctor.py"
    click Scripts "https://github.com/badie005/bdev-cli/blob/main/cli/plugins/scripts.py"
    click Snippets "https://github.com/badie005/bdev-cli/blob/main/cli/plugins/snippets.py"
    click Templates "https://github.com/badie005/bdev-cli/blob/main/cli/plugins/templates.py"
    click Todo "https://github.com/badie005/bdev-cli/blob/main/cli/plugins/todo.py"
    click ShellP "https://github.com/badie005/bdev-cli/blob/main/cli/plugins/shell.py"

    %% Click Events Utilities
    click UI "https://github.com/badie005/bdev-cli/blob/main/cli/utils/ui.py"
    click Theme "https://github.com/badie005/bdev-cli/blob/main/cli/utils/theme.py"
    click Errors "https://github.com/badie005/bdev-cli/blob/main/cli/utils/errors.py"

    %% Packaging & Config files
    SetupPy["setup.py"]:::code
    PyProj["pyproject.toml"]:::code
    ReqTxt["requirements.txt"]:::code
    User -->|"reads"| SetupPy
    User -->|"reads"| PyProj
    User -->|"reads"| ReqTxt
    click SetupPy "https://github.com/badie005/bdev-cli/blob/main/setup.py"
    click PyProj "https://github.com/badie005/bdev-cli/blob/main/pyproject.toml"
    click ReqTxt "https://github.com/badie005/bdev-cli/blob/main/requirements.txt"

    %% Legend
    subgraph Legend
        direction LR
        C[("Code Components")]:::code
        S[(Storage)]:::storage
        E{{"External"}}:::external
        U[("User")]:::user
    end

    classDef code fill:#cce5ff,stroke:#004085,color:#004085;
    classDef storage fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
    classDef user fill:#f8d7da,stroke:#721c24,color:#721c24;
```
