DeepCode Architecture Analysis

Companion analysis for whitehat-bot/automatic-potato (forked from HKUDS/DeepCode)

Architecture Overview

deepcode/
├── deepcode.py              # Entry point: Docker/local/CLI/Streamlit launcher
├── core/                    # Runtime kernel
│   ├── config.py            # Unified config (JSON + env vars + Pydantic)
│   ├── llm_runtime.py       # LLM call orchestration
│   ├── providers/           # Multi-provider abstraction
│   │   ├── base.py          # LLMProvider ABC
│   │   ├── openai_compat.py # OpenAI-compatible (covers OpenAI/DeepSeek/Gemini/etc)
│   │   ├── anthropic.py     # Anthropic Claude
│   │   └── registry.py      # Provider registry + auto-detection
│   ├── agent_runtime/       # Agent execution engine
│   │   ├── runner.py        # Tool-calling loop
│   │   ├── runtime.py       # Session lifecycle
│   │   └── tools/           # MCP tool integration
│   ├── sessions/            # Persistent session store
│   └── observability/       # Structured logging (JSONL per-task)
├── workflows/               # Multi-agent orchestration
│   ├── planning_runtime.py           # Requirement → plan
│   ├── implementation_llm_runtime.py # Plan → code
│   ├── code_implementation_workflow.py # End-to-end pipeline
│   └── plugins/             # Pluggable workflow stages
├── tools/                   # MCP tool servers (stdio)
│   ├── code_implementation_server.py  # File ops, code exec, search
│   ├── code_indexer.py               # Codebase indexing
│   ├── pdf_downloader.py             # Paper fetching
│   └── command_executor.py           # Shell execution
├── cli/                     # Terminal interface
├── new_ui/                  # Modern web UI
│   ├── backend/             # FastAPI (REST + WebSocket)
│   └── frontend/            # React + Vite + Tailwind
├── nanobot/                 # Multi-channel agent framework
│   └── nanobot/channels/    # Discord/Telegram/Slack/Feishu/etc
└── prompts/                 # LLM prompt templates

Key Design Patterns

1. Provider Abstraction

Auto-detection chain: model prefix → keyword match → local fallback → first with API key. Single make_llm_provider() factory handles all providers.

2. Phase-Based Config

agents.defaults → per-phase override (planning/implementation). resolve_phase() merges with None-fallback.

3. MCP Tool Protocol

Tools run as separate stdio processes. MCPServerConfig dataclass wraps JSON config. Server lifecycle managed by core/agent_runtime/tools/mcp.py.

4. Dual UI Strategy

• Docker (default): production deployment
• Local: --local flag runs FastAPI backend + Vite frontend
• Streamlit: --classic for quick prototyping

Contribution Opportunities

Area	Difficulty	Impact
Add type hints to workflows/	Easy	High
Migrate setup.py → pyproject.toml	Easy	Medium
Add integration tests for provider registry	Medium	High
Implement retry/failover in LLM runtime	Medium	High
Add streaming support to CLI	Medium	Medium
Docker multi-stage build optimization	Medium	Low

PRs Made

• #6 — CI modernization + test matrix + Makefile

Source

• Original: HKUDS/DeepCode (15.7k ⭐)
• Fork: whitehat-bot/automatic-potato