ADR 0016: Cross-module read models¶
- Status: Accepted
- Date: 2026-11-12
- Context issues: #52 (daily briefing), #70 (briefing push)
Context¶
Until now every module was self-contained: the dependency rule
(ADR 0001) forbids a module from importing
another one, enforced by depguard and internal/archtest. The only
cross-module traffic were shared kernel ports that many modules write to
(observations, alerts, audit events).
The daily briefing (#52) is the first feature that reads from several
modules at once: due to-dos, upcoming appointments, weather warnings, waste
collections, services that are down and overnight incidents from the
timeline. It must keep working when any of these modules is disabled via
MODULES_DISABLED, and the source modules must not learn that a briefing
exists.
Options considered:
- Import the source modules' use case packages from the briefing. Simple, but couples the briefing to six modules' internals and breaks the rule that modules do not import each other.
- Add shared read ports to
internal/shared/kernel. Every source module would have to implement a kernel interface designed for one consumer; the kernel would grow with every new read model. - Consumer-owned ports, adapters in the composition root. The briefing
defines exactly the narrow read ports it needs, with its own small fact
types.
cmd/serverimplements them on top of public read methods of the source modules.
Decision¶
Option 3.
- The consumer owns the ports.
briefing/usecasedefines one read port per source (DueTodosReader,UpcomingEventsReader,WeatherWarningReader,CollectionReader,ServiceStatusReader,IncidentReader) with briefing-owned fact types (TodoFact, …). The module knows nothing about to-do IDs, CalDAV or DWD. - Source modules expose read methods on their
Module(OpenTodos,Upcoming,Warnings,Services,Recent) that delegate to their existing input ports. They contain no logic and no knowledge of the consumer. - Adapters live in the composition root (
cmd/server/briefing.go). They translate between the source's view types and the consumer's facts and do simple filtering (e.g. "offline" services, non-info timeline events). The briefing module is built after the source modules and finds them in the registry; a disabled module leaves its portnil, and the use case leaves that section out. - Failures stay local: a source that errors marks its section as unavailable; the briefing itself still succeeds.
- Delivery channels are adapters too: the daily push (#70) reuses the
same
BuildBriefingcomposition and hands the text to aPublisherport, implemented in the composition root on top of the notifications module.
Consequences¶
- No module imports another module;
archteststays unchanged. - Adding a section means: a port and a fact type in the consumer, a read
method on the source module (if none exists), and an adapter in
cmd/serverwith an end-to-end test (cmd/server/briefing_test.go). - The composition root grows a little logic (mapping and filtering). It
must stay mapping only; rules belong in the consumer's domain
(
briefing/domain: ordering, priorities, time windows). - Future read models (e.g. a kiosk overview or config as code, #88) follow the same pattern.