# phpclaw-php/phpclaw architecture

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

- Interactive diagram: https://gitdiagram.com/phpclaw-php/phpclaw
- Repository: https://github.com/phpclaw-php/phpclaw
- Video tour (about a minute): https://gitdiagram.com/phpclaw-php/phpclaw/video

## Overview

phpClaw is a framework-independent PHP agent engine. A caller builds a Claw and sends a message; invocation lifecycle code applies guards and hooks, then the Agent runs a bounded ReAct loop using a provider and available tools, returning an AgentResponse. Conversation persistence, memory recall, streaming, structured output, pipelines, graph execution, provider fallback, skills, and discovery are additional capabilities. Arrows are limited to relationships explicit in the README or visible in indexed/read excerpts; unsampled subsystem links are omitted.

Main entry points: [`src/Agent/Agent.php`](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Agent/Agent.php) (ReAct agent), [`src/Agent/InvocationPipeline.php`](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Agent/InvocationPipeline.php) (Invocation lifecycle), [`src/Claw.php`](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Claw.php) (Claw facade), [`src/Providers`](https://github.com/phpclaw-php/phpclaw/tree/0.x/src/Providers) (Provider adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Agent entry"]
  node_claw["Claw facade<br/>[Claw.php]"]
  node_response["Agent response<br/>[AgentResponse.php]"]
end

subgraph group_runtime["Agent runtime"]
  node_invocation["Invocation lifecycle"]
  node_guards["Input guards<br/>[GuardRegistry.php]"]
  node_agent["ReAct agent<br/>[Agent.php]"]
end

subgraph group_extensions["Agent capabilities"]
  node_structured["Structured output"]
  node_pipeline["Composable pipeline<br/>[Pipeline.php]"]
  node_pipeline_tool["Pipeline tool<br/>[PipelineTool.php]"]
  node_graph["Graph execution<br/>[Graph.php]"]
  node_skills["Skills"]
  node_discovery["Attribute discovery"]
end

subgraph group_integrations["Providers and tools"]
  node_provider["Provider adapters"]
  node_tool_registry["Tool registry<br/>[ToolRegistry.php]"]
  node_tool_router["Tool routing<br/>[ToolRouter.php]"]
  node_tool_impl["Built-in tools"]
  node_database_tool["Read-only SQL tool"]
  node_streaming["Streaming transport<br/>[StreamParser.php]"]
end

subgraph group_operations["State and events"]
  node_memory[("Memory drivers")]
  node_conversation["Conversation history<br/>[Conversation.php]"]
  node_hooks["Lifecycle hooks<br/>[HookDispatcher.php]"]
end

node_caller(("Application caller"))
node_external_llm(("LLM service"))
node_database[("Application database")]

node_caller -->|"sends message"| node_claw
node_claw -->|"starts invocation"| node_invocation
node_invocation -->|"scans input"| node_guards
node_invocation -->|"dispatches events"| node_hooks
node_invocation -->|"invokes agent"| node_agent
node_invocation -->|"persists history"| node_memory
node_invocation -->|"appends turn"| node_conversation
node_agent -->|"requests completion"| node_provider
node_agent -->|"executes tools"| node_tool_registry
node_agent -->|"fires events"| node_hooks
node_agent -->|"returns result"| node_response
node_provider -.->|"sends requests"| node_external_llm
node_tool_registry -->|"routes calls"| node_tool_router
node_tool_registry -.->|"dispatches tool"| node_database_tool
node_database_tool -->|"queries SELECT"| node_database
node_agent -->|"recalls context"| node_memory
node_agent -->|"validates schema"| node_structured
node_caller -->|"composes steps"| node_pipeline
node_pipeline_tool -->|"invokes pipeline"| node_pipeline
node_agent -.->|"calls as tool"| node_pipeline_tool
node_caller -->|"defines execution graph"| node_graph
node_agent -->|"uses skills"| node_skills
node_caller -->|"scans attributes"| node_discovery
node_provider -.->|"parses stream"| node_streaming
node_claw -->|"returns response"| node_response

click node_claw "https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Claw.php"
click node_invocation "https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Agent/InvocationPipeline.php"
click node_guards "https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Guards/GuardRegistry.php"
click node_agent "https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Agent/Agent.php"
click node_response "https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Agent/AgentResponse.php"
click node_provider "https://github.com/phpclaw-php/phpclaw/tree/0.x/src/Providers"
click node_tool_registry "https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Tools/ToolRegistry.php"
click node_tool_router "https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Tools/ToolRouter.php"
click node_tool_impl "https://github.com/phpclaw-php/phpclaw/tree/0.x/src/Tools"
click node_database_tool "https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Tools/DatabaseQueryTool.php"
click node_memory "https://github.com/phpclaw-php/phpclaw/tree/0.x/src/Memory"
click node_conversation "https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Agent/Conversation.php"
click node_hooks "https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Hooks/HookDispatcher.php"
click node_streaming "https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Http/StreamParser.php"
click node_structured "https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Agent/StructuredOutputRunner.php"
click node_pipeline "https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Pipeline/Pipeline.php"
click node_pipeline_tool "https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Pipeline/PipelineTool.php"
click node_graph "https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Graph/Graph.php"
click node_skills "https://github.com/phpclaw-php/phpclaw/tree/0.x/src/Skills"
click node_discovery "https://github.com/phpclaw-php/phpclaw/blob/0.x/src/AutoDiscovery/AttributeScanner.php"

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_claw,node_response toneBlue
class node_invocation,node_guards,node_agent,node_database toneAmber
class node_structured,node_pipeline,node_pipeline_tool,node_graph,node_skills,node_discovery toneMint
class node_provider,node_tool_registry,node_tool_router,node_tool_impl,node_database_tool,node_streaming toneRose
class node_memory,node_conversation,node_hooks,node_caller,node_external_llm toneIndigo
```

## Components

### Agent entry

- [Claw facade](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Claw.php): `src/Claw.php`
- [Agent response](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Agent/AgentResponse.php): `src/Agent/AgentResponse.php`

### Agent runtime

- [Invocation lifecycle](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Agent/InvocationPipeline.php): `src/Agent/InvocationPipeline.php`
- [Input guards](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Guards/GuardRegistry.php): `src/Guards/GuardRegistry.php`
- [ReAct agent](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Agent/Agent.php): `src/Agent/Agent.php`

### Agent capabilities

- [Structured output](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Agent/StructuredOutputRunner.php): `src/Agent/StructuredOutputRunner.php`
- [Composable pipeline](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Pipeline/Pipeline.php): `src/Pipeline/Pipeline.php`
- [Pipeline tool](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Pipeline/PipelineTool.php): `src/Pipeline/PipelineTool.php`
- [Graph execution](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Graph/Graph.php): `src/Graph/Graph.php`
- [Skills](https://github.com/phpclaw-php/phpclaw/tree/0.x/src/Skills): `src/Skills`
- [Attribute discovery](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/AutoDiscovery/AttributeScanner.php): `src/AutoDiscovery/AttributeScanner.php`

### Providers and tools

- [Provider adapters](https://github.com/phpclaw-php/phpclaw/tree/0.x/src/Providers): `src/Providers`
- [Tool registry](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Tools/ToolRegistry.php): `src/Tools/ToolRegistry.php`
- [Tool routing](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Tools/ToolRouter.php): `src/Tools/ToolRouter.php`
- [Built-in tools](https://github.com/phpclaw-php/phpclaw/tree/0.x/src/Tools): `src/Tools`
- [Read-only SQL tool](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Tools/DatabaseQueryTool.php): `src/Tools/DatabaseQueryTool.php`
- [Streaming transport](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Http/StreamParser.php): `src/Http/StreamParser.php`

### State and events

- [Memory drivers](https://github.com/phpclaw-php/phpclaw/tree/0.x/src/Memory): `src/Memory`
- [Conversation history](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Agent/Conversation.php): `src/Agent/Conversation.php`
- [Lifecycle hooks](https://github.com/phpclaw-php/phpclaw/blob/0.x/src/Hooks/HookDispatcher.php): `src/Hooks/HookDispatcher.php`

### Other components

- **Application caller**
- **LLM service**
- **Application database**

## Connections

- Application caller → Claw facade: sends message (evidence: `README.md`)
- Claw facade → Invocation lifecycle: starts invocation (evidence: `src/Claw.php`)
- Invocation lifecycle → Input guards: scans input (evidence: `src/Agent/InvocationPipeline.php`)
- Invocation lifecycle → Lifecycle hooks: dispatches events (evidence: `src/Agent/InvocationPipeline.php`)
- Invocation lifecycle → ReAct agent: invokes agent (evidence: `src/Agent/InvocationPipeline.php`)
- Invocation lifecycle → Memory drivers: persists history (evidence: `src/Agent/InvocationPipeline.php`)
- Invocation lifecycle → Conversation history: appends turn (evidence: `src/Agent/InvocationPipeline.php`)
- ReAct agent → Provider adapters: requests completion (evidence: `src/Agent/Agent.php`)
- ReAct agent → Tool registry: executes tools (evidence: `src/Agent/Agent.php`)
- ReAct agent → Lifecycle hooks: fires events (evidence: `src/Agent/Agent.php`)
- ReAct agent → Agent response: returns result (evidence: `src/Agent/Agent.php`)
- Provider adapters → LLM service: sends requests (evidence: `README.md`)
- Tool registry → Tool routing: routes calls (evidence: `src/Agent/Agent.php`)
- Tool registry → Read-only SQL tool: dispatches tool
- Read-only SQL tool → Application database: queries SELECT (evidence: `src/Tools/DatabaseQueryTool.php`)
- ReAct agent → Memory drivers: recalls context (evidence: `README.md`)
- ReAct agent → Structured output: validates schema (evidence: `README.md`)
- Application caller → Composable pipeline: composes steps (evidence: `src/Pipeline/Pipeline.php`)
- Pipeline tool → Composable pipeline: invokes pipeline (evidence: `src/Pipeline/PipelineTool.php`)
- ReAct agent → Pipeline tool: calls as tool
- Application caller → Graph execution: defines execution graph (evidence: `src/Graph/Graph.php`)
- ReAct agent → Skills: uses skills (evidence: `README.md`)
- Application caller → Attribute discovery: scans attributes (evidence: `src/AutoDiscovery/AttributeScanner.php`)
- Provider adapters → Streaming transport: parses stream
- Claw facade → Agent response: returns response (evidence: `README.md`)