# seratul03/evocode architecture

> Architecture diagram of the GitHub repository seratul03/evocode, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/seratul03/evocode
- Repository: https://github.com/seratul03/evocode

## Overview

EvoCode turns a programming problem into candidate code, evaluates it in a sandbox, and uses population evolution and feedback to improve results. Its autonomous and chat entry points lead into the evolution engine; the evaluation layer coordinates generation, review, testing, and scoring. A separate meta-evolution branch monitors performance and proposes upgrades to the system’s agents. The README documents these capabilities, while excerpts and the source index provide only partial implementation evidence, so unsampled relationships are omitted where they cannot be established.

Main entry points: [`src/evoflow.py`](https://github.com/seratul03/evocode/blob/main/src/evoflow.py) (Evolution engine), [`src/orchestration/evaluator.py`](https://github.com/seratul03/evocode/blob/main/src/orchestration/evaluator.py) (Population evaluator), [`src/client.py`](https://github.com/seratul03/evocode/blob/main/src/client.py) (LLM client), [`src/meta_evolution/clone_builder.py`](https://github.com/seratul03/evocode/blob/main/src/meta_evolution/clone_builder.py) (Clone builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Problem solving"]
  node_autonomous["Autonomous runner<br/>[run_autonomous.py]"]
  node_chat["Interactive chat<br/>[chat.py]"]
  node_flow["Evolution engine<br/>[evoflow.py]"]
end

subgraph group_agents["Code agents"]
  node_generator["Code generator<br/>[generator.py]"]
  node_architect["Solution architect<br/>[architect.py]"]
  node_reviewer["Code reviewer<br/>[reviewer.py]"]
  node_bugfixer["Bug fixer<br/>[bugfixer.py]"]
  node_optimizer["Code optimizer<br/>[optimizer.py]"]
  node_mutator["Genetic mutator<br/>[mutator.py]"]
  node_memoryagent["Memory historian<br/>[memory_agent.py]"]
end

subgraph group_runtime["Evaluation runtime"]
  node_evaluator["Population evaluator<br/>[evaluator.py]"]
  node_genome["Agent genome<br/>[genome.py]"]
  node_sandbox["Docker sandbox<br/>[sandbox.py]"]
  node_fitness["Fitness scoring<br/>[fitness_scorer.py]"]
  node_property["Property testing<br/>[property_tester.py]"]
  node_logger["Run event logger<br/>[event_logger.py]"]
  node_memory[("Evolution memory<br/>[memory_manager.py]")]
end

subgraph group_meta["Meta-evolution"]
  node_watcher["Performance watcher<br/>[watcher.py]"]
  node_clonebuilder["Clone builder<br/>[clone_builder.py]"]
  node_judge["Patch judge<br/>[source_judge.py]"]
  node_referee["Safety referee<br/>[referee.py]"]
  node_metaarena["Fast duel arena<br/>[meta_arena.py]"]
end

subgraph group_llm["LLM access"]
  node_client["LLM client<br/>[client.py]"]
  node_ollama["Ollama provider<br/>[ollama_provider.py]"]
  node_groq["Groq provider<br/>[groq_provider.py]"]
  node_openrouter["OpenRouter provider"]
end

node_user(("User"))
node_llmservice(("LLM services"))

node_user -->|"starts run"| node_autonomous
node_user -->|"starts chat"| node_chat
node_autonomous -->|"runs evolution"| node_flow
node_chat -.->|"solves problems"| node_flow
node_flow -->|"evaluates population"| node_evaluator
node_evaluator -.->|"generates code"| node_generator
node_evaluator -->|"reviews code"| node_reviewer
node_evaluator -->|"checks optimization"| node_optimizer
node_evaluator -->|"generates tests"| node_property
node_evaluator -.->|"executes candidates"| node_sandbox
node_evaluator -.->|"scores results"| node_fitness
node_flow -.->|"plans solutions"| node_architect
node_flow -.->|"repairs failures"| node_bugfixer
node_flow -.->|"mutates candidates"| node_mutator
node_flow -.->|"uses experience"| node_memoryagent
node_flow -->|"records events"| node_logger
node_flow -.->|"evolves agents"| node_genome
node_flow -->|"triggers upgrades"| node_watcher
node_watcher -->|"requests patch"| node_clonebuilder
node_clonebuilder -.->|"proposes changes"| node_judge
node_clonebuilder -.->|"checks safety"| node_referee
node_clonebuilder -.->|"tests candidates"| node_metaarena
node_flow -.->|"records lineage"| node_memory
node_generator -.->|"requests completion"| node_client
node_reviewer -->|"requests review"| node_client
node_client -->|"tries first"| node_ollama
node_client -->|"falls back"| node_groq
node_client -->|"falls back"| node_openrouter
node_ollama -.->|"calls model"| node_llmservice
node_groq -.->|"calls model"| node_llmservice
node_openrouter -.->|"calls model"| node_llmservice

click node_autonomous "https://github.com/seratul03/evocode/blob/main/run_autonomous.py"
click node_chat "https://github.com/seratul03/evocode/blob/main/chat.py"
click node_flow "https://github.com/seratul03/evocode/blob/main/src/evoflow.py"
click node_evaluator "https://github.com/seratul03/evocode/blob/main/src/orchestration/evaluator.py"
click node_genome "https://github.com/seratul03/evocode/blob/main/src/genome.py"
click node_generator "https://github.com/seratul03/evocode/blob/main/src/agents/generator.py"
click node_architect "https://github.com/seratul03/evocode/blob/main/src/agents/architect.py"
click node_reviewer "https://github.com/seratul03/evocode/blob/main/src/agents/reviewer.py"
click node_bugfixer "https://github.com/seratul03/evocode/blob/main/src/agents/bugfixer.py"
click node_optimizer "https://github.com/seratul03/evocode/blob/main/src/agents/optimizer.py"
click node_mutator "https://github.com/seratul03/evocode/blob/main/src/agents/mutator.py"
click node_memoryagent "https://github.com/seratul03/evocode/blob/main/src/agents/memory_agent.py"
click node_sandbox "https://github.com/seratul03/evocode/blob/main/src/sandbox.py"
click node_fitness "https://github.com/seratul03/evocode/blob/main/src/fitness_scorer.py"
click node_property "https://github.com/seratul03/evocode/blob/main/src/property_tester.py"
click node_logger "https://github.com/seratul03/evocode/blob/main/src/event_logger.py"
click node_memory "https://github.com/seratul03/evocode/blob/main/src/memory_manager.py"
click node_watcher "https://github.com/seratul03/evocode/blob/main/src/meta_evolution/watcher.py"
click node_clonebuilder "https://github.com/seratul03/evocode/blob/main/src/meta_evolution/clone_builder.py"
click node_judge "https://github.com/seratul03/evocode/blob/main/src/meta_evolution/source_judge.py"
click node_referee "https://github.com/seratul03/evocode/blob/main/src/meta_evolution/referee.py"
click node_metaarena "https://github.com/seratul03/evocode/blob/main/src/meta_evolution/meta_arena.py"
click node_client "https://github.com/seratul03/evocode/blob/main/src/client.py"
click node_ollama "https://github.com/seratul03/evocode/blob/main/src/llm/ollama_provider.py"
click node_groq "https://github.com/seratul03/evocode/blob/main/src/llm/groq_provider.py"
click node_openrouter "https://github.com/seratul03/evocode/blob/main/src/llm/openrouter_provider.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_autonomous,node_chat,node_flow,node_user toneBlue
class node_generator,node_architect,node_reviewer,node_bugfixer,node_optimizer,node_mutator,node_memoryagent toneAmber
class node_evaluator,node_genome,node_sandbox,node_fitness,node_property,node_logger,node_memory toneMint
class node_watcher,node_clonebuilder,node_judge,node_referee,node_metaarena toneRose
class node_client,node_ollama,node_groq,node_openrouter,node_llmservice toneIndigo
```

## Components

### Problem solving

- [Autonomous runner](https://github.com/seratul03/evocode/blob/main/run_autonomous.py): `run_autonomous.py`
- [Interactive chat](https://github.com/seratul03/evocode/blob/main/chat.py): `chat.py`
- [Evolution engine](https://github.com/seratul03/evocode/blob/main/src/evoflow.py): `src/evoflow.py`

### Code agents

- [Code generator](https://github.com/seratul03/evocode/blob/main/src/agents/generator.py): `src/agents/generator.py`
- [Solution architect](https://github.com/seratul03/evocode/blob/main/src/agents/architect.py): `src/agents/architect.py`
- [Code reviewer](https://github.com/seratul03/evocode/blob/main/src/agents/reviewer.py): `src/agents/reviewer.py`
- [Bug fixer](https://github.com/seratul03/evocode/blob/main/src/agents/bugfixer.py): `src/agents/bugfixer.py`
- [Code optimizer](https://github.com/seratul03/evocode/blob/main/src/agents/optimizer.py): `src/agents/optimizer.py`
- [Genetic mutator](https://github.com/seratul03/evocode/blob/main/src/agents/mutator.py): `src/agents/mutator.py`
- [Memory historian](https://github.com/seratul03/evocode/blob/main/src/agents/memory_agent.py): `src/agents/memory_agent.py`

### Evaluation runtime

- [Population evaluator](https://github.com/seratul03/evocode/blob/main/src/orchestration/evaluator.py): `src/orchestration/evaluator.py`
- [Agent genome](https://github.com/seratul03/evocode/blob/main/src/genome.py): `src/genome.py`
- [Docker sandbox](https://github.com/seratul03/evocode/blob/main/src/sandbox.py): `src/sandbox.py`
- [Fitness scoring](https://github.com/seratul03/evocode/blob/main/src/fitness_scorer.py): `src/fitness_scorer.py`
- [Property testing](https://github.com/seratul03/evocode/blob/main/src/property_tester.py): `src/property_tester.py`
- [Run event logger](https://github.com/seratul03/evocode/blob/main/src/event_logger.py): `src/event_logger.py`
- [Evolution memory](https://github.com/seratul03/evocode/blob/main/src/memory_manager.py): `src/memory_manager.py`

### Meta-evolution

- [Performance watcher](https://github.com/seratul03/evocode/blob/main/src/meta_evolution/watcher.py): `src/meta_evolution/watcher.py`
- [Clone builder](https://github.com/seratul03/evocode/blob/main/src/meta_evolution/clone_builder.py): `src/meta_evolution/clone_builder.py`
- [Patch judge](https://github.com/seratul03/evocode/blob/main/src/meta_evolution/source_judge.py): `src/meta_evolution/source_judge.py`
- [Safety referee](https://github.com/seratul03/evocode/blob/main/src/meta_evolution/referee.py): `src/meta_evolution/referee.py`
- [Fast duel arena](https://github.com/seratul03/evocode/blob/main/src/meta_evolution/meta_arena.py): `src/meta_evolution/meta_arena.py`

### LLM access

- [LLM client](https://github.com/seratul03/evocode/blob/main/src/client.py): `src/client.py`
- [Ollama provider](https://github.com/seratul03/evocode/blob/main/src/llm/ollama_provider.py): `src/llm/ollama_provider.py`
- [Groq provider](https://github.com/seratul03/evocode/blob/main/src/llm/groq_provider.py): `src/llm/groq_provider.py`
- [OpenRouter provider](https://github.com/seratul03/evocode/blob/main/src/llm/openrouter_provider.py): `src/llm/openrouter_provider.py`

### Other components

- **User**
- **LLM services**

## Connections

- User → Autonomous runner: starts run (evidence: `README.md`)
- User → Interactive chat: starts chat (evidence: `README.md`)
- Autonomous runner → Evolution engine: runs evolution (evidence: `run_autonomous.py`)
- Interactive chat → Evolution engine: solves problems
- Evolution engine → Population evaluator: evaluates population (evidence: `src/orchestration/evaluator.py`)
- Population evaluator → Code generator: generates code
- Population evaluator → Code reviewer: reviews code (evidence: `src/orchestration/evaluator.py`)
- Population evaluator → Code optimizer: checks optimization (evidence: `src/orchestration/evaluator.py`)
- Population evaluator → Property testing: generates tests (evidence: `src/orchestration/evaluator.py`)
- Population evaluator → Docker sandbox: executes candidates
- Population evaluator → Fitness scoring: scores results
- Evolution engine → Solution architect: plans solutions (evidence: `src/evoflow.py`)
- Evolution engine → Bug fixer: repairs failures (evidence: `src/evoflow.py`)
- Evolution engine → Genetic mutator: mutates candidates (evidence: `src/evoflow.py`)
- Evolution engine → Memory historian: uses experience
- Evolution engine → Run event logger: records events (evidence: `src/evoflow.py`)
- Evolution engine → Agent genome: evolves agents (evidence: `src/evoflow.py`)
- Evolution engine → Performance watcher: triggers upgrades (evidence: `run_autonomous.py`)
- Performance watcher → Clone builder: requests patch (evidence: `src/meta_evolution/__init__.py`)
- Clone builder → Patch judge: proposes changes
- Clone builder → Safety referee: checks safety
- Clone builder → Fast duel arena: tests candidates
- Evolution engine → Evolution memory: records lineage
- Code generator → LLM client: requests completion
- Code reviewer → LLM client: requests review (evidence: `src/agents/reviewer.py`)
- LLM client → Ollama provider: tries first (evidence: `src/client.py`)
- LLM client → Groq provider: falls back (evidence: `src/client.py`)
- LLM client → OpenRouter provider: falls back (evidence: `src/client.py`)
- Ollama provider → LLM services: calls model
- Groq provider → LLM services: calls model
- OpenRouter provider → LLM services: calls model
