HarperFast / HarperFast/harper

Config system overhaul: single source of truth, eliminate circular deps, dynamic runtime reconfiguration

Open
#671 1 comment 0 reactions 1 assignee Claimed by @Ethan-Arrowood View on GitHub
area:components enhancement from-jira
Dominant language
JavaScript
Stars
89
Forks
10
Avg merge
2d 6h
Merged PRs (30d)
200

Description

**Architecture umbrella.** The Harper config system has accumulated significant technical debt: `hdbTerms.ts`, `configUtils.js`, `environmentManager.js`, `common_utils.js`, and scattered per-file duplicates all handling config in overlapping ways, with circular dependencies that have resisted cleanup.

## Core problems

1. **Circular dependency loop**: `harper_logger.js` → `RootConfigWatcher.ts` → `configUtils.ts` → `common_utils.js` → `environmentManager.js` → `harper_logger.js`. New subsystems cannot use `RootConfigWatcher` without hitting this cycle.
2. **No single in-memory config object**: multiple places re-parse `harperdb-config.yaml` from disk instead of using a shared in-memory representation.
3. **Runtime changes not propagated**: most subsystems cannot react to config changes without restart (and don't even tell the user a restart is needed).

## Proposed direction (from Ethan Arrowood's comment)

- **Single source of truth**: a canonical in-memory config object derived from yaml file + env vars + CLI args. All reads go through one interface.
- **RootConfigWatcher as the default**: extend the dynamic reconfiguration pattern (already used by `harper_logger`) to all config-dependent subsystems.
- **Fresh start on the legacy files**: `hdbTerms.ts`, `environmentManager.js`, `common_utils.js` should be incrementally replaced with a new config module rather than patched further.
- **Restart notification**: subsystems that truly require a restart on config change should declare that and surface it to the operator.

## Not Ready

This is a significant refactor. Needs a concrete incremental plan before scheduling. Initial step: agree on the new module structure and dependency graph, then migrate one subsystem at a time.

---

🤖 Filed by Claude on behalf of Kris.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.