# doriandarko/claude-engineer architecture

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

- Interactive diagram: https://gitdiagram.com/doriandarko/claude-engineer
- Repository: https://github.com/doriandarko/claude-engineer

## Overview

##### Main Components
- Interface Layer:
- Web Interface: Represented by app.py, templates (HTML files), and static (CSS/JS) assets. This component handles HTTP requests, real-time updates (e.g., token visualization), and a user-friendly modern UI.
- CLI Interface: Represented by ce3.py, which provides rich text formatting, progress indicators, and a terminal-based workflow.
- Core Application Logic:
- Assistant and Conversation Manager: This handles dynamic tool creation, conversation state management, token tracking (with dependencies on Anthropic’s token counting API), and decision-making during interactions.
- Configuration Module: (config.py) that centralizes model settings, tokens limits, tool directory location, and other options.
- Prompts System: (prompts/system_prompts.py), which provides system-level prompt definitions to guide the AI’s behavior.
- Tools Framework:
- Tools Directory: Contains a base tool class (tools/base.py) and numerous specialized tool modules (e.g., toolcreator, file handling, web scraping, linting, etc.). These modules encapsulate discrete functionalities that the assistant can load, chain, and execute dynamically.
- External Services and Dependencies:
- UV Package Manager Integration (tools/uvpackagemanager.py) for managing package dependencies.
- External APIs for Anthropic's Claude 3.5 and E2B (for secure code execution).
- Utility and Testing:
- Additional scripts like test.py and auxiliary tool modules that support various development and operational tasks.

##### Relationships and Interactions
- The user interacts with the system through either the Web or CLI interface.
- In the web interface, HTTP requests flow from the browser (shown via static assets and HTML templates) to app.py, which then calls the core assistant logic.
- In CLI mode, ce3.py drives the conversation loop, interfacing directly with the Assistant class.
- The core assistant manages conversation state, dynamically loads tools from the “tools” directory, and uses configuration settings (config.py) and system prompts (prompts) to process user input.
- When a tool is required (self-improving feature), the assistant uses the tool abstraction framework to instantiate and execute the proper tool (e.g., file manipulation or web scraping) in a chained or sequential manner.
- The communication between components is guided by clear API-like contracts, e.g., tool creation (toolcreator), execution outputs feeding back to conversation handling, and token usage tracking seamlessly integrated throughout the process.

##### Architectural Patterns and Design Principles
- Modular Design: Separation into directories for interface (app.py, ce3.py, static assets, and templates), business logic (config, prompts), and tool implementations (tools/ directory).
- Plugin/Extension Architecture: The “tools” module is built using a base class that allows dynamic loading and execution of additional functionality, facilitating autonomous tool generation and extension.
- Self-Improvement Loop: The intelligent assistant continually monitors usage patterns, dynamically generates new tools, and optimizes existing ones, embodying a kind of feedback loop.
- Clear Concerns Separation: Different components clearly separate user input handling (interfaces) from business logic and tool execution.

##### Including Relevant Technologies and Frameworks
- Python 3.8+ as the primary language.
- Web technologies such as HTML, CSS, and JavaScript for the web interface.
- Integration of third-party APIs (Anthropic for AI, E2B for code execution).
- Utilization of “uv” for running scripts and managing virtual environments.
- The design leverages a modular Python-based architecture with dynamic module importing and real-time status visualization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User interacting with the system
    User["User"]:::user

    %% Interface Layer
    subgraph "Interface Layer"
        subgraph "Web Interface"
            webApp["app.py"]:::web
            webTemplates["Templates"]:::web
            webStaticCss["Static CSS"]:::web
            webStaticJs["Static JS"]:::web
        end
        CLI["CLI (ce3.py)"]:::cli
    end

    %% Core Application Logic
    subgraph "Core Application Logic"
        Assistant["Assistant Core"]:::core
        Config["Configuration"]:::config
        Prompts["Prompts System"]:::prompts
    end

    %% Tools Framework & External Services
    Tools["Tools Framework"]:::tools
    UV["UV Package Manager"]:::external
    Anthropic["Anthropic API"]:::external
    E2B["E2B API"]:::external
    Test["Utility/Testing"]:::utility

    %% Interactions from User to Interfaces
    User -->|"interacts"| webApp
    User -->|"interacts"| CLI

    %% Interfaces sending commands to the Core
    webApp -->|"HTTP-request"| Assistant
    CLI -->|"CLI-command"| Assistant

    %% Core dependencies
    Assistant -->|"uses"| Config
    Assistant -->|"uses"| Prompts
    Assistant -->|"loads"| Tools
    Assistant -->|"calls"| Anthropic
    Assistant -->|"calls"| E2B

    %% Tools integration and external dependencies
    Tools -->|"integrates"| Assistant
    Tools -->|"dependency"| UV

    %% Utility supporting Tools
    Test -->|"supports"| Tools

    %% Subgraph Click Event Nodes are not visible but provide navigation for mapped components

    %% Click Events
    click webApp "https://github.com/doriandarko/claude-engineer/blob/main/app.py"
    click webTemplates "https://github.com/doriandarko/claude-engineer/blob/main/templates/index.html"
    click webStaticCss "https://github.com/doriandarko/claude-engineer/blob/main/static/css/style.css"
    click webStaticJs "https://github.com/doriandarko/claude-engineer/blob/main/static/js/chat.js"
    click CLI "https://github.com/doriandarko/claude-engineer/blob/main/ce3.py"
    click Config "https://github.com/doriandarko/claude-engineer/blob/main/config.py"
    click Prompts "https://github.com/doriandarko/claude-engineer/blob/main/prompts/system_prompts.py"
    click Tools "https://github.com/doriandarko/claude-engineer/tree/main/tools/"
    click UV "https://github.com/doriandarko/claude-engineer/blob/main/tools/uvpackagemanager.py"
    click Test "https://github.com/doriandarko/claude-engineer/blob/main/test.py"

    %% Styles
    classDef user fill:#fce94f,stroke:#555,stroke-width:2px;
    classDef web fill:#8ae234,stroke:#555,stroke-width:2px;
    classDef cli fill:#729fcf,stroke:#555,stroke-width:2px;
    classDef core fill:#ad7fa8,stroke:#555,stroke-width:2px;
    classDef config fill:#efc000,stroke:#555,stroke-width:2px;
    classDef prompts fill:#efc000,stroke:#555,stroke-width:2px;
    classDef tools fill:#fcaf3e,stroke:#555,stroke-width:2px;
    classDef external fill:#e9b96e,stroke:#555,stroke-width:2px;
    classDef utility fill:#cc0000,stroke:#555,stroke-width:2px;
```
