# ak4bento/capsule-shell architecture

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

- Interactive diagram: https://gitdiagram.com/ak4bento/capsule-shell
- Repository: https://github.com/ak4bento/capsule-shell

## Overview

##### Project type and purpose
- This is an AI-powered CLI assistant (an open-source tool) named “Capsule Shell.”
- Its purpose is to convert natural-language prompts into safe shell commands, show an explanation, prompt for confirmation, and optionally execute the extracted Bash code.

##### File structure
Top-level directories and files:
- cmd/
– root.go (defines the Cobra CLI commands and flags)
- chat/
– chat.go (handles communication with the OpenRouter API)
- internal/
– readonly.go (UI logic for non-execution mode)
– script.go (logic to extract valid Bash code blocks)
– ui.go (confirmation and execution prompts)
- main.go (initializes the CLI and kicks off the command flow)
- go.mod, go.sum (dependency configuration)

##### README for additional insights
- Uses Cobra for CLI parsing
- Calls the OpenRouter API (e.g., OpenAI) via chat/chat.go
- Has two modes: descriptive (-d) and execution (-x)
- Safety: only extracts and runs code from fenced Bash code blocks after confirmation

##### Components
a. User / Terminal
b. CLI Parser (Cobra – cmd/root.go)
c. Chat Service Module (chat/chat.go)
d. AI Provider (external OpenRouter API)
e. Response Handler & Extractor (internal/script.go)
f. UI & Confirmation Layer (internal/ui.go and internal/readonly.go)
g. Shell Execution Engine (invokes OS shell)
h. Optional: Configuration & Flags subsystem (Cobra flags, env vars)

##### Relationships and data flow
1. User enters a natural-language prompt + flags in the terminal.
2. Cobra Parser reads flags (-d, -x) and routes to main.
3. main.go calls Chat Service → sends prompt to OpenRouter API.
4. AI Provider returns a text response.
5. Response Handler extracts only the valid Bash code block.
6. UI Layer displays the AI explanation (descriptive mode) and shows the extracted command.
7. If execution flag is set, UI prompts user “Run this command? (y/n)”.
8. On confirmation, Shell Execution Engine spawns a subprocess to run the safe Bash command.
9. Execution result is returned and printed to the user.

##### Architectural patterns and design principles
- Modular separation: CLI, API client, parsing/extraction logic, UI, execution
- Single Responsibility: each package (cmd, chat, internal) has a clear role
- Safety first: “extract only fenced Bash code” principle, explicit confirmation

##### Detail
- Decision points (flags parsing, user confirmation).
- Role of internal/readonly.go vs. internal/ui.go for non-execution vs. execution flows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["User / Terminal"]:::ui
    B["CLI Parser\n(cmd/root.go)"]:::ui
    C["Main Entry Point\n(main.go)"]:::processing
    D{"Execution Flag (-x)?"}:::processing
    E["Chat Service\n(chat/chat.go)"]:::processing
    F["AI Provider\n(OpenRouter API)"]:::external
    G["Response Handler\n(internal/script.go)"]:::processing
    H1["UI Descriptive Mode\n(internal/readonly.go)"]:::ui
    H2["UI Confirmation\n(internal/ui.go)"]:::ui
    I["Shell Execution Engine"]:::execution
    J["OS Shell"]:::execution

    A -->|"enter prompt & flags"| B
    B -->|"parsed flags & command"| C
    C --> E
    E -->|"prompt text"| F
    F -->|"AI response"| G
    G -->|"Bash code snippet"| D
    D -- no (-d) --> H1
    D -- yes (-x) --> H2
    H2 -->|"confirmation yes"| I
    I --> J
    J -->|"execution result"| H2

    click B "https://github.com/ak4bento/capsule-shell/blob/main/cmd/root.go"
    click E "https://github.com/ak4bento/capsule-shell/blob/main/chat/chat.go"
    click G "https://github.com/ak4bento/capsule-shell/blob/main/internal/script.go"
    click H2 "https://github.com/ak4bento/capsule-shell/blob/main/internal/ui.go"
    click H1 "https://github.com/ak4bento/capsule-shell/blob/main/internal/readonly.go"
    click C "https://github.com/ak4bento/capsule-shell/blob/main/main.go"

    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef processing fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef execution fill:#FF6347,stroke:#333,stroke-width:1px
```
