Architecture
This section explains how the bundle works internally. It is for developers who need to understand the system end-to-end - to extend it, debug it, or reason about a failure mode. For "what can the product do," see Features. For YAML/env reference, see Configuration. Terminology is defined once in Core Concepts; this section assumes you have read that page.
System diagram
Pages
| Page | What you'll learn |
|---|---|
| 01 Agent Framework | How the Copilot SDK is wrapped, the two adapters (Copilot/Dummy), LLM auth modes, model resolution, performance instrumentation. |
| 02 Communication Flows | Start here. The system map - every runtime flow (chat/SSE, internal & external MCP, persistence, config export, Mercure, LLM) and the credential each one uses, with links to the canonical detail. |
| 03 Request Lifecycle | End-to-end path of a chat request: auth → session → task → the three event sinks (Mercure / PHP / POST) → catch-up reconnect → completion callback. |
| 04 Authentication | The credential reference behind the flow map: session cookie validation + identity cache, the pmcp_ bearer scope, admin bearer token, per-provider LLM auth, Mercure publisher JWT, rate limits, CSRF, audit log. |
| 05 MCP Integration | Internal vs external MCP servers, tool groups, the meta-tool wrapper, how the pmcp_ bearer and session IDs are forwarded, the token lifecycle. |
| 06 Session Storage | What is persisted, the DB tables, session lifecycle hooks. |
| 07 Tool Security | The pre-tool-use hook, SDK tool whitelist, path sandboxing. Mechanism only - for the tool catalog see the Configuration reference. |
| 08 Configuration System | How agent and skill configuration flows from PHP to the agent-server: the three-layer merge, the export endpoint, skill materialization, reload paths, startup recovery. |
| 09 Field Hint System | How the bundle teaches agents the correct JSON shape for every Pimcore field type - provider pattern, registry, covered types, recursion depth guard. |
| 10 Document Schema | How get_document_schema / get_area_brick work - the four signals an LLM receives, the AST analyzer, fixture loading + validation, the <index> placeholder convention, target-group personalization. For the fixture authoring workflow, see Extending → Template Examples. |
| 11 File Staging | The generic read-only file-set primitive: developer-configured sets, how an agent stages and reads them, the roots/denylist security model. |
| 12 Agent Template Generation | The template write path: private root + Twig namespace, the validator and sandbox, test-render, persistence, clone-and-reassign, the drift-guard lint. |
| 13 Real-time Sync | Multi-client chat: live turn delivery to every tab/device via Studio's Mercure per-user topic + GlobalMessageBus, PHP as the record, the catch-up / reconnect-refetch reliability model, busy state. |
| 14 Agent Tasks | Headless agent tasks: the AgentTask state machine, settlement, turn orchestration, the Node-owned finalize nudge, the maintenance watchdog, and the delegated-access model. |
The frontend is a Pimcore Studio plugin delivered via Module Federation. It has no architecturally distinct surface beyond what Studio itself documents - the one extension point you'll likely touch is the widget renderer registry, covered in Extending → Custom Rich Chat Widgets.
Components at a glance
| Component | Directory | Stack |
|---|---|---|
| Agent-server | agent-server/ | Node.js 22, Fastify 5, TypeScript, @github/copilot-sdk |
| Frontend plugin | assets/ | React 18, Redux Toolkit, Ant Design / @ant-design/x, RSBuild, Module Federation |
| PHP bundle | src/ | Symfony 7, Pimcore 2026.x, MCP tools, session storage API, installer |