Skip to content

Architecture Decisions

This section collects the Architecture Decision Records (ADRs) for webullapi4go. Each ADR captures one significant decision, the options considered, and the consequences.

Why ADRs

  • Decisions are recorded once, in one place, instead of being re-litigated in issues and pull requests.
  • The rationale survives contributor turnover.
  • Superseded decisions stay on disk, so the history of the design is auditable.

Format

Each ADR is a Markdown file named NNNN-short-title.md, where NNNN is a zero-padded, monotonically increasing number. Numbers are never reused.

Every ADR starts with a metadata block:

---
Status: Proposed | Accepted | Superseded by ADR-NNNN | Deprecated
Date: YYYY-MM-DD
Deciders: <who decided>
Supersedes: ADR-NNNN   # optional
---

Status meanings:

  • Proposed — written up but not yet ratified by the maintainer.
  • Accepted — the decision is in force.
  • Superseded by ADR-NNNN — replaced; the new one is authoritative.
  • Deprecated — no longer recommended, but not yet replaced.

Recommended body sections: Context, Problem, Options Considered (with pros/cons), Decision, Rationale, Consequences, Risks and Unknowns, Spike Plan (when follow-up verification is required).

Conventions

  • One decision per ADR. Do not bundle unrelated choices.
  • State facts and inferences separately. Mark anything inferred or unverified explicitly with Inferred or To verify.
  • Do not fabricate details (message names, field numbers, endpoints). When a detail is unknown, write "to be determined".
  • ADRs are immutable once Accepted. To change a decision, add a new ADR that supersedes the old one; do not rewrite history.

Records

ADR Title Status Date
0001 Record architecture decisions Accepted 2026-09-18
0002 gRPC event protobuf strategy Accepted 2026-09-18

New decisions get the next number and must not rewrite an accepted ADR; supersede it with a new record instead.