43 lines
3.0 KiB
Markdown
43 lines
3.0 KiB
Markdown
# Architecture information-architecture remediation
|
|
|
|
Use this workflow when a Docusaurus architecture section builds successfully but does not satisfy its required navigation or content contract.
|
|
|
|
## Separate the three verdicts
|
|
|
|
Audit and report these independently:
|
|
|
|
1. **Structural compliance** — dedicated docs plugin/sidebar, exact ordering and nesting, stable document IDs, routes, and registry links.
|
|
2. **Content completeness** — required C4 levels, registries, responsibilities, relationships, traceability, and explicit placeholders for gated decisions.
|
|
3. **Build/render health** — structure validator, typecheck, strict broken-link production build, diagram-source validation, browser rendering, and console errors.
|
|
|
|
A green build proves only build health. An autogenerated sidebar or matching headings inside one page does not prove structural compliance.
|
|
|
|
## Safe remediation sequence
|
|
|
|
1. Fetch the remote base branch and create a clean worktree/branch from its exact SHA.
|
|
2. Encode the required hierarchy in a deterministic validator and run it once to prove RED.
|
|
3. Replace autogenerated navigation with an explicit sidebar when semantic order matters.
|
|
4. Add the smallest compliant pages and registries. If product/solution approval is absent, create visibly gated scaffolding rather than inventing requirements, decisions, tasks, interfaces, or versions.
|
|
5. Keep editable `.drawio` sources beside the consuming architecture pages. Render them through `docusaurus-plugin-drawio` and MDX raw imports; do not substitute download links or static exports.
|
|
6. Run the structure validator, Draw.io/XML validation, typecheck, strict-link production build, and `git diff --check`.
|
|
7. Serve the production build and verify the actual sidebar nesting, representative routes, rendered diagram DOM, and browser console.
|
|
8. Commit and push, open a reviewable PR, read back its head/base SHAs and changed-file list, and wait for the exact commit's CI status to reach a terminal state.
|
|
9. Post one concise evidence message in the governing project channel with PR, commit, structure, validation, and remaining human gate.
|
|
|
|
## Docusaurus link pitfall
|
|
|
|
Docusaurus may resolve a source-relative link such as `./containers` from the generated page route (`/architecture/overview/`) rather than from the source-file directory, producing `/architecture/overview/containers/`. For links between sibling architecture documents, prefer explicit site-root routes such as `/architecture/containers/` and `/architecture/features/<id>/overview/`, then let the production build's broken-link check verify them.
|
|
|
|
Do not weaken `onBrokenLinks` or broken-Markdown-link handling to make remediation pass.
|
|
|
|
## Verification evidence to retain
|
|
|
|
- base branch and SHA;
|
|
- feature branch and commit SHA;
|
|
- validator output;
|
|
- strict production-build result;
|
|
- Draw.io validation result for every edited source;
|
|
- browser evidence for sidebar hierarchy and representative rendered diagram;
|
|
- zero relevant console/JavaScript errors;
|
|
- PR URL, mergeability, exact remote head SHA, and terminal CI result.
|