ADR-0027: Shared platform services as modules of their own
- Status: Accepted
- Date: 2026-11-13
Context and problem statement
Section titled “Context and problem statement”The initial layout of the API was one module per functional area, ten in all (ADR-0001), with services used by everyone inside the platform module. platform also builds the Home screen from counts of Recruit and Attract, so it imports both. When Recruit needed the email queue, which lived in platform, the imports closed a cycle: Recruit to Platform to Attract to Recruit. The API then started correctly only for one particular order of imports.
Where do services live that several business modules use?
Decision drivers
Section titled “Decision drivers”- No import cycle between modules, in any order of loading.
- The boundary rule stays as it is: a module is used only through its public interface.
- A shared service must not know the business modules that use it.
Considered options
Section titled “Considered options”- A folder of its own under
apps/api/src/modulesfor each shared service, importing only the shared kernel. - Keep the services inside
platform, as first laid out. - Defer the cycle with a dynamic
import(). Considered later for a similar cycle and rejected: the boundary rule also covers dynamic imports and was kept.
Decision outcome
Section titled “Decision outcome”Chosen option: 1.
Four modules follow this pattern:
platform-mail: the email queue, used by Platform and by Recruit.platform-messaging: sending and receiving messages, and the provider adapters (ADR-0012, ADR-0013).platform-automations: the automation engine.platform-signing: electronic signature (ADR-0014).
None of them imports a business module or the rest of platform. The dependency is inverted through registries: a business module registers its triggers, conditions and actions in the engine, its link and attachment resolvers in messaging, and its file owners in the file service. Small helpers needed by several modules sit in the shared kernel, apps/api/src/core.
Consequences
Section titled “Consequences”- Good, because the dependencies point one way: business modules, then platform services, then the kernel.
- Good, because
apps/api/test/module-cycles.test.tsstarts the API from each module entry in turn and fails if any order breaks. - Bad, because the folder list has fourteen modules and no longer matches the ten functional areas one to one.
- Bad, because a service that does not know its users cannot reference their tables. The automation engine stores triggers, conditions and action parameters as checked text and JSON. A reference inside them (a template, a stage, a user) is checked when the rule is saved and again when it runs, not by a foreign key.
More information
Section titled “More information”apps/api/src/modules/platform-mail/index.ts,platform-messaging/index.ts,platform-automations/index.tsandplatform-signing/index.ts: the public interfaces, each stating what it must not import.apps/api/test/module-cycles.test.ts: the test.- Building blocks shows the modules and who depends on whom.
- Concept pages: Messaging, Background work.