Skip to content

docs: reorganize data-plane and backend design by ownership - #445

Merged
zzylol merged 2 commits into
mainfrom
docs/reorganize-backend-design
Aug 28, 2026
Merged

zzylol merged 2 commits into
mainfrom
docs/reorganize-backend-design

Conversation

@zzylol

@zzylol zzylol commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

Summary

Reorganize data_plane/docs and top-level docs using the same topic/ownership model as the control-plane cleanup in #444.

ASAPQuery-backend now documents only backend-owned architecture, physical runtime behavior, storage, identity, and extension boundaries. ASAPPlanner-owned parsing, query-to-summary mapping, accuracy reasoning, candidate generation, and logical selection are referenced rather than re-specified.

New structure

data_plane/docs

README.md is the index, with content split by audience:

  • design_docs/query-execution.md: BackendPlan-aware ingestion, routing, readiness, summary readout, and exact fallback contracts.
  • developer_docs/extension-points.md: protocol server, adapter, and fallback-client responsibilities without file-by-file recipes.
  • user_guide/querying-asap.md: user-facing PromQL behavior, summary-backed results, exact fallback, accuracy, freshness, and errors.

top-level docs

  • simplified getting-started overview and system architecture centered on the OTel summary pipeline;
  • design_docs/summary-storage.md: active materialization storage and lifecycle contract;
  • design_docs/series-identity.md: active canonical sid contract and recovery behavior;
  • design_docs/future-storage-and-compression.md: dormant/non-MVP persistence, compaction, backfill, service mode, compression, sampling, and profiling scopes;
  • developer_docs/adding-summary-family.md: cross-repository ownership and backend validation checklist.

Removed

  • historical PromSketch and SID-unification migration plans;
  • three implementation-specific extension walkthroughs;
  • obsolete query-log bootstrap instructions that place planning in ASAPCollector;
  • duplicated controller/planner, arithmetic, precompute, Sketch DB, persistence, pluggability, roadmap, compression, benchmark-estimate, and proof documents;
  • stale root TODO.md, which duplicated deleted progress/roadmap material and referenced removed files.

Relevant source comments now point to the consolidated storage and identity documents.

Validation

  • git diff --check
  • all local Markdown links resolve across docs, data_plane/docs, control_plane/docs, and the root README;
  • retained design documents declare status and MVP relationship;
  • searched the repository for names of all removed documents;
  • cargo fmt --all -- --check was attempted but is blocked by pre-existing formatting differences in sibling ASAPCollector/asap-precompute-rs; no Rust behavior changed in this PR.

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