Skip to content

ADR-0027: Shared platform services as modules of their own

  • Status: Accepted
  • Date: 2026-11-13

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?

  • 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.
  1. A folder of its own under apps/api/src/modules for each shared service, importing only the shared kernel.
  2. Keep the services inside platform, as first laid out.
  3. 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.

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.

  • Good, because the dependencies point one way: business modules, then platform services, then the kernel.
  • Good, because apps/api/test/module-cycles.test.ts starts 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.
  • apps/api/src/modules/platform-mail/index.ts, platform-messaging/index.ts, platform-automations/index.ts and platform-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.