# eliran79/nexus-ai architecture

> Architecture diagram of the GitHub repository eliran79/nexus-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eliran79/nexus-ai
- Repository: https://github.com/eliran79/nexus-ai

## Overview

##### Identifying the Project’s Main Components
- Interactive CLI Environment – This is the user “front-end” where commands are entered.
- REPL Modules – There are several REPL modules under the “nexus_ai/repl” directory (base.py, nexus_repl.py, python_repl.py, task_repl.py). They parse user commands, determine the command prefixes (>, !, or ??/claude), and decide what to execute.
- Execution Engine – Under “nexus_ai/core” you have executor.py, output.py, and session.py. These coordinate the execution of Python code, manage output processing, and keep session information persistent.
- AI Integration – The “nexus_ai/claude” module (with its client.py) handles interactions with the Anthropic Claude API, processing natural language requests that ask for coding help or analysis.
- Utility and Configuration – The “nexus_ai/utils/config.py” provides configuration management required across modules (like API keys and other settings).

##### Determining Relationships and Interactions
- User Input/Command Parsing: In the CLI component (powered by main.py), user commands are parsed and directed to the appropriate REPL module based on the command prefix.
- Command Routing: Depending on whether a command starts with “>” (Python), “!” (Bash), or “??”/“claude” (AI assistance), the corresponding REPL module is invoked.
- Execution Flow: For Python or Bash commands, the core executor facilitates the runtime execution and then relays the output via the output module. The session module ensures that variables and context persist.
- AI Assistance: For assistance requests, the input is sent from the REPL to the Claude integration via the client module, which then returns the processed response or generated code.
- Config and Dependencies: The utilities for configuration ensure proper setup (e.g., loading API keys and environment configurations) across all components.

##### Architectural Patterns and Design Principles
- Modular Architecture: Clear separation of concerns across REPL handling, execution logic, and AI integration.
- Command Dispatcher Pattern: The system detects command prefixes and routes the requests to appropriate handlers.
- Layered Structure: The user interface (CLI) directly interacts with REPL components, which in turn utilize lower-level core logic (execution, session management) and AI services.
- Extensibility: The modular approach makes it simple to add new command types or integrate additional services.

##### Relevant Technologies, Frameworks, and Libraries
- Python 3.x – primary language.
- Anthropic Claude API – for AI integration.
- Standard Python libraries for process execution and session management.
- pytest for testing (as mentioned in the README).
- Virtual environments and pip (see requirements.txt and setup.py).

- From the dispatcher, branch out to:
- A “Python REPL Module” that connects to an “Executor and Session Manager” (core execution) for running Python code.
- A “Bash Executor” which represents the handling of shell commands.
- A shared “Utilities/Configuration” component that all modules refer to.

## Diagram (Mermaid)

```mermaid
graph TD
    CLI("Interactive CLI Environment"):::interface
    click CLI "https://github.com/eliran79/nexus-ai/blob/main/nexus_ai/main.py"
    
    CD("Command Dispatcher"):::logic

    REPL("REPL Modules (Python, Bash, Task)"):::interface
    click REPL "https://github.com/eliran79/nexus-ai/tree/main/nexus_ai/repl/"

    EE("Execution Engine (Executor, Output, Session)"):::core
    click EE "https://github.com/eliran79/nexus-ai/tree/main/nexus_ai/core/"

    AI("Claude AI Integration"):::ai
    click AI "https://github.com/eliran79/nexus-ai/tree/main/nexus_ai/claude/"

    Config("Utility & Configuration"):::config
    click Config "https://github.com/eliran79/nexus-ai/blob/main/nexus_ai/utils/config.py"

    %% Connections
    CLI -->|"Process_Command"| CD
    CD -->|"Route_Python/Bash"| REPL
    CD -->|"Route_AI"| AI
    REPL -->|"Execute_Command"| EE
    EE -->|"Return_Output"| CLI

    %% Configuration dependencies
    REPL -.->|"Uses_Config"| Config
    EE -.->|"Uses_Config"| Config
    AI -.->|"Uses_Config"| Config

    %% Styles
    classDef interface fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef logic fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef core fill:#A9DFBF,stroke:#229954,stroke-width:2px;
    classDef ai fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef config fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
```
