Custom Craft CMS module: where project logic breaks
The standard Craft CMS model is designed for predictable entities: entries, categories, fields, role-based permissions. As long as a project stays within these boundaries, everything works without touching the core.
Problems begin where business logic stops being typical — and this is not about "too few plugins," but about the fact that the data model itself does not describe real relationships.
The first bottleneck is non-standard permission logic.
Built-in roles operate on sections and entry groups, but they do not answer questions like "an editor sees only their own content within their department" or "an approver can edit a field but not publish." Workarounds begin through hacky checks in templates, and every new rule has to be manually written into a dozen places.
The second is relationships between entities. When an entry must reference several related objects with different relationship types and display conditions, the standard Relations fields are not enough: relationship context is lost, duplicates appear, and queries become heavy.
The same goes for integrations with internal systems — warehouse, CRM, billing: the exchange requires intermediate logic that simply does not exist in the CMS.
A custom Craft CMS module solves this at the architecture level: dedicated tables and services for relationships, a separate access rules layer, event handlers for integrations. The core remains untouched — CMS updates do not break your logic. Let's break down how this is handled in practice.
What the module delivers: speed, fault tolerance, control
Non-standard logic spread across templates and plugins produces three typical problems: heavy queries on public pages, failures during core updates, and opaque access permissions.
Moving this logic into a separate Craft CMS module solves them at the architectural level rather than through point fixes.
Response speed
The module registers its own routes and services, so heavy queries move out of templates into a controlled layer with caching and lazy loading of relations.
In practice, the response time of the catalog and personal dashboards drops severalfold, and peak loads no longer hit the template render.
Eliminated failure classes
The logic in the module does not depend on template structure or plugin order — a core update or theme change will not break it.
A separate class of failures related to write races is also closed off: transactions and queues move heavy operations out of the user request, and no partially applied changes remain in the database.
Predictability of updates
The module is installed and updated as a separate package with schema migrations and versioning. A core update stops being an event requiring manual checking of every template: incompatibility is detected at the migration stage, not in production.
Access control
Permissions are described declaratively — by roles, sections, and individual actions, rather than through scattered checks in templates.
This provides a single audit point: it is clear who can do what, and any change to access policy goes through review rather than being edited in ten places.
The effect accumulates: the more non-standard scenarios live in the module, the smaller the surface for regressions with each release.
Implementation formats: built-in module, plugin, external service
In Craft CMS, custom logic lives in three different places, and the choice between them determines how the project will be maintained going forward.
A built-in module is code inside the project: it sees the core's models, events, and queues directly, is deployed together with the application, and does not require a separate release cycle.
A plugin is a standalone package with its own lifecycle: it can be reused across projects and updated independently, but every call to Craft's internal APIs must be kept within compatible boundaries.
An external service moves the logic outside the application and communicates with it over the network — this takes the load off PHP processes, but adds network failure, latency, and a separate deployment contour.
| Option | When it fits | Architecture constraints |
|---|---|---|
| Built-in module | The logic is specific to one project, and direct access to core events and models is needed | Lives only in this project, is updated together with it, and cannot be reused on another site |
| Plugin | The functionality repeats across several projects, or version isolation is needed | Requires a stable public API; on a major Craft update, compatibility must be maintained |
| External service | Heavy computations, integrations, working with external systems and your own data | Network failure and latency, separate access credentials, logging and monitoring, state synchronization |
In practice, the boundaries are often combined: the module holds business rules and events, the external service takes on the heavy lifting, and a plugin appears once the solution has proven its value and it is time to move it between projects.
We lock in this choice at the design stage — the deployment scheme, the update strategy, and the cost of maintenance a year from now all depend on it.
Implementation stages: from logic audit to handover to the team
We start with a logic audit: we analyze how the task is currently solved — with plugins, manual editor operations, or template edits. At this step, we record the points where logic is duplicated and the places that break when the core is updated. The result of the audit is a dependency map and a list of what the module should take on.
- Audit of the current logic. We collect real workflows of editors and administrators, and look at which data and events the task affects. We define the boundaries of the module: what goes into it, what stays in the core.
- Designing the module schema. We describe the structure: entities, fields, relationships, role-based access rights. We design migrations separately — so that the data structure can be deployed on any environment with a single command.
- Setup and assembly. We implement the logic, move configuration into project files, and connect the module without modifying the core. This way, platform updates do not overwrite the customizations.
- Scenario verification. We run the module on real data and edge cases: empty result sets, bulk operations, simultaneous work by several editors. We cover each scenario with a test.
- Acceptance on the staging environment. We demonstrate the work on a copy of production content and compare the behavior with the original logic. We make fixes before rollout, not after.
- Handover to the team. We provide documentation on the structure and settings, an instruction manual for editors, and the rollback procedure. We hold a walkthrough with your developers so that the module can be developed further without us.
Each stage ends with an artifact that can be verified: a dependency map, a data schema, a set of tests, an operation manual. This way, what you get at the end is not a "black box" but a predictable component with a clear area of responsibility.
What the client receives: configurations, diagrams, regulations
We hand over not "working code on our server," but a package with which your team or another contractor can continue the work without us. Below is what exactly is fixed in the handover for a custom module.
- Module configurations — settings files describing all parameters: which fields and content types the module registers, which events it intercepts, which default values it uses. Settings are separated from the code, so behavior changes by editing the configuration rather than by modifying the code.
- Relationship diagrams — a map of how the module interacts with the system core, other modules, and external services: extension points, call order, and places where the logic depends on third-party data.
- Access policies — a permission matrix by role: who can see the module's sections, who can change settings, who can only read data. Server-side checks are described separately so that permissions cannot be bypassed through a direct request.
- Migrations and data structure — scenarios for changing the storage schema with versioning, so that an update does not break already accumulated records and rolls back correctly.
- Module documentation — purpose, public methods, usage examples, limitations, and known assumptions. Enough for a new developer to figure things out without corresponding with the author.
- Update and rollback regulations — the procedure for rolling out changes, pre-release checks, rollback points to the previous version, and the conditions under which a rollback is triggered automatically.
- Operations manual — typical operations: enabling and disabling the module, key rotation, reading logs, and responding to external service failures.
The package closes the main risk of custom development — dependence on a single contractor. Any engineer familiar with the stack can bring up the module in a clean environment using the documentation and continue its development. Describe your task — we will come back with an estimate and a handover plan.
Case study: how a module eliminated manual operations and sped up response
The client — a network of several dozen regional representative offices — maintained its product catalog and inventory on Craft CMS.
Content managers updated prices and availability by hand: an export from the accounting system arrived as a file, followed by line-by-line transfer, reconciliation, and publication. At peak — several hundred edits per day, and every error in inventory made it to the storefront.
We identified the bottleneck: the problem was not the volume of data, but the absence of a layer between the accounting system and the editor.
We built a custom module that accepts the export on a schedule, matches records by external identifier, and updates fields through Craft's native API — without direct database queries and without bypassing the cache.
Version conflicts (who edited last) are resolved by the module using a timestamp and written to a log, rather than being "silently" overwritten.
What it was before and what it became after
| Metric | Before | After |
|---|---|---|
| Catalog update | manually, once a day | on a schedule, every 15 minutes |
| Manual edits per day | several hundred | a handful (only non-standard cases) |
| Inventory errors | regular, caught after the fact | filtered out at data intake |
| Storefront response to a change | hours | minutes |
We also separately addressed rollback: each update writes a snapshot of the changed records, so an unsuccessful export can be undone with a single operation without restoring the entire database. Manual operations are gone from the process — managers focus on content, not on reconciling tables.
How is a custom module different from a marketplace plugin?
A marketplace plugin is a ready-made solution for a typical scenario: a feedback form, simple import, basic integration. As long as the task matches what the author built into the plugin, everything works predictably.
The problem begins where the business logic diverges: you need a non-standard calculation, your own access rights scheme, several entities tied into a single process.
Then the plugin either doesn't cover the task or covers it only partially — and workarounds start growing around it.
A custom module is written for a specific process, so control over the logic stays with the team, not with a third-party author. We define the data structure, the order of operations, the extension points, and how the module behaves on errors.
This is the fundamental difference: with a plugin you accept someone else's decisions as a given, with a module you design them for your own task.
Dependencies are the second source of risk. A plugin always has a chain: the author, their support timelines, compatibility with the current CMS branch, third-party libraries inside.
When the core is updated, that chain breaks at the most inconvenient moment, and you either wait for a patch from the author or freeze updates. We keep a custom module on the core's supported interfaces and update it along with the core — without waiting for a third party.
Hence the different class of risks when updating the CMS. A plugin can break on a major update, and it can't be fixed without access to the source code.
We maintain the module ourselves: we see what changed in the core and make targeted fixes without touching the rest of the system.
That is why for processes that give the business an advantage, a module is almost always more beneficial — you don't share control over the logic with someone else's team.
Technical concerns: updates, security, rollback
A custom module lives in the project's codebase, not in the system core, so CMS updates don't break it: extensions are connected through standard extension points rather than by editing vendor files.
For a major update, we run the module through a test bench with a copy of production data — if the extension point contract has changed, adaptation takes hours rather than weeks of rewriting from scratch.
We separate access by roles and permissions within the CMS itself: a content manager sees only their own sections, an administrator sees the module settings, and external integrations use separate keys with a limited set of operations.
All actions with data are written to a log — you can see who changed a record and when, which also helps during incident investigation.
What happens if a CMS update does break the module?
We install the update first on a copy of the production environment, not on prod. If the module fails the checks, the CMS release is rolled back to the previous branch, and the module is adapted separately — the production site keeps running without downtime during this time.
Before every update we take a snapshot of the database and files, so returning to a working state takes minutes.
How do you roll back changes made by the module?
Content changes are versioned: every record keeps a revision history, and any one can be restored selectively without rolling back everything else.
For data schema changes we prepare reverse migrations — they are executed by the same deployment command as the forward ones and are tested on the bench before production.
Is the module compatible with third-party extensions?
Yes, if they use standard extension points rather than overriding the core. Conflicts usually arise at the level of shared tables or interception of the same events — we identify such places at the design stage and separate them by processing priorities. Before implementation we run a scenario with the customer's full set of extensions.
Who has access to the server and database after handover?
Access remains with the customer: we work through separate accounts with limited rights and logging, not through a shared administrative login.
This means that when a contractor or engineer changes, access is revoked in a single operation, with no risk of losing control over the system.
Let's discuss the task: we'll come back with an estimate and a plan
To come back with an estimate and a plan rather than generalities, we need a minimum of input on the task.
A custom Craft CMS module almost always grows out of a specific bottleneck: non-standard discount calculation, catalog synchronization with an external system, roles and permissions that aren't in the base set, or a custom content type with complex publishing logic.
The more precisely you describe what's happening now and what should happen, the fewer assumptions we'll build into the estimate.
To start, the following is enough:
- a description of the business process: who does what, where it currently breaks or is done manually;
- data examples: an export, admin panel screenshots, samples of fields and relationships between entities;
- how the task is solved today — an external service, spreadsheets, a manager's work;
- access requirements: which roles should see and change data, what should be read-only;
- integrations: what the module exchanges data with and in which direction;
- constraints: deadlines, ties to releases, what must not be broken in the current site;
- the contact of the person who will accept the work and confirm the logic.
In return, we come back with an estimate and a plan: a breakdown into stages with effort estimates, a draft technical specification, a data and integration point diagram, a list of risks and assumptions, as well as a rollout order — first on a test environment, then on production with the ability to roll back.
If non-obvious dependencies surface during the review, we record them separately so that the start of work doesn't turn into a revision of deadlines.
Describe the task in free form — that will be enough to come back with an estimate and a plan.
