# rwb3n/hephaestus architecture

> Architecture diagram of the GitHub repository rwb3n/hephaestus, 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/rwb3n/hephaestus
- Repository: https://github.com/rwb3n/hephaestus

## Overview

##### Project Type and Purpose
- Hephaestus is a recursive agent framework designed for self-constructing and self-modifying software. In essence, it is an autonomous build system that mutates, evaluates, and refines code on its own.

##### File Structure
- Several top-level directories correspond to key components:
- “engine”: Contains the core loop and control components (e.g., forge_loop/flow_builder, mutation engine, goal proposer). This is the heart of the system.
- “scoring”: Houses the test harness and evaluation logic. It’s responsible for scoring the generated code against defined metrics.
- “registry”: Manages a lineage-aware registry, tracking build artifacts and their ancestry.
- “nodes”: Acts as the output directory for generated Python modules (i.e., code artifacts).
- “services”: Provides integrations with external systems like LLMs (e.g., OpenAI API) and template rendering via Jinja.
- “config”: Contains runtime configuration files such as “forge_config.json” that drive operational parameters like entropy settings and thresholds.
- “docs”: A comprehensive documentation directory that supports both developers and future extensions.
- Additional directories like “tests”, “scripts”, and “drafts” which support testing, automation, and prototyping, respectively.
- There are multiple configuration and supporting files (e.g., .env examples, LICENSE, CHANGELOG) that imply attention to a robust production process.

##### Main Components and Their Relationships
a. Engine/Control Plane:
- Components in the “engine” directory drive the core forge loop, including modules for mutation (“mutation_engine.py”, “mutation.py”) and goal proposal (“goal_proposer.py”).
- They interact with other subsystems to propose new changes, monitor performance, and iterate the build process.
b. Scoring System:
- The “scoring” directory includes scripts for evaluating generated code via functional and structural metrics.
- This component feeds back into the engine to help select optimal variants.
c. Registry:
- The “registry” and “core” directories maintain a lineage-aware registry (with files like “registry.json” and “registry.py”) tracking ancestry and maintaining state.
d. Node Generation:
- The “nodes” directory represents the output artifacts (modular, generated code files) that result from the iterative build cycles.
e. External & Supporting Services:
- The “services” directory integrates with external APIs (OpenAI, llm_service, etc.) and includes template processing for code generation.
f. Configuration and Control:
- The “config” directory’s files define settings (e.g., constraints, thresholds) that the engine uses to control build iterations and safety (like the “emergency_stop.flag”).

##### Architectural Patterns and Design Principles
- The architecture is modular, with clear separations between code generation (engine, nodes), evaluation (scoring), and tracking (registry).
- It follows a recursive, self-refining pattern—a continuous cycle where the product of one cycle (nodes/artifacts) feeds into future iterations.
- Integration with an external LLM and usage of PocketFlow indicates plugin/extensibility patterns.

## Diagram (Mermaid)

```mermaid
graph TD
    run["Launcher (run.py)"]:::launcherStyle
    subgraph "Engine / Control Plane"
        engine["Engine"]:::engineStyle
        forge["Forge Loop"]:::engineStyle
        mutation["Mutation Engine"]:::engineStyle
        goal["Goal Proposer"]:::engineStyle
    end
    subgraph "Scoring System"
        scoring["Scoring Module"]:::scoringStyle
        test["Test Harness"]:::scoringStyle
    end
    subgraph "Registry"
        registry["Registry Management"]:::registryStyle
        regjson["Registry JSON"]:::registryStyle
    end
    subgraph "Node Generation"
        nodes["Nodes (Artifacts)"]:::nodesStyle
    end
    subgraph "External Services"
        llm["LLM Service"]:::servicesStyle
        template["Template Loader"]:::servicesStyle
    end
    subgraph "Configuration"
        config["Configuration"]:::configStyle
    end

    %% Relationships between high-level components
    run -->|"launches"| engine
    engine -->|"controls"| forge
    forge -->|"triggers"| mutation
    forge -->|"triggers"| goal
    engine -->|"generates"| nodes
    nodes -->|"feedback"| scoring
    scoring -->|"informs"| engine
    engine -->|"logs_to"| registry
    registry -->|"updates"| engine
    llm -->|"provides_data"| engine
    template -->|"provides_templates"| engine
    config -->|"configures"| engine

    %% Click Events
    click run "https://github.com/rwb3n/hephaestus/blob/main/run.py"
    click forge "https://github.com/rwb3n/hephaestus/blob/main/engine/forge_loop.py"
    click mutation "https://github.com/rwb3n/hephaestus/blob/main/engine/mutation_engine.py"
    click goal "https://github.com/rwb3n/hephaestus/blob/main/engine/goal_proposer.py"
    click scoring "https://github.com/rwb3n/hephaestus/blob/main/scoring/scoring.py"
    click test "https://github.com/rwb3n/hephaestus/blob/main/scoring/test_harness.py"
    click registry "https://github.com/rwb3n/hephaestus/blob/main/registry/registry.py"
    click regjson "https://github.com/rwb3n/hephaestus/blob/main/registry/registry.json"
    click nodes "https://github.com/rwb3n/hephaestus/blob/main/nodes/base_node.py"
    click llm "https://github.com/rwb3n/hephaestus/blob/main/services/llm_service.py"
    click template "https://github.com/rwb3n/hephaestus/blob/main/services/template_loader.py"
    click config "https://github.com/rwb3n/hephaestus/tree/main/config/forge_config_json"

    %% Styles
    classDef launcherStyle fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef engineStyle fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef scoringStyle fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef registryStyle fill:#D5F5E3,stroke:#1E8449,stroke-width:2px;
    classDef nodesStyle fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef servicesStyle fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef configStyle fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
```
