Skip to content

Add architecture decision records for the 3.0 core - #50

Merged
neto737 merged 2 commits into
mainfrom
docs/3.0-adrs
Oct 30, 2026
Merged

neto737 merged 2 commits into
mainfrom
docs/3.0-adrs

Conversation

@neto737

@neto737 neto737 commented Oct 30, 2026

Copy link
Copy Markdown
Owner

Writes down the design decisions behind the 3.0 core as architecture decision records (ADRs) in docs/adr/, one per decision.

# Decision
0001 Navigation and the wallet handle: nouns navigate, verbs send, and the wallet holds only its coin and ID
0002 Arrays with documented open shapes instead of models
0003 PSR-18 with no bundled client: timeouts, TLS, proxies and CA bundles belong to the caller's client
0004 The exception hierarchy under BitGoException
0005 Path escaping: one segment per value, ''/./.. rejected, XRP/XLM addresses escaped whole
0006 Retries are opt-in and never apply to POST
  • Layout: each ADR has a status, a date, and the sections Context, Decision and Consequences. The context is drawn from what went wrong in 2.x and the v3 prototype.
  • Accuracy: every claim was checked against the current code, such as the defaults, the status-to-exception mapping and the Retry-After behaviour.
  • docs/adr/README.md: the index, when to write an ADR, how to supersede one, and a template.
  • CONTRIBUTING.md links to docs/adr/.
  • Two open points are written down as consequences rather than left out:
    • a discovered Guzzle client has no timeout by default, so the 3.0 README must say so
    • token coin codes with : are sent as %3A, which hasn't been checked against BitGo yet
  • Docs only: no code changes and no CHANGELOG entry. /docs is already excluded from dist archives.

@codecov

codecov Bot commented Oct 30, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (4b4af4a) to head (213a576).

Additional details and impacted files
@@             Coverage Diff             @@
##                main       #50   +/-   ##
===========================================
  Coverage     100.00%   100.00%           
  Complexity       159       159           
===========================================
  Files             16        16           
  Lines            370       370           
===========================================
  Hits             370       370           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

…-plugins setting only covers this repository's own install.
@neto737
neto737 merged commit d56b1a4 into main Oct 30, 2026
13 checks passed
@neto737
neto737 deleted the docs/3.0-adrs branch October 30, 2026 07:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant