architecture diagrams for messaging system

Author: bobbybol

docs/ops/doc-sync-workflow.mdx

@@ -41,6 +41,10 @@ Use explicit prompts when needed:
 
 Prompt override is temporary for that run; state should still be updated afterward.
 
+## Static HTML mirrors (diagrams)
+
+Some repositories ship interactive diagrams as HTML under `docs/diagrams/`. During maintenance for those repos, copy updated files into `static/repos/<repo-short-name>/diagrams/` (for example `static/repos/nxt-backend/diagrams/`) so Docusaurus can serve them. Embed from MDX with the `EmbeddedHtmlDiagram` component and a `path` relative to `static/` (for example `repos/nxt-backend/diagrams/foo.html`).
+
 ## Minimal required state fields
 
 - `repo`

docs/ops/repo-doc-sync-state.yaml

@@ -13,8 +13,8 @@ nxt-backend:
   standard: monorepo
   doc_mode: maintenance
   status: standard-compliant
-  last_synced_sha: b7ca5faa06752865172acb614b0839ed9ffd07af
-  last_synced_at: 2026-05-06
+  last_synced_sha: 68cc07cf6428256b68dcd153b38192f03adbd9c3
+  last_synced_at: 2026-05-12
 
 nxt-control-room:
   repo: nxtgrid/nxt-control-room

docs/repositories/nxt-backend.mdx

@@ -22,6 +22,10 @@ Out of scope:
 - Frontend product UX orchestration and app-side routing.
 - Component-level endpoint payload definitions beyond source app docs and code contracts.
 
+## Architecture diagrams
+
+Interactive HTML diagrams (meter communications, device messaging, after-effects) are published on the dedicated [Architecture diagrams](./nxt-backend/diagrams) page. Source files live under `docs/diagrams` in the backend repository.
+
 ## Key components
 
 - Apps:

docs/repositories/nxt-backend/diagrams.mdx

@@ -0,0 +1,39 @@
+---
+title: Architecture diagrams
+---
+
+import EmbeddedHtmlDiagram from '@site/src/components/EmbeddedHtmlDiagram';
+
+# Architecture diagrams
+
+These interactive diagrams are maintained in [`nxt-backend/docs/diagrams`](https://github.com/nxtgrid/nxt-backend/tree/main/docs/diagrams) and mirrored here as static assets so they render inside NXT Docs.
+
+## Meter communications flow
+
+End-to-end meter communication paths and integration touchpoints.
+
+<EmbeddedHtmlDiagram
+  title="Meter communications flow"
+  path="repos/nxt-backend/diagrams/meter-communications-flow.html"
+  height={700}
+/>
+
+## Device message lifecycle
+
+High-level flow for device-related messaging through the stack.
+
+<EmbeddedHtmlDiagram
+  title="Device message lifecycle"
+  path="repos/nxt-backend/diagrams/device-message-lifecycle.html"
+  height={700}
+/>
+
+## After-effects cascade
+
+How downstream actions and side effects chain after primary operations.
+
+<EmbeddedHtmlDiagram
+  title="After-effects cascade"
+  path="repos/nxt-backend/diagrams/after-effects-cascade.html"
+  height={700}
+/>

sidebars.ts

@@ -26,6 +26,7 @@ const sidebars: SidebarsConfig = {
             'repositories/nxt-backend/yeti',
             'repositories/nxt-backend/shared-libs',
             'repositories/nxt-backend/data-layer',
+            'repositories/nxt-backend/diagrams',
           ],
         },
         'repositories/nxt-control-room',

src/components/EmbeddedHtmlDiagram.tsx

@@ -0,0 +1,46 @@
+import React from 'react';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+export type EmbeddedHtmlDiagramProps = {
+  title: string;
+  /**
+   * Path under `static/` (POSIX slashes). Example:
+   * `repos/nxt-backend/diagrams/meter-communications-flow.html`
+   */
+  path: string;
+  /** Iframe height in CSS pixels. */
+  height?: number;
+};
+
+function normalizeStaticPath(path: string): string {
+  const trimmed = path.trim();
+  return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+
+/**
+ * Embeds mirrored HTML diagrams or similar full-page assets from `static/`.
+ */
+export default function EmbeddedHtmlDiagram({
+  title,
+  path,
+  height = 720,
+}: EmbeddedHtmlDiagramProps): React.ReactNode {
+  const url = useBaseUrl(normalizeStaticPath(path));
+
+  return (
+    <figure className="embedded-html-diagram">
+      <iframe
+        title={title}
+        src={url}
+        width="100%"
+        height={height}
+        loading="lazy"
+      />
+      <figcaption className="embedded-html-diagram__caption">
+        <a href={url} target="_blank" rel="noopener noreferrer">
+          Open diagram in new tab
+        </a>
+      </figcaption>
+    </figure>
+  );
+}

src/css/custom.css

@@ -18,6 +18,17 @@
 }
 
 /* For readability concerns, you should choose a lighter palette in dark mode. */
+.embedded-html-diagram iframe {
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: var(--ifm-global-radius);
+  display: block;
+}
+
+.embedded-html-diagram__caption {
+  margin-top: 0.5rem;
+  font-size: var(--ifm-font-size-secondary);
+}
+
 [data-theme='dark'] {
   --ifm-color-primary: #2ba0bd;
   --ifm-color-primary-dark: #278fad;