# waddle-io/ezshell architecture

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

- Interactive diagram: https://gitdiagram.com/waddle-io/ezshell
- Repository: https://github.com/waddle-io/ezshell

## Overview

ezShell diagnoses failed shell commands and turns natural-language requests into proposed commands that the user reviews and inserts; it does not execute fixes without user action. The Python CLI captures shell context, routes requests through a shared assistant/provider path, applies risk checks, and presents results in desktop, terminal, or inline interfaces. Its hosted web service supplies proxy-based AI access, device authorization, quotas, and account/admin capabilities. Some web routes and UI-to-API wiring were not sampled, so those connections are omitted rather than inferred.

Main entry points: [`web/lib/handlers.ts`](https://github.com/waddle-io/ezshell/blob/main/web/lib/handlers.ts) (Hosted API), [`src/core/chat_bridge.py`](https://github.com/waddle-io/ezshell/blob/main/src/core/chat_bridge.py) (Request bridge), [`src/main.py`](https://github.com/waddle-io/ezshell/blob/main/src/main.py) (CLI dispatch), [`src/core/provider.py`](https://github.com/waddle-io/ezshell/blob/main/src/core/provider.py) (Provider selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Shell workflow"]
  node_cli["CLI dispatch<br/>[main.py]"]
  node_shell_hook["Shell integration<br/>[shell_hook.py]"]
  node_capture["Command capture<br/>[capture.py]"]
  node_execution["Command execution<br/>[app.py]"]
  node_interfaces["Desktop and TUI<br/>[gui_window.py]"]
  node_inline["Inline panel<br/>[inline.py]"]
  node_render["Terminal rendering<br/>[render.py]"]
end

subgraph group_assistant["Assistant runtime"]
  node_context["Shell context<br/>[context.py]"]
  node_chat["Request bridge<br/>[chat_bridge.py]"]
  node_suggest["Suggestion logic<br/>[suggest.py]"]
  node_safety["Risk checks<br/>[safety.py]"]
  node_provider["Provider selection<br/>[provider.py]"]
  node_proxy["Device proxy client<br/>[proxy_client.py]"]
  node_direct_llm["Direct Groq client<br/>[groq_client.py]"]
  node_config["User configuration<br/>[config.py]"]
end

subgraph group_hosted["Hosted AI service"]
  node_hosted_api["Hosted API<br/>[handlers.ts]"]
  node_hosted_llm["Hosted model calls<br/>[llm.ts]"]
  node_quota["Quota and plans<br/>[quota.ts]"]
  node_redaction["Server redaction<br/>[redact.ts]"]
  node_database[("PostgreSQL data<br/>[db.ts]")]
end

subgraph group_accounts["Accounts and operations"]
  node_device_auth["Device authorization"]
  node_account_ui["Account dashboard<br/>[page.tsx]"]
  node_admin_ui["Admin console<br/>[page.tsx]"]
  node_admin_api["Admin endpoints"]
end

node_user(("Terminal user"))
node_groq_service["Groq service"]

node_user -->|"invokes"| node_shell_hook
node_shell_hook -.->|"captures runs"| node_capture
node_user -->|"starts"| node_cli
node_cli -->|"dispatches commands"| node_execution
node_execution -->|"reads context"| node_context
node_capture -->|"supplies last run"| node_context
node_cli -->|"dispatches suggestions"| node_inline
node_cli -->|"opens desktop"| node_interfaces
node_interfaces -->|"submits requests"| node_chat
node_inline -->|"requests suggestions"| node_chat
node_chat -->|"builds request context"| node_context
node_chat -->|"gets suggestion"| node_suggest
node_suggest -.->|"queries provider"| node_provider
node_chat -->|"checks proposed commands"| node_safety
node_provider -->|"selects hosted proxy"| node_proxy
node_provider -.->|"selects direct mode"| node_direct_llm
node_provider -->|"loads settings"| node_config
node_proxy -->|"posts requests"| node_hosted_api
node_hosted_api -->|"calls model"| node_hosted_llm
node_hosted_api -->|"checks usage"| node_quota
node_hosted_api -->|"redacts input"| node_redaction
node_hosted_api -->|"uses data store"| node_database
node_hosted_llm -.->|"requests completions"| node_groq_service
node_user -->|"authorizes device"| node_device_auth
node_user -->|"views account"| node_account_ui
node_user -->|"manages service"| node_admin_ui
node_admin_ui -.->|"uses admin features"| node_admin_api

click node_cli "https://github.com/waddle-io/ezshell/blob/main/src/main.py"
click node_shell_hook "https://github.com/waddle-io/ezshell/blob/main/src/core/shell_hook.py"
click node_capture "https://github.com/waddle-io/ezshell/blob/main/src/core/capture.py"
click node_execution "https://github.com/waddle-io/ezshell/blob/main/src/app.py"
click node_context "https://github.com/waddle-io/ezshell/blob/main/src/core/context.py"
click node_chat "https://github.com/waddle-io/ezshell/blob/main/src/core/chat_bridge.py"
click node_suggest "https://github.com/waddle-io/ezshell/blob/main/src/core/suggest.py"
click node_safety "https://github.com/waddle-io/ezshell/blob/main/src/core/safety.py"
click node_provider "https://github.com/waddle-io/ezshell/blob/main/src/core/provider.py"
click node_proxy "https://github.com/waddle-io/ezshell/blob/main/src/core/proxy_client.py"
click node_direct_llm "https://github.com/waddle-io/ezshell/blob/main/src/core/groq_client.py"
click node_config "https://github.com/waddle-io/ezshell/blob/main/src/core/config.py"
click node_interfaces "https://github.com/waddle-io/ezshell/blob/main/src/ui/gui_window.py"
click node_inline "https://github.com/waddle-io/ezshell/blob/main/src/ui/inline.py"
click node_render "https://github.com/waddle-io/ezshell/blob/main/src/ui/render.py"
click node_hosted_api "https://github.com/waddle-io/ezshell/blob/main/web/lib/handlers.ts"
click node_hosted_llm "https://github.com/waddle-io/ezshell/blob/main/web/lib/llm.ts"
click node_quota "https://github.com/waddle-io/ezshell/blob/main/web/lib/quota.ts"
click node_redaction "https://github.com/waddle-io/ezshell/blob/main/web/lib/redact.ts"
click node_database "https://github.com/waddle-io/ezshell/blob/main/web/lib/db.ts"
click node_device_auth "https://github.com/waddle-io/ezshell/tree/main/web/app/api/v1/auth/device"
click node_account_ui "https://github.com/waddle-io/ezshell/blob/main/web/app/dashboard/page.tsx"
click node_admin_ui "https://github.com/waddle-io/ezshell/blob/main/web/app/admin/page.tsx"
click node_admin_api "https://github.com/waddle-io/ezshell/tree/main/web/app/api/v1/admin"

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_shell_hook,node_capture,node_execution,node_interfaces,node_inline,node_render,node_user toneBlue
class node_context,node_chat,node_suggest,node_safety,node_provider,node_proxy,node_direct_llm,node_config toneAmber
class node_hosted_api,node_hosted_llm,node_quota,node_redaction,node_database toneMint
class node_device_auth,node_account_ui,node_admin_ui,node_admin_api toneRose
class node_groq_service toneIndigo
```

## Components

### Shell workflow

- [CLI dispatch](https://github.com/waddle-io/ezshell/blob/main/src/main.py): `src/main.py`
- [Shell integration](https://github.com/waddle-io/ezshell/blob/main/src/core/shell_hook.py): `src/core/shell_hook.py`
- [Command capture](https://github.com/waddle-io/ezshell/blob/main/src/core/capture.py): `src/core/capture.py`
- [Command execution](https://github.com/waddle-io/ezshell/blob/main/src/app.py): `src/app.py`
- [Desktop and TUI](https://github.com/waddle-io/ezshell/blob/main/src/ui/gui_window.py): `src/ui/gui_window.py`
- [Inline panel](https://github.com/waddle-io/ezshell/blob/main/src/ui/inline.py): `src/ui/inline.py`
- [Terminal rendering](https://github.com/waddle-io/ezshell/blob/main/src/ui/render.py): `src/ui/render.py`

### Assistant runtime

- [Shell context](https://github.com/waddle-io/ezshell/blob/main/src/core/context.py): `src/core/context.py`
- [Request bridge](https://github.com/waddle-io/ezshell/blob/main/src/core/chat_bridge.py): `src/core/chat_bridge.py`
- [Suggestion logic](https://github.com/waddle-io/ezshell/blob/main/src/core/suggest.py): `src/core/suggest.py`
- [Risk checks](https://github.com/waddle-io/ezshell/blob/main/src/core/safety.py): `src/core/safety.py`
- [Provider selection](https://github.com/waddle-io/ezshell/blob/main/src/core/provider.py): `src/core/provider.py`
- [Device proxy client](https://github.com/waddle-io/ezshell/blob/main/src/core/proxy_client.py): `src/core/proxy_client.py`
- [Direct Groq client](https://github.com/waddle-io/ezshell/blob/main/src/core/groq_client.py): `src/core/groq_client.py`
- [User configuration](https://github.com/waddle-io/ezshell/blob/main/src/core/config.py): `src/core/config.py`

### Hosted AI service

- [Hosted API](https://github.com/waddle-io/ezshell/blob/main/web/lib/handlers.ts): `web/lib/handlers.ts`
- [Hosted model calls](https://github.com/waddle-io/ezshell/blob/main/web/lib/llm.ts): `web/lib/llm.ts`
- [Quota and plans](https://github.com/waddle-io/ezshell/blob/main/web/lib/quota.ts): `web/lib/quota.ts`
- [Server redaction](https://github.com/waddle-io/ezshell/blob/main/web/lib/redact.ts): `web/lib/redact.ts`
- [PostgreSQL data](https://github.com/waddle-io/ezshell/blob/main/web/lib/db.ts): `web/lib/db.ts`

### Accounts and operations

- [Device authorization](https://github.com/waddle-io/ezshell/tree/main/web/app/api/v1/auth/device): `web/app/api/v1/auth/device`
- [Account dashboard](https://github.com/waddle-io/ezshell/blob/main/web/app/dashboard/page.tsx): `web/app/dashboard/page.tsx`
- [Admin console](https://github.com/waddle-io/ezshell/blob/main/web/app/admin/page.tsx): `web/app/admin/page.tsx`
- [Admin endpoints](https://github.com/waddle-io/ezshell/tree/main/web/app/api/v1/admin): `web/app/api/v1/admin`

### Other components

- **Terminal user**
- **Groq service**

## Connections

- Terminal user → Shell integration: invokes
- Shell integration → Command capture: captures runs
- Terminal user → CLI dispatch: starts
- CLI dispatch → Command execution: dispatches commands (evidence: `src/main.py`)
- Command execution → Shell context: reads context (evidence: `src/app.py`)
- Command capture → Shell context: supplies last run (evidence: `src/core/context.py`)
- CLI dispatch → Inline panel: dispatches suggestions (evidence: `src/main.py`)
- CLI dispatch → Desktop and TUI: opens desktop (evidence: `src/main.py`)
- Desktop and TUI → Request bridge: submits requests (evidence: `src/ui/gui_window.py`)
- Inline panel → Request bridge: requests suggestions (evidence: `src/ui/inline.py`)
- Request bridge → Shell context: builds request context (evidence: `src/core/chat_bridge.py`)
- Request bridge → Suggestion logic: gets suggestion (evidence: `src/core/chat_bridge.py`)
- Suggestion logic → Provider selection: queries provider
- Request bridge → Risk checks: checks proposed commands (evidence: `src/core/chat_bridge.py`)
- Provider selection → Device proxy client: selects hosted proxy (evidence: `src/core/provider.py`)
- Provider selection → Direct Groq client: selects direct mode
- Provider selection → User configuration: loads settings (evidence: `src/core/provider.py`)
- Device proxy client → Hosted API: posts requests (evidence: `src/core/proxy_client.py`)
- Hosted API → Hosted model calls: calls model (evidence: `web/lib/handlers.ts`)
- Hosted API → Quota and plans: checks usage (evidence: `web/lib/handlers.ts`)
- Hosted API → Server redaction: redacts input (evidence: `web/lib/handlers.ts`)
- Hosted API → PostgreSQL data: uses data store (evidence: `web/lib/handlers.ts`)
- Hosted model calls → Groq service: requests completions
- Terminal user → Device authorization: authorizes device
- Terminal user → Account dashboard: views account
- Terminal user → Admin console: manages service
- Admin console → Admin endpoints: uses admin features
