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](../../StyleGuide.md)
- [docs/requirements/](../requirements/) — the component design specs the code implements
- [README.md](../../README.md) — master component index