Skip to content

docs: add developer guides for backend design components - #446

Merged
zzylol merged 3 commits into
mainfrom
docs/backend-component-developer-guides
Aug 28, 2026
Merged

zzylol merged 3 commits into
mainfrom
docs/backend-component-developer-guides

Conversation

@zzylol

@zzylol zzylol commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

Summary

Follow up #445 with developer guides for the public component interfaces required by the active designs.

Every developer guide now follows the same required structure:

  1. Code architecture — public module/component boundaries and data flow.
  2. Public interfaces and definitions — public traits, structs, enums, field semantics, function signatures, inputs, outputs, errors, and why the interfaces exist.
  3. Adding and verifying functionality — how to add concrete feature classes through those interfaces and how to interpret/validate their outputs.

The guides do not document private interfaces, functions, variables, implementation files, or internal helpers. Where current code has not converged on a stable public boundary, the document explicitly labels a target public API rather than presenting migration internals as API.

Public interfaces covered

Control plane

  • Planner adapter: PlanningRequest -> SelectedLogicalPlan.
  • Physical compiler: selected plan + deployment/policy -> matching CompiledPlanBundle.
  • Runtime clients: CollectorPlan and BackendPlan staging.
  • Semantic application reports and PlanPublisher activation/rollback.

Data plane

  • BackendPlan decoder, validator, runtime, snapshots, and lifecycle reports.
  • OTLP SummaryDecoder, SeriesIdentityResolver, SummaryValidator, and SummaryStateApplier.
  • QueryService, SummaryReader, and ExactQueryClient.
  • SeriesRegistry and SummaryStore, including typed coverage results.
  • Public protocol server/adapter/fallback extension contracts.
  • Cross-repository SummaryCapability workflow for adding a summary family.

ASAPCollector correspondence

Runtime publication directly references ASAPCollector's authoritative docs/developer_docs/opamp-config-push.md rather than redefining CollectorPlan. It preserves:

  • the asap-collector-plan.yaml AgentConfigMap entry;
  • YAML media type;
  • config_hash versus cross-runtime plan_id;
  • io.asap.collector.plan.v1 / application_report semantics; and
  • the documented current implementation gap.

Navigation

  • control-plane and data-plane indexes list the new guides;
  • each active design links to its corresponding developer interface;
  • repository documentation index links to all public extension guides.

Validation

  • git diff --check
  • all local Markdown links resolve;
  • all developer documents have the required three sections;
  • fenced code blocks are balanced;
  • checked that developer docs contain no pub(crate), private interface/function/variable documentation, implementation file paths, or current-code maps;
  • documentation-only change.

@zzylol
zzylol merged commit af7b6ed into main Aug 28, 2026
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