# joeydd032995-pixel/self-morphing-adaptive-recursion-engine architecture

> Architecture diagram of the GitHub repository joeydd032995-pixel/self-morphing-adaptive-recursion-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine
- Repository: https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine

## Overview

The product is a hybrid neurosymbolic reasoning engine exposed through a CLI and authenticated FastAPI service. A typical user submits a query, which the engine can plan through knowledge-graph hops and verify before returning a result; documents can also be ingested for retrieval-grounded reasoning. The authoritative engine contains morphic execution, RAG, knowledge-graph, self-teaching, and GNN capabilities. Edges reflect only calls or relationships shown in the excerpts or README; unsampled subsystem internals are represented at the engine path.

Main entry points: [`organized_self_morphing_engine.py`](https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py) (Adaptive engine), [`cli.py`](https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/cli.py) (CLI), [`fastapi_server.py`](https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/fastapi_server.py) (FastAPI service), [`semantic_cache.py`](https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/semantic_cache.py) (Semantic cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surface["User Interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_api["FastAPI service<br/>[fastapi_server.py]"]
end

subgraph group_reasoning["Reasoning Engine"]
  node_engine["Adaptive engine"]
  node_morphic["Morphic execution"]
  node_similarity["Hybrid similarity"]
  node_pog["PoG planning"]
  node_verification["Verification and audit"]
end

subgraph group_knowledge["Knowledge and Retrieval"]
  node_rag["RAG retrieval"]
  node_ingest["Document ingestion"]
  node_kg[("Knowledge graph")]
end

subgraph group_learning["Learning and Models"]
  node_teaching["Self-teaching"]
  node_gnn["Learned GNN"]
end

subgraph group_state["Persistence"]
  node_cache[("Semantic cache<br/>[semantic_cache.py]")]
  node_sqlite[("SQLite engine store")]
end

node_user(("User"))
node_neo4j[("Neo4j")]
node_llm["LLM provider"]

node_user -->|"runs command"| node_cli
node_cli -->|"dispatches to"| node_engine
node_user -->|"sends request"| node_api
node_api -->|"calls engine"| node_engine
node_engine -->|"executes nodes"| node_morphic
node_engine -->|"scores queries"| node_similarity
node_engine -->|"plans reasoning"| node_pog
node_pog -->|"explores hops"| node_kg
node_pog -->|"reflects through"| node_verification
node_engine -->|"retrieves context"| node_rag
node_engine -->|"ingests documents"| node_ingest
node_ingest -->|"seeds entities"| node_kg
node_engine -->|"syncs graph"| node_kg
node_kg -.->|"syncs bidirectionally"| node_neo4j
node_engine -->|"runs teaching loop"| node_teaching
node_teaching -->|"validates proposals"| node_verification
node_teaching -->|"uses graph signals"| node_gnn
node_engine -->|"builds and trains"| node_gnn
node_engine -->|"gets and puts"| node_cache
node_engine -->|"persists engine state"| node_sqlite
node_engine -.->|"requests completions"| node_llm

click node_cli "https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/cli.py"
click node_api "https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/fastapi_server.py"
click node_engine "https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py"
click node_morphic "https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py"
click node_similarity "https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py"
click node_pog "https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py"
click node_verification "https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py"
click node_rag "https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py"
click node_ingest "https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py"
click node_kg "https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py"
click node_teaching "https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py"
click node_gnn "https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py"
click node_cache "https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/semantic_cache.py"
click node_sqlite "https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.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_api,node_user toneBlue
class node_engine,node_morphic,node_similarity,node_pog,node_verification,node_neo4j toneAmber
class node_rag,node_ingest,node_kg toneMint
class node_teaching,node_gnn toneRose
class node_cache,node_sqlite,node_llm toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/cli.py): `cli.py`
- [FastAPI service](https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/fastapi_server.py): `fastapi_server.py`

### Reasoning Engine

- [Adaptive engine](https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py): `organized_self_morphing_engine.py`
- [Morphic execution](https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py): `organized_self_morphing_engine.py`
- [Hybrid similarity](https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py): `organized_self_morphing_engine.py`
- [PoG planning](https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py): `organized_self_morphing_engine.py`
- [Verification and audit](https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py): `organized_self_morphing_engine.py`

### Knowledge and Retrieval

- [RAG retrieval](https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py): `organized_self_morphing_engine.py`
- [Document ingestion](https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py): `organized_self_morphing_engine.py`
- [Knowledge graph](https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py): `organized_self_morphing_engine.py`

### Learning and Models

- [Self-teaching](https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py): `organized_self_morphing_engine.py`
- [Learned GNN](https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py): `organized_self_morphing_engine.py`

### Persistence

- [Semantic cache](https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/semantic_cache.py): `semantic_cache.py`
- [SQLite engine store](https://github.com/joeydd032995-pixel/self-morphing-adaptive-recursion-engine/blob/main/organized_self_morphing_engine.py): `organized_self_morphing_engine.py`

### Other components

- **User**
- **Neo4j**
- **LLM provider**

## Connections

- User → CLI: runs command (evidence: `cli.py`)
- CLI → Adaptive engine: dispatches to (evidence: `cli.py`)
- User → FastAPI service: sends request (evidence: `fastapi_server.py`)
- FastAPI service → Adaptive engine: calls engine (evidence: `fastapi_server.py`)
- Adaptive engine → Morphic execution: executes nodes (evidence: `README.md`)
- Adaptive engine → Hybrid similarity: scores queries (evidence: `README.md`)
- Adaptive engine → PoG planning: plans reasoning (evidence: `fastapi_server.py`)
- PoG planning → Knowledge graph: explores hops (evidence: `README.md`)
- PoG planning → Verification and audit: reflects through (evidence: `organized_self_morphing_engine.py`)
- Adaptive engine → RAG retrieval: retrieves context (evidence: `fastapi_server.py`)
- Adaptive engine → Document ingestion: ingests documents (evidence: `cli.py`)
- Document ingestion → Knowledge graph: seeds entities (evidence: `README.md`)
- Adaptive engine → Knowledge graph: syncs graph (evidence: `README.md`)
- Knowledge graph → Neo4j: syncs bidirectionally (evidence: `README.md`)
- Adaptive engine → Self-teaching: runs teaching loop (evidence: `cli.py`)
- Self-teaching → Verification and audit: validates proposals (evidence: `README.md`)
- Self-teaching → Learned GNN: uses graph signals (evidence: `README.md`)
- Adaptive engine → Learned GNN: builds and trains (evidence: `README.md`)
- Adaptive engine → Semantic cache: gets and puts (evidence: `organized_self_morphing_engine.py`)
- Adaptive engine → SQLite engine store: persists engine state (evidence: `organized_self_morphing_engine.py`)
- Adaptive engine → LLM provider: requests completions (evidence: `README.md`)
