# phpclaw-php/phpclaw-laravel architecture

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

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

## Overview

phpClaw is a Laravel adapter for an agent runtime: users submit requests through Artisan, the REST API, or application code; the engine uses configured providers, tools, and memory to produce responses. The README documents the major capabilities, while sampled source confirms API handling, tool execution, memory routing, and queue-result management. Provider registration, MCP internals, Telescope recording, and several command implementations were not sampled, so their wiring is shown only where documented or omitted.

Main entry points: [`src/Memory/DatabaseRouterMemory.php`](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Memory/DatabaseRouterMemory.php) (Memory router), [`src/PhpClawServiceProvider.php`](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/PhpClawServiceProvider.php) (Service provider), [`src/Engine/EngineFactory.php`](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Engine/EngineFactory.php) (Engine factory), [`src/Tools`](https://github.com/phpclaw-php/phpclaw-laravel/tree/0.x/src/Tools) (Laravel tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Request interfaces"]
  node_api_routes["REST routes<br/>[api.php]"]
  node_api_middleware["API middleware"]
  node_controller["API controller"]
  node_cli_command["Agent CLI<br/>[PhpClawCommand.php]"]
  node_facade["Laravel facade<br/>[PhpClaw.php]"]
end

subgraph group_engine["Agent integration"]
  node_provider["Service provider"]
  node_factory["Engine factory<br/>[EngineFactory.php]"]
  node_runtime{{"Agent runtime"}}
  node_ai_provider{{"AI provider"}}
end

subgraph group_capabilities["Agent capabilities"]
  node_tools["Laravel tools"]
  node_database_tool["Database tool<br/>[DatabaseTool.php]"]
end

subgraph group_state["Memory and jobs"]
  node_memory_router["Memory router"]
  node_conversation_memory[("Conversation memory")]
  node_key_value_memory[("Key-value memory<br/>[DatabaseMemory.php]")]
  node_cache_memory[("Cache memory<br/>[CacheMemory.php]")]
  node_queue_manager["Queue manager<br/>[QueueManager.php]"]
  node_agent_job["Agent job<br/>[RunAgentJob.php]"]
end

subgraph group_observability["Operations"]
  node_telescope["Telescope watcher<br/>[PhpClawWatcher.php]"]
  node_mcp_command["MCP server command"]
end

node_user(("User"))
node_laravel_app["Laravel app"]
node_artisan(("Artisan user"))
node_app_services[("Laravel services")]

node_user -->|"submits request"| node_api_routes
node_api_routes -->|"passes request"| node_api_middleware
node_api_middleware -->|"authenticates"| node_controller
node_controller -->|"sends or streams"| node_runtime
node_artisan -->|"runs command"| node_cli_command
node_cli_command -->|"sends request"| node_runtime
node_laravel_app -->|"calls agent"| node_facade
node_facade -->|"delegates"| node_runtime
node_provider -->|"builds engine"| node_factory
node_factory -->|"configures"| node_runtime
node_factory -->|"resolves tools"| node_tools
node_runtime -->|"requests completion"| node_ai_provider
node_runtime -->|"invokes tools"| node_tools
node_tools -->|"includes"| node_database_tool
node_database_tool -->|"runs read-only SQL"| node_app_services
node_provider -->|"registers driver"| node_memory_router
node_runtime -->|"reads and writes memory"| node_memory_router
node_memory_router -->|"routes conversations"| node_conversation_memory
node_memory_router -->|"routes other namespaces"| node_key_value_memory
node_provider -->|"registers driver"| node_cache_memory
node_queue_manager -->|"dispatches job"| node_agent_job
node_queue_manager -->|"polls stored results"| node_memory_router
node_provider -.->|"registers watcher"| node_telescope
node_artisan -->|"starts server"| node_mcp_command

click node_api_routes "https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/routes/api.php"
click node_api_middleware "https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Http/Middleware/AuthenticatePhpClawApi.php"
click node_controller "https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Http/Controllers/PhpClawController.php"
click node_cli_command "https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Console/PhpClawCommand.php"
click node_facade "https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Facades/PhpClaw.php"
click node_provider "https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/PhpClawServiceProvider.php"
click node_factory "https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Engine/EngineFactory.php"
click node_tools "https://github.com/phpclaw-php/phpclaw-laravel/tree/0.x/src/Tools"
click node_database_tool "https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Tools/DatabaseTool.php"
click node_memory_router "https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Memory/DatabaseRouterMemory.php"
click node_conversation_memory "https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Memory/DatabaseConversationMemory.php"
click node_key_value_memory "https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Memory/DatabaseMemory.php"
click node_cache_memory "https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Memory/CacheMemory.php"
click node_queue_manager "https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/QueueManager.php"
click node_agent_job "https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Jobs/RunAgentJob.php"
click node_telescope "https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Telescope/PhpClawWatcher.php"
click node_mcp_command "https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Console/McpServerCommand.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_api_routes,node_api_middleware,node_controller,node_cli_command,node_facade,node_user,node_artisan toneBlue
class node_provider,node_factory,node_runtime,node_ai_provider,node_app_services toneAmber
class node_tools,node_database_tool toneMint
class node_memory_router,node_conversation_memory,node_key_value_memory,node_cache_memory,node_queue_manager,node_agent_job toneRose
class node_telescope,node_mcp_command,node_laravel_app toneIndigo
```

## Components

### Request interfaces

- [REST routes](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/routes/api.php): `routes/api.php`
- [API middleware](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Http/Middleware/AuthenticatePhpClawApi.php): `src/Http/Middleware/AuthenticatePhpClawApi.php`
- [API controller](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Http/Controllers/PhpClawController.php): `src/Http/Controllers/PhpClawController.php`
- [Agent CLI](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Console/PhpClawCommand.php): `src/Console/PhpClawCommand.php`
- [Laravel facade](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Facades/PhpClaw.php): `src/Facades/PhpClaw.php`

### Agent integration

- [Service provider](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/PhpClawServiceProvider.php): `src/PhpClawServiceProvider.php`
- [Engine factory](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Engine/EngineFactory.php): `src/Engine/EngineFactory.php`
- **Agent runtime**
- **AI provider**

### Agent capabilities

- [Laravel tools](https://github.com/phpclaw-php/phpclaw-laravel/tree/0.x/src/Tools): `src/Tools`
- [Database tool](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Tools/DatabaseTool.php): `src/Tools/DatabaseTool.php`

### Memory and jobs

- [Memory router](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Memory/DatabaseRouterMemory.php): `src/Memory/DatabaseRouterMemory.php`
- [Conversation memory](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Memory/DatabaseConversationMemory.php): `src/Memory/DatabaseConversationMemory.php`
- [Key-value memory](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Memory/DatabaseMemory.php): `src/Memory/DatabaseMemory.php`
- [Cache memory](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Memory/CacheMemory.php): `src/Memory/CacheMemory.php`
- [Queue manager](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/QueueManager.php): `src/QueueManager.php`
- [Agent job](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Jobs/RunAgentJob.php): `src/Jobs/RunAgentJob.php`

### Operations

- [Telescope watcher](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Telescope/PhpClawWatcher.php): `src/Telescope/PhpClawWatcher.php`
- [MCP server command](https://github.com/phpclaw-php/phpclaw-laravel/blob/0.x/src/Console/McpServerCommand.php): `src/Console/McpServerCommand.php`

### Other components

- **User**
- **Laravel app**
- **Artisan user**
- **Laravel services**

## Connections

- User → REST routes: submits request
- REST routes → API middleware: passes request
- API middleware → API controller: authenticates
- API controller → Agent runtime: sends or streams
- Artisan user → Agent CLI: runs command
- Agent CLI → Agent runtime: sends request
- Laravel app → Laravel facade: calls agent
- Laravel facade → Agent runtime: delegates
- Service provider → Engine factory: builds engine
- Engine factory → Agent runtime: configures
- Engine factory → Laravel tools: resolves tools
- Agent runtime → AI provider: requests completion
- Agent runtime → Laravel tools: invokes tools
- Laravel tools → Database tool: includes
- Database tool → Laravel services: runs read-only SQL
- Service provider → Memory router: registers driver
- Agent runtime → Memory router: reads and writes memory
- Memory router → Conversation memory: routes conversations
- Memory router → Key-value memory: routes other namespaces
- Service provider → Cache memory: registers driver
- Queue manager → Agent job: dispatches job
- Queue manager → Memory router: polls stored results
- Service provider → Telescope watcher: registers watcher
- Artisan user → MCP server command: starts server