ADR 0001: Retain a modular monolith with service adapters
Status
Accepted
Amended after acceptance under ADR 0000: Record each explanation once, in the place that owns it; the
Notes section records every clause added or corrected.
Context
dataretrieval is one Python library serving users who often combine several
hydrologic data sources in one process or notebook. The upstream services have
different protocols and schemas, but the package has one release lifecycle and
maintainer group. Distributed deployment or separately versioned service
packages would add operational and compatibility cost without improving the
library’s primary use cases.
Decision
Maintain one installable distribution organized as a modular monolith. Expose functions grouped by data portal. Keep service- and protocol-specific adapters independent behind those facades, and share infrastructure only where its contract is API-neutral.
Treat the OGC subsystem as a protocol component used by Water Data and NGWMN, not as a universal service framework. Do not force NLDI, StreamStats, WQP, or Water Use into return values or paging semantics in OGC’s form.
Consequences
Users install and version one coherent package.
Cross-service API compatibility can be tested in one pipeline.
Component boundaries are source-level rather than deployment boundaries and therefore require import checks and review discipline.
Shared infrastructure must remain small enough that it does not become a god module.
A new service should begin as its own adapter and acquire shared abstractions only after duplication has been demonstrated, not by up-front generalization.
Compliance
.importlinter prevents shared OGC infrastructure from importing service
adapters; lint-imports checks it in pre-commit and CI. A package-wide
fitness function requires the runtime import graph, including package facades,
to stay acyclic. The installed-wheel CI job verifies that the whole monolith
ships as one usable artifact.
Notes
The Compliance paragraph was corrected after acceptance. It also named the
contract that kept modern modules from depending on legacy NWIS, which was
deleted with dataretrieval.nwis (ADR 0005: Quarantine and retire legacy NWIS).