# americashowspy-create/hybrid-engine architecture

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

- Interactive diagram: https://gitdiagram.com/americashowspy-create/hybrid-engine
- Repository: https://github.com/americashowspy-create/hybrid-engine

## Overview

Hybrid Engine is an agent-independent software review framework: it combines portable human/agent protocols with an optional Python CLI for bounded, read-only analysis and permissioned GitHub workflows. The main path is a user request through workflow planning and target inspection, into findings and coverage reporting, then prioritized advice; any code change is a separately authorized, reviewable proposal. The graph also preserves evidence import, large-project coverage, and GitHub task and verification capabilities. Links reflect the excerpts, SOURCE INDEX references, or README; unsampled implementation details are not inferred.

Main entry points: [`hybrid_engine/cli.py`](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/cli.py) (Python CLI), [`hybrid_engine/assessment.py`](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/assessment.py) (Assessment), [`hybrid_engine/agent_bridge.py`](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/agent_bridge.py) (Agent Bridge), [`hybrid_engine/github_adapter.py`](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/github_adapter.py) (GitHub Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow Planning"]
  node_cli["Python CLI<br/>[cli.py]"]
  node_planner["Flow Planner<br/>[core.py]"]
  node_runner["Local Runner<br/>[runner.py]"]
  node_state[("Workflow State<br/>[store.py]")]
end

subgraph group_analysis["Static Analysis"]
  node_enumeration["Tree Enumeration<br/>[enumeration.py]"]
  node_sourceio["Safe Source Reads<br/>[source_io.py]"]
  node_audit["Code Audit<br/>[audit.py]"]
  node_dbguard["Database Heuristics<br/>[db_guard.py]"]
  node_structure["Structure Analysis<br/>[structure.py]"]
end

subgraph group_evidence["Findings and Evidence"]
  node_assessment["Assessment<br/>[assessment.py]"]
  node_workspace["Workspace Batches<br/>[workspace_audit.py]"]
  node_advisor["Implementation Advice<br/>[advisor.py]"]
  node_evidenceimport["Evidence Import<br/>[evidence_bridge.py]"]
  node_reports["Report I/O<br/>[report_io.py]"]
end

subgraph group_agent["Agent Handoff"]
  node_handoff["Agent Bridge<br/>[agent_bridge.py]"]
  node_packages["Chat Packages<br/>[chat_package.py]"]
end

subgraph group_github["GitHub Operations"]
  node_adapter["GitHub Adapter<br/>[github_adapter.py]"]
  node_taskboard[("Task Journal<br/>[taskboard.py]")]
  node_executor["Change Executor<br/>[auto_executor.py]"]
  node_verification["PR Verification<br/>[verification.py]"]
end

node_user(("User"))
node_target["Target Project"]
node_agent(("AI Agent"))
node_github["GitHub API"]

node_user -->|"submits request"| node_cli
node_cli -->|"plans flow"| node_planner
node_cli -->|"dispatches workflow"| node_runner
node_cli -->|"runs assessment"| node_assessment
node_cli -->|"runs DB scan"| node_dbguard
node_cli -->|"runs large audits"| node_workspace
node_cli -->|"generates advice"| node_advisor
node_cli -->|"imports evidence"| node_evidenceimport
node_cli -->|"dispatches GitHub flow"| node_handoff
node_cli -->|"dispatches tasks"| node_taskboard
node_cli -->|"dispatches verification"| node_verification
node_cli -->|"selects target"| node_target
node_cli -->|"reads or writes state"| node_state
node_assessment -->|"combines findings"| node_audit
node_assessment -->|"combines findings"| node_dbguard
node_assessment -->|"analyzes structure"| node_structure
node_audit -->|"enumerates files"| node_enumeration
node_dbguard -->|"enumerates files"| node_enumeration
node_enumeration -->|"opens directories"| node_sourceio
node_audit -->|"reads source"| node_sourceio
node_dbguard -->|"reads source"| node_sourceio
node_assessment -->|"scans target"| node_target
node_workspace -->|"repeats in batches"| node_assessment
node_workspace -->|"consolidates advice"| node_advisor
node_advisor -->|"prioritizes findings"| node_assessment
node_evidenceimport -->|"normalizes evidence"| node_assessment
node_assessment -->|"serializes report"| node_reports
node_advisor -->|"formats advice"| node_reports
node_agent -->|"requests handoff"| node_handoff
node_handoff -->|"requests remote audit"| node_adapter
node_adapter -->|"calls API"| node_github
node_handoff -->|"creates work order"| node_planner
node_packages -->|"packages handoff"| node_handoff
node_packages -->|"uses GitHub adapter"| node_adapter
node_taskboard -->|"journals tasks"| node_github
node_executor -->|"proposes changes"| node_adapter
node_verification -->|"checks pull request"| node_adapter

click node_cli "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/cli.py"
click node_planner "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/core.py"
click node_runner "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/runner.py"
click node_state "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/store.py"
click node_enumeration "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/enumeration.py"
click node_sourceio "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/source_io.py"
click node_audit "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/audit.py"
click node_dbguard "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/db_guard.py"
click node_structure "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/structure.py"
click node_assessment "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/assessment.py"
click node_workspace "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/workspace_audit.py"
click node_advisor "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/advisor.py"
click node_evidenceimport "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/evidence_bridge.py"
click node_reports "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/report_io.py"
click node_handoff "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/agent_bridge.py"
click node_packages "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/chat_package.py"
click node_adapter "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/github_adapter.py"
click node_taskboard "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/taskboard.py"
click node_executor "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/auto_executor.py"
click node_verification "https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/verification.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_cli,node_planner,node_runner,node_state,node_user toneBlue
class node_enumeration,node_sourceio,node_audit,node_dbguard,node_structure toneAmber
class node_assessment,node_workspace,node_advisor,node_evidenceimport,node_reports,node_github toneMint
class node_handoff,node_packages toneRose
class node_adapter,node_taskboard,node_executor,node_verification,node_target,node_agent toneIndigo
```

## Components

### Workflow Planning

- [Python CLI](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/cli.py): `hybrid_engine/cli.py`
- [Flow Planner](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/core.py): `hybrid_engine/core.py`
- [Local Runner](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/runner.py): `hybrid_engine/runner.py`
- [Workflow State](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/store.py): `hybrid_engine/store.py`

### Static Analysis

- [Tree Enumeration](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/enumeration.py): `hybrid_engine/enumeration.py`
- [Safe Source Reads](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/source_io.py): `hybrid_engine/source_io.py`
- [Code Audit](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/audit.py): `hybrid_engine/audit.py`
- [Database Heuristics](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/db_guard.py): `hybrid_engine/db_guard.py`
- [Structure Analysis](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/structure.py): `hybrid_engine/structure.py`

### Findings and Evidence

- [Assessment](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/assessment.py): `hybrid_engine/assessment.py`
- [Workspace Batches](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/workspace_audit.py): `hybrid_engine/workspace_audit.py`
- [Implementation Advice](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/advisor.py): `hybrid_engine/advisor.py`
- [Evidence Import](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/evidence_bridge.py): `hybrid_engine/evidence_bridge.py`
- [Report I/O](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/report_io.py): `hybrid_engine/report_io.py`

### Agent Handoff

- [Agent Bridge](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/agent_bridge.py): `hybrid_engine/agent_bridge.py`
- [Chat Packages](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/chat_package.py): `hybrid_engine/chat_package.py`

### GitHub Operations

- [GitHub Adapter](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/github_adapter.py): `hybrid_engine/github_adapter.py`
- [Task Journal](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/taskboard.py): `hybrid_engine/taskboard.py`
- [Change Executor](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/auto_executor.py): `hybrid_engine/auto_executor.py`
- [PR Verification](https://github.com/americashowspy-create/hybrid-engine/blob/main/hybrid_engine/verification.py): `hybrid_engine/verification.py`

### Other components

- **User**
- **Target Project**
- **AI Agent**
- **GitHub API**

## Connections

- User → Python CLI: submits request (evidence: `README.md`)
- Python CLI → Flow Planner: plans flow (evidence: `hybrid_engine/cli.py`)
- Python CLI → Local Runner: dispatches workflow (evidence: `hybrid_engine/cli.py`)
- Python CLI → Assessment: runs assessment (evidence: `hybrid_engine/cli.py`)
- Python CLI → Database Heuristics: runs DB scan (evidence: `hybrid_engine/cli.py`)
- Python CLI → Workspace Batches: runs large audits (evidence: `hybrid_engine/cli.py`)
- Python CLI → Implementation Advice: generates advice (evidence: `hybrid_engine/cli.py`)
- Python CLI → Evidence Import: imports evidence (evidence: `hybrid_engine/cli.py`)
- Python CLI → Agent Bridge: dispatches GitHub flow (evidence: `hybrid_engine/cli.py`)
- Python CLI → Task Journal: dispatches tasks (evidence: `hybrid_engine/cli.py`)
- Python CLI → PR Verification: dispatches verification (evidence: `hybrid_engine/cli.py`)
- Python CLI → Target Project: selects target (evidence: `hybrid_engine/cli.py`)
- Python CLI → Workflow State: reads or writes state (evidence: `hybrid_engine/cli.py`)
- Assessment → Code Audit: combines findings (evidence: `hybrid_engine/assessment.py`)
- Assessment → Database Heuristics: combines findings (evidence: `hybrid_engine/assessment.py`)
- Assessment → Structure Analysis: analyzes structure (evidence: `hybrid_engine/assessment.py`)
- Code Audit → Tree Enumeration: enumerates files (evidence: `hybrid_engine/audit.py`)
- Database Heuristics → Tree Enumeration: enumerates files (evidence: `hybrid_engine/db_guard.py`)
- Tree Enumeration → Safe Source Reads: opens directories (evidence: `hybrid_engine/enumeration.py`)
- Code Audit → Safe Source Reads: reads source (evidence: `hybrid_engine/audit.py`)
- Database Heuristics → Safe Source Reads: reads source (evidence: `hybrid_engine/db_guard.py`)
- Assessment → Target Project: scans target (evidence: `README.md`)
- Workspace Batches → Assessment: repeats in batches (evidence: `hybrid_engine/workspace_audit.py`)
- Workspace Batches → Implementation Advice: consolidates advice (evidence: `hybrid_engine/workspace_audit.py`)
- Implementation Advice → Assessment: prioritizes findings (evidence: `hybrid_engine/advisor.py`)
- Evidence Import → Assessment: normalizes evidence (evidence: `hybrid_engine/evidence_bridge.py`)
- Assessment → Report I/O: serializes report (evidence: `hybrid_engine/report_io.py`)
- Implementation Advice → Report I/O: formats advice (evidence: `hybrid_engine/advisor.py`)
- AI Agent → Agent Bridge: requests handoff (evidence: `README.md`)
- Agent Bridge → GitHub Adapter: requests remote audit (evidence: `hybrid_engine/agent_bridge.py`)
- GitHub Adapter → GitHub API: calls API (evidence: `hybrid_engine/github_adapter.py`)
- Agent Bridge → Flow Planner: creates work order (evidence: `hybrid_engine/agent_bridge.py`)
- Chat Packages → Agent Bridge: packages handoff (evidence: `hybrid_engine/chat_package.py`)
- Chat Packages → GitHub Adapter: uses GitHub adapter (evidence: `hybrid_engine/chat_package.py`)
- Task Journal → GitHub API: journals tasks (evidence: `hybrid_engine/taskboard.py`)
- Change Executor → GitHub Adapter: proposes changes (evidence: `hybrid_engine/auto_executor.py`)
- PR Verification → GitHub Adapter: checks pull request (evidence: `hybrid_engine/verification.py`)
