command-assistant/docs/developer/architecture.md

Architecture Overview

This document provides a comprehensive overview of Edison's architecture, components, and their interactions.

System Architecture

graph TD
    subgraph User Interaction
        CLI[CLI Module]
        Interactive[Interactive Mode]
        Console[Console UI]
    end
    
    subgraph Core Components
        APIClient[API Client]
        PromptManager[Prompt Manager]
        CommandExecutor[Command Executor]
    end
    
    subgraph Configuration
        ConfigManager[Config Manager]
        Validation[Validation]
    end
    
    subgraph Utilities
        Logging[Logging Utils]
        OSUtils[OS Utils]
    end
    
    CLI --> APIClient
    CLI --> CommandExecutor
    CLI --> Console
    CLI --> Interactive
    Interactive --> APIClient
    Interactive --> CommandExecutor
    
    APIClient --> PromptManager
    APIClient --> ConfigManager
    CommandExecutor --> Validation
    CommandExecutor --> OSUtils
    
    ConfigManager --> Logging
    
    style User Interaction fill:#f9d5e5,stroke:#333,stroke-width:2px
    style Core Components fill:#d3f6db,stroke:#333,stroke-width:2px
    style Configuration fill:#d3f6f5,stroke:#333,stroke-width:2px
    style Utilities fill:#eeeeee,stroke:#333,stroke-width:2px

Component Breakdown

User Interaction Layer

The user interaction layer handles all user-facing functionality:

1. CLI Module (edison/cli.py):

   • Entry point for the application
   • Parses command-line arguments
   • Initializes logging and configuration
   • Coordinates between components

2. Interactive Mode (edison/ui/interactive.py):

   • Provides a dedicated shell for continuous interaction
   • Manages command history and user input
   • Handles special commands and actions

3. Console UI (edison/ui/console.py):

   • Formats and displays text output
   • Presents commands and prompt options
   • Manages colored output with termcolor

Core Components

The core components handle the main business logic:

1. API Client (edison/core/api_client.py):

   • Manages communication with the OpenAI API
   • Handles API key management and retry logic
   • Processes responses from the API

2. Prompt Manager (edison/core/prompt_manager.py):

   • Constructs effective prompts for the AI model
   • Formats user queries for optimal command generation
   • Adapts prompts based on shell and OS

3. Command Executor (edison/core/command_executor.py):

   • Safely executes generated commands
   • Handles command output and errors
   • Adapts execution for different shells and platforms

Configuration Layer

The configuration layer manages settings and validation:

1. Config Manager (edison/config/config_manager.py):

   • Loads and validates configuration from edison.yaml
   • Provides default settings
   • Handles environment variables for API keys

2. Validation (edison/utils/validation.py):

   • Validates commands for safety
   • Detects potentially dangerous operations
   • Checks for invalid syntax or formatting

Utilities

Utility modules provide support functions:

1. Logging Utils (edison/utils/logging_utils.py):

   • Configures logging for the application
   • Manages log files and levels
   • Provides logger access

2. OS Utils (edison/utils/os_utils.py):

   • Provides OS-specific functionality
   • Detects platform and shell information
   • Manages environment variables

Data Flow

sequenceDiagram
    participant User
    participant CLI
    participant Config
    participant APIClient
    participant CommandExecutor
    participant Shell
    
    User->>CLI: Input query
    CLI->>Config: Load configuration
    CLI->>APIClient: Send query
    APIClient->>APIClient: Format prompt
    APIClient->>OpenAI: API request
    OpenAI-->>APIClient: Command response
    APIClient-->>CLI: Return command
    CLI->>User: Display command
    User->>CLI: Confirm execution
    CLI->>CommandExecutor: Execute command
    CommandExecutor->>Shell: Run in shell
    Shell-->>CommandExecutor: Command output
    CommandExecutor-->>CLI: Execution result
    CLI->>User: Display output

1. User inputs a natural language query
2. CLI loads configuration and processes arguments
3. Query is sent to the API client
4. API client formats the prompt and sends it to OpenAI
5. Response is received and processed
6. Command is displayed to the user
7. User confirms, modifies, or cancels execution
8. If confirmed, command is sent to the command executor
9. Command executor runs the command in the appropriate shell
10. Output is returned to the CLI and displayed to the user

Extension Points

Edison is designed to be extensible in several ways:

1. New UI Components: Add new UI modes by extending the UI components
2. Alternative AI Providers: The API client can be extended to support other AI providers
3. Custom Prompt Templates: The prompt manager can be enhanced with specialized prompts
4. Additional Command Validation: Add custom validation rules in the validation module
5. Platform-Specific Features: Extend OS utils for additional platform support

Technologies Used

Edison is built using:

• Python: Core programming language
• OpenAI API: For natural language processing and command generation
• prompt_toolkit: For interactive shell functionality
• termcolor: For colored terminal output
• pyyaml: For configuration file parsing
• pyperclip: For clipboard integration