# phpclaw-php/phpclaw-cloud architecture

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

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

## Overview

phpClaw Cloud is an optional transport and security extension for phpClaw agents. With a cloud key, CloudManager resolves the subscription manifest, then registers enabled lifecycle hooks and scan guards. Lifecycle events are converted into bounded, redacted payloads and sent asynchronously to Cloud; enabled prompt scans instead send messages for a verdict before the agent proceeds. Cloud capabilities include run tracing, model/tool monitoring, plan-based usage limits, feature opt-outs, and content hiding. The sampled source supports the manifest/cache, hook, payload, HTTP, and scan connections shown; broader dashboard behavior is documented but not implemented in this package.

Main entry points: [`src/CloudHttp.php`](https://github.com/phpclaw-php/phpclaw-cloud/blob/0.x/src/CloudHttp.php) (Cloud HTTP client), [`src/CloudManager.php`](https://github.com/phpclaw-php/phpclaw-cloud/blob/0.x/src/CloudManager.php) (Cloud manager), [`src/CloudWebhookHook.php`](https://github.com/phpclaw-php/phpclaw-cloud/blob/0.x/src/CloudWebhookHook.php) (Cloud webhook hook), [`src/CloudScanGuard.php`](https://github.com/phpclaw-php/phpclaw-cloud/blob/0.x/src/CloudScanGuard.php) (Cloud scan guard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_activation["Cloud activation"]
  node_manager["Cloud manager<br/>[CloudManager.php]"]
  node_manifest["Subscription manifest<br/>[CloudManifest.php]"]
  node_manifest_cache["Manifest cache<br/>[CloudManager.php]"]
end

subgraph group_telemetry["Lifecycle telemetry"]
  node_hook_registry["Hook registry"]
  node_lifecycle["Lifecycle events"]
  node_webhook["Cloud webhook hook"]
  node_payload["Payload builder"]
end

subgraph group_security["Prompt security"]
  node_guard_registry["Guard registry"]
  node_scan_guard["Cloud scan guard<br/>[CloudScanGuard.php]"]
end

subgraph group_remote["Cloud service"]
  node_cloud_http["Cloud HTTP client<br/>[CloudHttp.php]"]
  node_cloud{{"phpClaw Cloud API"}}
  node_dashboard["Tracing and usage"]
end

node_app(("phpClaw application"))
node_agent_prompt(("Agent prompt"))

node_app -->|"activates with key"| node_manager
node_manager -->|"reads and writes"| node_manifest_cache
node_manager -->|"fetches manifest"| node_cloud_http
node_cloud_http -->|"GET manifest"| node_cloud
node_cloud -->|"returns manifest"| node_cloud_http
node_cloud_http -->|"returns response"| node_manager
node_manager -->|"resolves config"| node_manifest
node_manager -->|"registers hooks"| node_hook_registry
node_manager -->|"registers guards"| node_guard_registry
node_lifecycle -->|"dispatches events"| node_hook_registry
node_hook_registry -->|"invokes hook"| node_webhook
node_webhook -->|"builds payload"| node_payload
node_webhook -->|"sends payload"| node_cloud_http
node_cloud_http -->|"POST run"| node_cloud
node_cloud -->|"provides tracing"| node_dashboard
node_agent_prompt -->|"checks prompt"| node_guard_registry
node_guard_registry -->|"invokes guard"| node_scan_guard
node_scan_guard -->|"requests scan"| node_cloud_http
node_cloud_http -->|"POST scan"| node_cloud
node_cloud -->|"returns verdict"| node_cloud_http
node_cloud_http -->|"returns response"| node_scan_guard

click node_manager "https://github.com/phpclaw-php/phpclaw-cloud/blob/0.x/src/CloudManager.php"
click node_manifest "https://github.com/phpclaw-php/phpclaw-cloud/blob/0.x/src/CloudManifest.php"
click node_manifest_cache "https://github.com/phpclaw-php/phpclaw-cloud/blob/0.x/src/CloudManager.php"
click node_webhook "https://github.com/phpclaw-php/phpclaw-cloud/blob/0.x/src/CloudWebhookHook.php"
click node_payload "https://github.com/phpclaw-php/phpclaw-cloud/blob/0.x/src/CloudPayloadBuilder.php"
click node_scan_guard "https://github.com/phpclaw-php/phpclaw-cloud/blob/0.x/src/CloudScanGuard.php"
click node_cloud_http "https://github.com/phpclaw-php/phpclaw-cloud/blob/0.x/src/CloudHttp.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_manager,node_manifest,node_manifest_cache toneBlue
class node_hook_registry,node_lifecycle,node_webhook,node_payload toneAmber
class node_guard_registry,node_scan_guard toneMint
class node_cloud_http,node_cloud,node_dashboard toneRose
class node_app,node_agent_prompt toneIndigo
```

## Components

### Cloud activation

- [Cloud manager](https://github.com/phpclaw-php/phpclaw-cloud/blob/0.x/src/CloudManager.php): `src/CloudManager.php`
- [Subscription manifest](https://github.com/phpclaw-php/phpclaw-cloud/blob/0.x/src/CloudManifest.php): `src/CloudManifest.php`
- [Manifest cache](https://github.com/phpclaw-php/phpclaw-cloud/blob/0.x/src/CloudManager.php): `src/CloudManager.php`

### Lifecycle telemetry

- **Hook registry**
- **Lifecycle events**
- [Cloud webhook hook](https://github.com/phpclaw-php/phpclaw-cloud/blob/0.x/src/CloudWebhookHook.php): `src/CloudWebhookHook.php`
- [Payload builder](https://github.com/phpclaw-php/phpclaw-cloud/blob/0.x/src/CloudPayloadBuilder.php): `src/CloudPayloadBuilder.php`

### Prompt security

- **Guard registry**
- [Cloud scan guard](https://github.com/phpclaw-php/phpclaw-cloud/blob/0.x/src/CloudScanGuard.php): `src/CloudScanGuard.php`

### Cloud service

- [Cloud HTTP client](https://github.com/phpclaw-php/phpclaw-cloud/blob/0.x/src/CloudHttp.php): `src/CloudHttp.php`
- **phpClaw Cloud API**
- **Tracing and usage**

### Other components

- **phpClaw application**
- **Agent prompt**

## Connections

- phpClaw application → Cloud manager: activates with key
- Cloud manager → Manifest cache: reads and writes
- Cloud manager → Cloud HTTP client: fetches manifest
- Cloud HTTP client → phpClaw Cloud API: GET manifest
- phpClaw Cloud API → Cloud HTTP client: returns manifest
- Cloud HTTP client → Cloud manager: returns response
- Cloud manager → Subscription manifest: resolves config
- Cloud manager → Hook registry: registers hooks
- Cloud manager → Guard registry: registers guards
- Lifecycle events → Hook registry: dispatches events
- Hook registry → Cloud webhook hook: invokes hook
- Cloud webhook hook → Payload builder: builds payload
- Cloud webhook hook → Cloud HTTP client: sends payload
- Cloud HTTP client → phpClaw Cloud API: POST run
- phpClaw Cloud API → Tracing and usage: provides tracing
- Agent prompt → Guard registry: checks prompt
- Guard registry → Cloud scan guard: invokes guard
- Cloud scan guard → Cloud HTTP client: requests scan
- Cloud HTTP client → phpClaw Cloud API: POST scan
- phpClaw Cloud API → Cloud HTTP client: returns verdict
- Cloud HTTP client → Cloud scan guard: returns response