documentation-docusaurus-3darch/references/architecture-ia-remediation.md

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.