ScadaBridge/docs/plans/2026-06-03-component-reference-docs-design.md

Component Reference Documentation — Design

Generate a complete set of per-component developer-reference documents in docs/components/, derived from the actual src/ code and written to StyleGuide.md. This is the design produced by the documentation-audit brainstorming session; the goal is documentation that is accurate (matches the code) and complete (one doc per component).

Goal

Produce 25 new reference docs — one per component — that describe how the code works for a developer, with real code examples. These complement (do not replace) the existing docs/requirements/Component-*.md design specs: the specs say what the component should do and why; the new reference docs say how the shipped code does it.

The requirements specs, the src/ code, and the XML doc comments are not modified by this work.

Scope

One reference doc per component, PascalCase, 1:1 with the existing spec set (minus the Component- prefix), under a new docs/components/ folder:

docs/components/
  README.md            # index linking all 25, one-line description each
  AuditLog.md  CentralUI.md  CLI.md  ClusterInfrastructure.md  Commons.md
  Communication.md  ConfigurationDatabase.md  DataConnectionLayer.md
  DeploymentManager.md  ExternalSystemGateway.md  HealthMonitoring.md  Host.md
  InboundAPI.md  ManagementService.md  NotificationOutbox.md  NotificationService.md
  Security.md  SiteCallAudit.md  SiteEventLogging.md  SiteRuntime.md
  StoreAndForward.md  TemplateEngine.md  TraefikProxy.md  Transport.md  TreeView.md

23 of the 25 map 1:1 to a src/ZB.MOM.WW.ScadaBridge.<Name> project. The other two are documented in full (decision: keep docs/components/ parallel to the spec set):

• TraefikProxy.md — no C# project; documented from the docker/ / infra/ Traefik configuration and the Host /health/active active-node endpoint. Examples in yaml / bash / json.
• TreeView.md — a Blazor component inside the CentralUI project; documented from the actual .razor / .cs component code. Examples in razor / csharp / css.

A link from the root README.md points to the new reference set.

Per-Document Structure

Each doc follows the StyleGuide section organization (general to specific), adapted to a code-reference doc. Sections scale to the component — simple components omit sections they do not need.

1. # H1 title (Title Case, matching the spec) + 1–2 sentence purpose.
2. ## Overview — what it is, where it runs (central / site), its role and the "why".
3. ## Key Concepts — domain terms a developer must know (only if needed).
4. ## Architecture — main types (actors / services / entities), data and message flow, with real csharp snippets (5–25 lines, with class context) taken from the actual source.
5. ## Usage — primary entry points and how the component is invoked, with real code.
6. ## Configuration — appsettings sections / options classes as a table (Option | Default | Description); only keys that exist in code.
7. ## Dependencies & Interactions — what it depends on and talks to, cross-linked.
8. ## Troubleshooting — common failure modes / health signals (where applicable).
9. ## Related Documentation — link to the spec (../requirements/Component-<Name>.md), related component reference docs, and relevant AkkaDotNet/ notes.

Generation Workflow

Approach: pilot exemplar, then parallel fan-out, then verification.

Phase 1 — Pilot

Author AuditLog.md by reading the src/ZB.MOM.WW.ScadaBridge.AuditLog project and its existing spec, fully StyleGuide-conformant. AuditLog spans central and site, actors, database, telemetry, and configuration, so it exercises every section and makes a strong template. The pilot is reviewed and approved before fan-out.

Phase 2 — Fan-out

One subagent per remaining component, dispatched in batches of roughly five to six concurrently (model: sonnet). Each subagent receives:

• The approved exemplar as the literal template to mirror.
• A condensed StyleGuide checklist (tone, present tense, real code only, names match code exactly, language-tagged code blocks, relative links, a Related Documentation section, no marketing words, no dates or version numbers).
• Its src/ project path, to read the real code.
• Its existing docs/requirements/Component-<Name>.md spec, for domain cross-check (where code and spec disagree, the code wins).
• The fixed section template and the output path.

Each subagent returns the written doc and the list of source files it drew from.

Phase 3 — Verification

For each generated doc, a reviewer pass checks:

• Every type, method, file, and config key referenced exists in the source (grep-verifiable). No invented APIs.
• StyleGuide conformance: heading casing, language-tagged code blocks, present tense, no banned marketing words, no dates / version numbers, links resolve.
• Required sections present (at minimum Overview, Dependencies & Interactions, Related Documentation).

Flagged issues are fixed. Then the docs/components/README.md index and the root README link are added, and all internal links are confirmed to resolve.

Acceptance Criteria

• Accuracy — no invented code; every snippet, type, method, and config key verifiably exists in src/; cross-links resolve; described behavior matches code.
• Completeness — 25 docs, none missing; each has at least Overview, Dependencies & Interactions, and Related Documentation; index and README updated.
• Conformance — passes the StyleGuide checklist.

Out of Scope

• No changes to src/ code, XML doc comments, or the docs/requirements/ specs.
• Nothing is committed mid-generation; the full set is reviewed before any push.

Related Documentation

• Documentation Style Guide
• docs/requirements/ — the component design specs the code implements
• README.md — master component index