# riyaax07/cmdbuddy architecture

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

- Interactive diagram: https://gitdiagram.com/riyaax07/cmdbuddy
- Repository: https://github.com/riyaax07/cmdbuddy

## Overview

CmdBuddy is a PowerShell-first assistant that turns developer intent into proposed commands, checks their safety, and runs them only according to approval rules. Its second major workflow captures a terminal error, gathers project context, and proposes an evidence-grounded fix. It also exposes project facts and stores history, snippets, and session state locally. The README documents these capabilities; some internal wiring is supported only by its architecture description or source-index references, so unsampled details are not expanded.

Main entry points: [`cmdbuddy/cli.py`](https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/cli.py) (CLI entry), [`cmdbuddy/executor.py`](https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/executor.py) (Approval and execution), [`cmdbuddy/ai_client.py`](https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/ai_client.py) (Generation and diagnosis), [`cmdbuddy/storage.py`](https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/storage.py) (Persistence manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflows["User Workflows"]
  node_cli["CLI entry<br/>[cli.py]"]
  node_error_capture["Error capture<br/>[error_capture.py]"]
end

subgraph group_intelligence["Context and Diagnosis"]
  node_context["Project context<br/>[context_engine.py]"]
  node_ai["Generation and diagnosis<br/>[ai_client.py]"]
  node_schemas["Response schemas<br/>[schemas.py]"]
end

subgraph group_execution["Command Execution"]
  node_safety["Safety classifier<br/>[safety.py]"]
  node_executor["Approval and execution<br/>[executor.py]"]
  node_ui["Terminal UI<br/>[ui.py]"]
end

subgraph group_persistence["Local Persistence"]
  node_storage["Persistence manager<br/>[storage.py]"]
  node_sqlite[("Local SQLite")]
end

node_user(("PowerShell user"))
node_gemini{{"Gemini API"}}
node_powershell{{"PowerShell runtime"}}
node_demo_mount["Demo app mount<br/>[main.tsx]"]
node_demo_app["Demo React app<br/>[App.tsx]"]

node_user -->|"invokes"| node_cli
node_cli -->|"scans project"| node_context
node_cli -->|"requests generation"| node_ai
node_cli -->|"captures errors"| node_error_capture
node_cli -->|"requests diagnosis"| node_ai
node_ai -->|"uses project facts"| node_context
node_ai -->|"sends API request"| node_gemini
node_ai -->|"validates responses"| node_schemas
node_cli -->|"classifies snippets"| node_safety
node_cli -->|"submits commands"| node_executor
node_executor -->|"classifies command"| node_safety
node_executor -->|"runs command"| node_powershell
node_executor -->|"renders prompts"| node_ui
node_executor -->|"records execution"| node_storage
node_error_capture -->|"reads session state"| node_storage
node_error_capture -->|"prompts user"| node_ui
node_cli -->|"manages snippets"| node_storage
node_storage -->|"reads and writes"| node_sqlite
node_demo_mount -->|"renders"| node_demo_app

click node_cli "https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/cli.py"
click node_error_capture "https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/error_capture.py"
click node_context "https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/context_engine.py"
click node_ai "https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/ai_client.py"
click node_schemas "https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/schemas.py"
click node_safety "https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/safety.py"
click node_executor "https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/executor.py"
click node_ui "https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/ui.py"
click node_storage "https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/storage.py"
click node_demo_mount "https://github.com/riyaax07/cmdbuddy/blob/main/demo-react-vite-project/src/main.tsx"
click node_demo_app "https://github.com/riyaax07/cmdbuddy/blob/main/demo-react-vite-project/src/App.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_error_capture,node_user toneBlue
class node_context,node_ai,node_schemas toneAmber
class node_safety,node_executor,node_ui,node_gemini toneMint
class node_storage,node_sqlite toneRose
class node_powershell toneIndigo
class node_demo_mount,node_demo_app toneTeal
```

## Components

### User Workflows

- [CLI entry](https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/cli.py): `cmdbuddy/cli.py`
- [Error capture](https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/error_capture.py): `cmdbuddy/error_capture.py`

### Context and Diagnosis

- [Project context](https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/context_engine.py): `cmdbuddy/context_engine.py`
- [Generation and diagnosis](https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/ai_client.py): `cmdbuddy/ai_client.py`
- [Response schemas](https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/schemas.py): `cmdbuddy/schemas.py`

### Command Execution

- [Safety classifier](https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/safety.py): `cmdbuddy/safety.py`
- [Approval and execution](https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/executor.py): `cmdbuddy/executor.py`
- [Terminal UI](https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/ui.py): `cmdbuddy/ui.py`

### Local Persistence

- [Persistence manager](https://github.com/riyaax07/cmdbuddy/blob/main/cmdbuddy/storage.py): `cmdbuddy/storage.py`
- **Local SQLite**

### Other components

- **PowerShell user**
- **Gemini API**
- **PowerShell runtime**
- [Demo app mount](https://github.com/riyaax07/cmdbuddy/blob/main/demo-react-vite-project/src/main.tsx): `demo-react-vite-project/src/main.tsx`
- [Demo React app](https://github.com/riyaax07/cmdbuddy/blob/main/demo-react-vite-project/src/App.tsx): `demo-react-vite-project/src/App.tsx`

## Connections

- PowerShell user → CLI entry: invokes (evidence: `README.md`)
- CLI entry → Project context: scans project (evidence: `README.md`)
- CLI entry → Generation and diagnosis: requests generation (evidence: `cmdbuddy/cli.py`)
- CLI entry → Error capture: captures errors (evidence: `README.md`)
- CLI entry → Generation and diagnosis: requests diagnosis (evidence: `cmdbuddy/cli.py`)
- Generation and diagnosis → Project context: uses project facts (evidence: `cmdbuddy/ai_client.py`)
- Generation and diagnosis → Gemini API: sends API request (evidence: `cmdbuddy/ai_client.py`)
- Generation and diagnosis → Response schemas: validates responses (evidence: `cmdbuddy/ai_client.py`)
- CLI entry → Safety classifier: classifies snippets (evidence: `cmdbuddy/cli.py`)
- CLI entry → Approval and execution: submits commands (evidence: `README.md`)
- Approval and execution → Safety classifier: classifies command (evidence: `cmdbuddy/executor.py`)
- Approval and execution → PowerShell runtime: runs command (evidence: `cmdbuddy/executor.py`)
- Approval and execution → Terminal UI: renders prompts (evidence: `cmdbuddy/executor.py`)
- Approval and execution → Persistence manager: records execution (evidence: `cmdbuddy/executor.py`)
- Error capture → Persistence manager: reads session state (evidence: `cmdbuddy/error_capture.py`)
- Error capture → Terminal UI: prompts user (evidence: `cmdbuddy/error_capture.py`)
- CLI entry → Persistence manager: manages snippets (evidence: `cmdbuddy/cli.py`)
- Persistence manager → Local SQLite: reads and writes (evidence: `README.md`)
- Demo app mount → Demo React app: renders (evidence: `demo-react-vite-project/src/main.tsx`)
