Skip to content

Developer guide

This section is for engineers working on the FedMS framework or on a FedMS tenant site. It covers the architecture, the code layout, the tools, the extension points, and the conventions every contributor should know.

If you are an AI agent working on FedMS, also read AI agent orientation — it cross-references this section with agent-specific guidance.

Reading order for new contributors

If you are new to FedMS, read in this order:

  1. Architecture — the big picture.
  2. Repository layout — where things live.
  3. Tooling — L3D, Ahoy, Drush, Composer.
  4. Modules overview — the seven component modules.
  5. Entities — the data model in code.
  6. ECA models overview — the business logic.
  7. Config management — how config flows.
  8. Testing — how to run tests.
  9. Contributing — the workflow for changes.
  10. Release process — how versions ship.

Quick reference

Where everything lives

What Where
Install profile web/profiles/contrib/fedms/
Component modules web/modules/contrib/fedms_*/
ECA models web/modules/contrib/fedms_eca/config/optional/eca.eca.*.yml
ECA per-model docs web/modules/contrib/fedms_eca/docs/
Install / config scripts vendor/fedms/scripts/
Playwright tests (active) tests/playwright/
Cypress tests (deprecated) tests/cypress/
Public documentation this site (mkdocs/)

The seven components

# Module What it provides
1 fedms_federation Group types (org, event, session) and federation plumbing.
2 fedms_content fedms_event and fedms_session content entities, paragraph types.
3 fedms_attachment fedms_attachment content entity.
4 fedms_task fedms_task entity + fedms_task_pattern config entity.
5 fedms_eca The ten business-logic ECA models.
6 fedms_locale i18n / l10n (German shipped).
7 fedms/scripts Install / config / export Ahoy commands.

Plus the install profile (fedms/components/profile) that pulls them all together, and the recipes for optional features.

House rules

  • Always go through L3D for PHP, Composer, Drush, Ahoy, phpcs, phpstan, phpunit, glab, drupalorg. Never run these tools directly on the host. See Tooling.
  • Each fedms_* module is its own git repo. Site changes go to the site repo; module changes go to the module repo.
  • US English (en-US) for everything that ends up in CI: comments, commit messages, MRs, issues, identifiers. The cspell pipeline enforces this.
  • OOP hooks with the #[Hook] attribute for new hooks. See fedms_federation/src/Hook/EntityHooks.php for the canonical example.
  • declare(strict_types=1); in new PHP files.
  • Config ownership stays with the module — never dump module config into the site's config/sync/.
  • Don't hand-edit eca.eca.*.yml — go through the modeler and re-export. See ECA models.
  • Don't bypass the federation membership query alter in fedms_federation. It's load-bearing for session access control.
  • Don't add Cypress tests — Playwright only.

In this section