# myers404/demo-engine architecture

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

- Interactive diagram: https://gitdiagram.com/myers404/demo-engine
- Repository: https://github.com/myers404/demo-engine

## Overview

Demo Engine interprets YAML-defined state, schemas, and tool actions. Its main workflow is to load and validate a demo definition, create in-memory session state, execute a requested tool against a copy of that state, validate the result, and return the new state and result. The MCP adapter exposes configured tools over stdio and commits state only after successful execution. The engine is concentrated in one source file, so several nodes represent distinct responsibilities within that file; the graph does not assume persistence or multi-user hosting.

Main entry points: [`src/demo_engine/engine.py`](https://github.com/myers404/demo-engine/blob/main/src/demo_engine/engine.py) (Tool Executor), [`src/demo_engine/mcp_server.py`](https://github.com/myers404/demo-engine/blob/main/src/demo_engine/mcp_server.py) (MCP Server), [`examples/commerce_demo.yaml`](https://github.com/myers404/demo-engine/blob/main/examples/commerce_demo.yaml) (Demo YAML)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_definition["Demo Definition"]
  node_demo_yaml["Demo YAML<br/>[commerce_demo.yaml]"]
  node_config_loader["Config Loader<br/>[engine.py]"]
end

subgraph group_engine["Execution Engine"]
  node_schema_validation["Schema Validation<br/>[engine.py]"]
  node_session_state[("Session State<br/>[engine.py]")]
  node_tool_executor["Tool Executor<br/>[engine.py]"]
  node_action_interpreter["Action Interpreter<br/>[engine.py]"]
  node_selector["Collection Selector<br/>[engine.py]"]
  node_reference_resolver["Reference Resolver<br/>[engine.py]"]
end

subgraph group_mcp["MCP Runtime"]
  node_mcp_server["MCP Server<br/>[mcp_server.py]"]
  node_tool_registry["Tool Registry<br/>[mcp_server.py]"]
  node_stdio_transport["stdio Transport<br/>[mcp_server.py]"]
end

node_python_caller(("Python Caller"))
node_mcp_host(("MCP Host"))

node_demo_yaml -->|"defines config"| node_config_loader
node_python_caller -->|"loads config"| node_config_loader
node_config_loader -->|"validates schemas"| node_schema_validation
node_python_caller -->|"executes tool"| node_tool_executor
node_tool_executor -->|"validates input and state"| node_schema_validation
node_tool_executor -->|"copies and updates"| node_session_state
node_tool_executor -->|"runs action"| node_action_interpreter
node_action_interpreter -->|"selects matches"| node_selector
node_action_interpreter -->|"resolves values"| node_reference_resolver
node_tool_executor -->|"resolves result"| node_reference_resolver
node_tool_executor -->|"validates output"| node_schema_validation
node_mcp_host -->|"connects over stdio"| node_stdio_transport
node_stdio_transport -->|"routes MCP requests"| node_mcp_server
node_mcp_server -->|"loads definition"| node_config_loader
node_mcp_server -->|"lists configured tools"| node_tool_registry
node_mcp_server -->|"executes tool calls"| node_tool_executor
node_mcp_server -->|"commits next state"| node_session_state

click node_demo_yaml "https://github.com/myers404/demo-engine/blob/main/examples/commerce_demo.yaml"
click node_config_loader "https://github.com/myers404/demo-engine/blob/main/src/demo_engine/engine.py"
click node_schema_validation "https://github.com/myers404/demo-engine/blob/main/src/demo_engine/engine.py"
click node_session_state "https://github.com/myers404/demo-engine/blob/main/src/demo_engine/engine.py"
click node_tool_executor "https://github.com/myers404/demo-engine/blob/main/src/demo_engine/engine.py"
click node_action_interpreter "https://github.com/myers404/demo-engine/blob/main/src/demo_engine/engine.py"
click node_selector "https://github.com/myers404/demo-engine/blob/main/src/demo_engine/engine.py"
click node_reference_resolver "https://github.com/myers404/demo-engine/blob/main/src/demo_engine/engine.py"
click node_mcp_server "https://github.com/myers404/demo-engine/blob/main/src/demo_engine/mcp_server.py"
click node_tool_registry "https://github.com/myers404/demo-engine/blob/main/src/demo_engine/mcp_server.py"
click node_stdio_transport "https://github.com/myers404/demo-engine/blob/main/src/demo_engine/mcp_server.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_demo_yaml,node_config_loader toneBlue
class node_schema_validation,node_session_state,node_tool_executor,node_action_interpreter,node_selector,node_reference_resolver toneAmber
class node_mcp_server,node_tool_registry,node_stdio_transport toneMint
class node_python_caller,node_mcp_host toneIndigo
```

## Components

### Demo Definition

- [Demo YAML](https://github.com/myers404/demo-engine/blob/main/examples/commerce_demo.yaml): `examples/commerce_demo.yaml`
- [Config Loader](https://github.com/myers404/demo-engine/blob/main/src/demo_engine/engine.py): `src/demo_engine/engine.py`

### Execution Engine

- [Schema Validation](https://github.com/myers404/demo-engine/blob/main/src/demo_engine/engine.py): `src/demo_engine/engine.py`
- [Session State](https://github.com/myers404/demo-engine/blob/main/src/demo_engine/engine.py): `src/demo_engine/engine.py`
- [Tool Executor](https://github.com/myers404/demo-engine/blob/main/src/demo_engine/engine.py): `src/demo_engine/engine.py`
- [Action Interpreter](https://github.com/myers404/demo-engine/blob/main/src/demo_engine/engine.py): `src/demo_engine/engine.py`
- [Collection Selector](https://github.com/myers404/demo-engine/blob/main/src/demo_engine/engine.py): `src/demo_engine/engine.py`
- [Reference Resolver](https://github.com/myers404/demo-engine/blob/main/src/demo_engine/engine.py): `src/demo_engine/engine.py`

### MCP Runtime

- [MCP Server](https://github.com/myers404/demo-engine/blob/main/src/demo_engine/mcp_server.py): `src/demo_engine/mcp_server.py`
- [Tool Registry](https://github.com/myers404/demo-engine/blob/main/src/demo_engine/mcp_server.py): `src/demo_engine/mcp_server.py`
- [stdio Transport](https://github.com/myers404/demo-engine/blob/main/src/demo_engine/mcp_server.py): `src/demo_engine/mcp_server.py`

### Other components

- **Python Caller**
- **MCP Host**

## Connections

- Demo YAML → Config Loader: defines config (evidence: `README.md`)
- Python Caller → Config Loader: loads config (evidence: `README.md`)
- Config Loader → Schema Validation: validates schemas (evidence: `src/demo_engine/engine.py`)
- Python Caller → Tool Executor: executes tool (evidence: `README.md`)
- Tool Executor → Schema Validation: validates input and state (evidence: `src/demo_engine/engine.py`)
- Tool Executor → Session State: copies and updates (evidence: `src/demo_engine/engine.py`)
- Tool Executor → Action Interpreter: runs action (evidence: `src/demo_engine/engine.py`)
- Action Interpreter → Collection Selector: selects matches (evidence: `src/demo_engine/engine.py`)
- Action Interpreter → Reference Resolver: resolves values (evidence: `src/demo_engine/engine.py`)
- Tool Executor → Reference Resolver: resolves result (evidence: `src/demo_engine/engine.py`)
- Tool Executor → Schema Validation: validates output (evidence: `src/demo_engine/engine.py`)
- MCP Host → stdio Transport: connects over stdio (evidence: `README.md`)
- stdio Transport → MCP Server: routes MCP requests (evidence: `src/demo_engine/mcp_server.py`)
- MCP Server → Config Loader: loads definition (evidence: `src/demo_engine/mcp_server.py`)
- MCP Server → Tool Registry: lists configured tools (evidence: `src/demo_engine/mcp_server.py`)
- MCP Server → Tool Executor: executes tool calls (evidence: `src/demo_engine/mcp_server.py`)
- MCP Server → Session State: commits next state (evidence: `src/demo_engine/mcp_server.py`)
