# doriandarko/deepseek-engineer architecture

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

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

## Overview

##### Project Type & Purpose
- DeepSeek Engineer v2 is an **open-source CLI tool** (terminal interface) that acts as an AI-powered coding assistant.
- It connects a local CLI front-end to DeepSeek’s reasoning models, orchestrates function-calls for file operations, and streams real-time feedback to the user.

##### Break Down the Main Architectural Components
a. **CLI Interface (deepseek-eng.py)**
– Entry point, command parsing, and interactive shell.
b. **Controller/Orchestrator**
– Chains:
1. User Input
2. Chain-of-Thought Reasoning
3. Tool Invocation & Execution
4. AI Follow-up Response
– Manages the “triple-stream” (reasoning, content, tool_calls).
c. **DeepSeek Reasoning Model**
– External AI service (DeepSeek-Reasoner API).
– Receives natural language prompts and returns CoT outputs + suggested function calls.
d. **Function-Calling Tools Module**
– read_file(), read_multiple_files(), create_file(), create_multiple_files(), edit_file().
– Implements path normalization, traversal protection, size limits, error handling.
e. **Local File System**
– The actual project files (.py, .html, config files).
– .env for DEEPSEEK_API_KEY.
f. **Configuration & Dependency Layer**
– pyproject.toml, requirements.txt, .python-version, uv.lock.
– uv CLI runner integration.
g. **Static Assets**
– bouncing_ball_hexagon.html, solar_cube.html (demo artifacts/examples).
h. **External Services**
– DeepSeek Platform for the API key & reasoning model.
– Optional: pip registry, uv registry for dependencies.

##### Relationships & Data Flows
– **CLI Interface → Controller**: parse user commands → send to orchestrator.
– **Controller ↔ DeepSeek API**:
- Send user prompt → receive CoT + function call plan.
– **Controller → Tools Module**: invoke function calls as suggested.
– **Tools Module → File System**: perform read/write operations.
– **Tools Module → Controller**: return file contents or confirmation.
– **Controller → CLI Interface**: stream combined reasoning + content to user.
– **Configuration Layer** feeds into CLI/Controller at startup.

##### Patterns & Principles
- **Separation of Concerns**:
– CLI UI vs. Orchestration vs. File-IO.
- **Function-Calling Architecture**:
– Native function calls as the “API” between AI and host tool.
- **Streaming + Chain-of-Thought**:
– Real-time feedback loop with clearly demarcated streams.
- **Security Best Practices**:
– Path normalization, directory traversal guards, file size limits.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User CLI Layer
    subgraph "User CLI"
        CLI["CLI Interface\n(Python + uv)"]:::internal
    end

    %% Internal Engine Layer
    subgraph "Internal Engine"
        Controller["Controller/Orchestrator"]:::internal
        Tools["Function-Calling Tools Module"]:::internal
        Config["Config & Dependency Layer"]:::internal
    end

    %% Storage Layer
    subgraph "Storage"
        LocalFS["Local File System"]:::storage
        StaticAssets["Static Assets\n(bouncing_ball_hexagon.html, solar_cube.html)"]:::storage
    end

    %% External Systems Layer
    subgraph "External Systems"
        API["DeepSeek Reasoner API"]:::external
        Registries["Dependency Registries\n(pip, uv)"]:::external
    end

    %% Flows
    CLI -->|"parse user commands"| Controller
    Controller -->|"HTTP POST /chat"| API
    API -->|"return CoT + function calls"| Controller
    Controller -->|"invoke read_file(), create_file(), etc."| Tools
    Tools -->|"perform FS operations"| LocalFS
    Tools -->|"perform FS operations"| StaticAssets
    Tools -->|"return data/errors"| Controller
    Controller -->|"stream reasoning"| CLI
    Controller -->|"stream content"| CLI
    Controller -->|"stream tool_calls"| CLI
    Config -->|"load at startup"| CLI
    Config -->|"load at startup"| Controller
    Registries -->|"provide dependencies"| Config

    %% Click Events
    click CLI "https://github.com/doriandarko/deepseek-engineer/blob/main/deepseek-eng.py"
    click Controller "https://github.com/doriandarko/deepseek-engineer/blob/main/deepseek-eng.py"
    click Tools "https://github.com/doriandarko/deepseek-engineer/blob/main/deepseek-eng.py"
    click Config "https://github.com/doriandarko/deepseek-engineer/blob/main/pyproject.toml"
    click Config "https://github.com/doriandarko/deepseek-engineer/blob/main/requirements.txt"
    click Config "https://github.com/doriandarko/deepseek-engineer/blob/main/.python-version"
    click Config "https://github.com/doriandarko/deepseek-engineer/blob/main/uv.lock"
    click StaticAssets "https://github.com/doriandarko/deepseek-engineer/blob/main/bouncing_ball_hexagon.html"
    click StaticAssets "https://github.com/doriandarko/deepseek-engineer/blob/main/solar_cube.html"
    click LocalFS "https://github.com/doriandarko/deepseek-engineer/blob/main/."

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#1F618D,stroke-width:1px
    classDef external fill:#D5F5E3,stroke:#27AE60,stroke-width:1px
    classDef storage fill:#FCF3CF,stroke:#B7950B,stroke-width:1px
```
