---
url: /internals.md
---
# Internals

This track describes how Evolve is built. It is written for people and agents working on the CMS itself, in the [racerfish/evolve-cms](https://github.com/racerfish/evolve-cms) repository, rather than for people building a site with it. The [Guide](/getting-started/installation) and [Develop](/data-modeling/blueprints) tracks cover those.

The repository is one Composer package:

| Directory | Holds |
|---|---|
| `core/` | the CMS: panel, blocks, media, routing, forms, mail templates for form mails, deployment tooling, health checks, tracking, settings, LLM access |
| `blog/`, `company/`, `event/`, `faq/`, `locator/`, `project/`, `scout24/`, `shopify/`, `email/`, `mcp/`, `ai-chatbot/`, `devtools/` | one module each, with its own service provider |
| `theme/` | the theme provider and the publishable starter theme |
| `workbench/` | the Testbench harness used for development and tests, not shipped |

::: cards

* [Package layout and boot](/internals/package-and-boot)
  Composer map, providers, what `register()` and `boot()` wire, the module lifecycle, publish tags.
* [Workbench](/internals/workbench)
  Run the package standalone, build the demo site, run the tests.
* [Blueprints and blocks](/internals/blueprints-and-blocks)
  Blueprint classes and YAML, discovery, the Block model, rendering and composers.
* [Settings overlay](/internals/settings-overlay)
  The database settings and how they overlay the config.
* [Tracking pipeline](/internals/tracking-pipeline)
  Emission, consent, the browser layer, server-side drivers.
* [Head and SEO](/internals/head-and-seo)
  Head DTOs, per-route tags, sitemap, security.txt, structured data.
* [Images and media](/internals/images-and-media)
  Storage, metadata, the rendering pipeline, the usage index.
* [Forms](/internals/forms)
  From form definition to lead, mails and conversion event.
* [Health system](/internals/health-system)
  Checks, scheduling, endpoints, Fleet.
* [Deployment tooling](/internals/deployment-tooling)
  Declarations, the deploy command, environment commands, Envoy.
* [MCP server](/internals/mcp-server)
  Wiring, the server, public scope, tools, tokens.
* [AI](/internals/ai)
  The core LLM layer and the chatbot agent.
* [Panel frontend](/internals/panel-frontend)
  Build, scripts, icons, layouts, overrides.
* [Releasing and contributing](/internals/releasing)
  Labels, CI, releases, the docs entry, the development loop.
  :::

`RELEASING.md` and `CLAUDE.md` in the repository remain the contributor references; this track explains the systems they assume you know.