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).