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 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. |
| 03 Authentication | User session cookie validation, admin bearer token auth, MCP permission forwarding, rate limits, CSRF, audit log. |
| 04 MCP Integration | Internal vs external MCP servers, tool groups, the meta-tool wrapper, how cookies and session IDs are forwarded. |
| 05 Session Storage | What is persisted, the DB tables, session lifecycle hooks. |
| 06 Tool Security | The pre-tool-use hook, SDK tool whitelist, path sandboxing. Mechanism only — for the tool catalog see the Configuration reference. |
| 07 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. |
| 08 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. |
| 09 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. |
| 10 File Staging | The generic read-only file-set primitive: developer-configured sets, how an agent stages and reads them, the roots/denylist security model. |
| 11 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. |
| 12 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. |
The frontend is a Studio UI 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 11, MCP tools, session storage API, installer |