Audit production-configuration-and-approval-methodology.md thresholds; point to source-of-truth and consolidate defaults
- Dominant language
- TypeScript
- Stars
- 3
- Forks
- 9
- Avg merge
- 4d 14h
- Merged PRs (30d)
- 6
Description
## Summary
Audit the accuracy of the threshold/parameter values in [`docs/checks/production-configuration-and-approval-methodology.md`](https://github.com/FilOzone/dealbot/blob/main/docs/checks/production-configuration-and-approval-methodology.md), make the doc point at the source(s) of truth rather than restating values that can drift, and reduce the number of places a given default is defined.
## Motivation
The doc currently restates configuration values inline, and at least one of them does not match (or is not actually enforced by) the code. Example found while investigating the [Data Storage Success Rate](https://github.com/FilOzone/dealbot/blob/main/docs/checks/production-configuration-and-approval-methodology.md#data-storage-success-rate) section:
- The doc lists **`Max dataStorageCheckMs = 180s`**.
- There is no `180` anywhere in `apps/backend/src` (outside unrelated Prometheus histogram bucket boundaries), no config default of 180, and no env/infra override setting it to 180.
- What actually causes the data storage ("deal") check to give up is the `AbortController` + `setTimeout` in [`jobs.service.ts`](https://github.com/FilOzone/dealbot/blob/main/apps/backend/src/jobs/jobs.service.ts) `handleDealJob`, driven by `dealJobTimeoutSeconds`, which defaults to **360s** (`Math.max(120000, timeoutSeconds * 1000)` floor of 120s), and is set to **360** in prod env.
So the doc implies a 180s hard cutoff that does not exist in code. Whether 180s is a stale value, an aspirational SLO, or a genuinely intended cutoff that was never implemented needs to be resolved as part of the audit. This is exactly the kind of drift that happens when values are copied into prose instead of referenced.
## Scope of work
### 1. Audit doc values and link to the source of truth
Go through every threshold/parameter value in `docs/checks/production-configuration-and-approval-methodology.md`, confirm each against the code/config, and where practical replace the inline value with a link to (or clearly reference) the source of truth. Candidate sources of truth:
- Code defaults: [`apps/backend/src/config/constants.ts`](https://github.com/FilOzone/dealbot/blob/main/apps/backend/src/config/constants.ts)
- Env-loading defaults: [`apps/backend/src/config/loader.ts`](https://github.com/FilOzone/dealbot/blob/main/apps/backend/src/config/loader.ts)
- Prod overrides: [`prod/apps/dealbot/dealbot-env.env`](https://github.com/FilOzone/infra/blob/main/prod/apps/dealbot/dealbot-env.env) (FilOzone/infra)
Resolve the `dataStorageCheckMs = 180s` discrepancy specifically (correct the value, remove it, or file follow-up to actually enforce it, whichever is intended).
### 2. Define each default in exactly one place
Today defaults live in two places:
- `constants.ts` `networkDefaults` (per-network defaults, e.g. `dealJobTimeoutSeconds: 360`).
- `loader.ts` inline `getNumberEnv(env, "X", )` calls for non-per-network config (e.g. `connectTimeoutMs: 10000`, `httpRequestTimeoutMs: 240000`, `ipniVerificationTimeoutMs: 60000`, `sampledBlockSampleCount: 5`, etc.).
Consolidate so each default value is declared once (ideally all in `constants.ts`, with `loader.ts` referencing those constants) so there is a single, greppable source of truth.
### 3. Add "keep the doc in sync" reminders next to the values
Add comments in both:
- [`apps/backend/src/config/constants.ts`](https://github.com/FilOzone/dealbot/blob/main/apps/backend/src/config/constants.ts)
- [`prod/apps/dealbot/dealbot-env.env`](https://github.com/FilOzone/infra/blob/main/prod/apps/dealbot/dealbot-env.env) (FilOzone/infra)
noting that changes to these values likely also require an update to `docs/checks/production-configuration-and-approval-methodology.md`.
## Notes
- Item 3's env-file change lives in the separate `FilOzone/infra` repo, so it will need a companion PR there (or a linked follow-up issue).
Contributor guide
No contributing guide indexed for this repository
Research direction
Read docs/checks/production-configuration-and-approval-methodology.md alongside apps/backend/src/config/constants.ts, apps/backend/src/config/loader.ts, and jobs.service.ts; compare every documented threshold with its implementation. Check prod/apps/dealbot/dealbot-env.env in the infra repository, then consolidate defaults, resolve the 180s discrepancy, and add the requested sync reminders, with a companion infra change or follow-up.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- backend, documentation, infrastructure
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100