From 81a6c665dc30200d98c31d819c536d915fdafa08 Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Tue, 4 Aug 2026 21:52:49 +0200 Subject: [PATCH 1/2] Use case pages: add a How It Works section Use case pages carried only what and why. This adds a howItWorks block to the layout covering the component breakdown, the design pattern chosen, an end-to-end architecture diagram and the hand-off into the product docs. Filled in for production monitoring and shop floor communication, with placehold.co stand-ins until the real diagrams are drawn. Two supporting fixes: section eyebrow numbers now derive from the nav array instead of being hardcoded, so they no longer drift when a page omits a block; and the architecture front-matter key on shop floor communication, which the layout never read, now renders as a link to the architecture page the use case sits on. --- src/_includes/layouts/use-case.njk | 143 +++++++++++++++++++-- src/use-cases/production-monitoring.njk | 38 ++++++ src/use-cases/shop-floor-communication.njk | 39 +++++- 3 files changed, 207 insertions(+), 13 deletions(-) diff --git a/src/_includes/layouts/use-case.njk b/src/_includes/layouts/use-case.njk index d3a0372a73..edcb7c0171 100644 --- a/src/_includes/layouts/use-case.njk +++ b/src/_includes/layouts/use-case.njk @@ -9,10 +9,33 @@ sitemapPriority: 0.7 problem hero sub-headline (the pain in one line) customerPain { heading, intro[], cards[ {icon,title,detail} ] } outcomeFirst { heading, intro, dimensions[ {label,title,detail} ] } + howItWorks { heading, intro, designPattern{}, diagram{}, pieces[], architecture, docsCta{} } whyItMatters { heading, intro, points[ {title,detail} ] } competition { heading, intro, traps[ {label,title,detail} ] } comparison { without[ {title,detail} ], with[ {title,detail} ] } + howItWorks answers "how does FlowFuse build this", which the pain, outcome + and comparison blocks deliberately do not. It is the bridge from the + marketing narrative into the product docs, so keep it high level here and + push every detail into a docs link. + + designPattern { kind, name, detail, docsUrl } + kind is the pattern family, e.g. "Hardware pattern" or + "Software pattern". name is the specific pattern chosen + for this use case. + diagram { src, alt, caption, width, height, placeholder } + End-to-end architecture drawing. src may be a placeholder + while the real diagram is commissioned; set + diagram.placeholder to true to render the placeholder + treatment and keep it visibly unfinished. width/height + default to 1200x630 and only exist to reserve the box, so + override them when the real asset is a different shape. + pieces [ {icon, title, detail, docsUrl} ] + The problem broken into the individual components that get + built. Order them the way you would build them. + architecture slug of a /use-cases/ architecture page this sits on + docsCta { label, url } + Legacy fall-back front-matter (simple skeleton, still supported): gap[], workflow[], outcomes[] @@ -23,11 +46,17 @@ sitemapPriority: 0.7 {% set nav = [] %} {% if customerPain %}{% set nav = nav.concat([{ id: "customer-pain", label: "Customer Pain" }]) %}{% endif %} {% if outcomeFirst %}{% set nav = nav.concat([{ id: "outcome-first", label: "Outcome First" }]) %}{% endif %} +{% if howItWorks %}{% set nav = nav.concat([{ id: "how-it-works", label: "How It Works" }]) %}{% endif %} {% if whyItMatters %}{% set nav = nav.concat([{ id: "why-it-matters", label: "Why It Matters" }]) %}{% endif %} {% if competition %}{% set nav = nav.concat([{ id: "competition", label: "Why Off-the-Shelf Fails" }]) %}{% endif %} {% if comparison %}{% set nav = nav.concat([{ id: "with-without", label: "With / Without FlowFuse" }]) %}{% endif %} {% if aiBuildLayer %}{% set nav = nav.concat([{ id: "ai-build-layer", label: "Build It With AI" }]) %}{% endif %} +{# --- section eyebrow numbers, derived from nav so they cannot drift --- + Pages omit blocks freely, so a hardcoded "03" desyncs from the nav as soon + as an earlier block is missing. Look the number up instead. #} +{% macro secNum(id) %}{%- for item in nav -%}{%- if item.id == id -%}{%- if loop.index < 10 -%}0{%- endif -%}{{ loop.index }}{%- endif -%}{%- endfor -%}{% endmacro %} +
-

01 · Customer pain

+

{{ secNum("customer-pain") }} · Customer pain

{{ customerPain.heading }}

{% for paragraph in customerPain.intro %} @@ -94,11 +123,11 @@ sitemapPriority: 0.7 {% if outcomeFirst %}
-

02 · Outcome first

+

{{ secNum("outcome-first") }} · Outcome first

{{ outcomeFirst.heading }}

{{ outcomeFirst.intro }}

@@ -114,13 +143,103 @@ sitemapPriority: 0.7
{% endif %} + {% if howItWorks %} + +
+
+

{{ secNum("how-it-works") }} · How it works

+

{{ howItWorks.heading or "How FlowFuse builds this" }}

+ {% if howItWorks.intro %} +

{{ howItWorks.intro }}

+ {% endif %} + + {% if howItWorks.designPattern %} +
+
+ {% include "components/icons/squares-2x2.svg" %} +
+
+ {{ howItWorks.designPattern.kind }} +

{{ howItWorks.designPattern.name }}

+

{{ howItWorks.designPattern.detail }}

+ {% if howItWorks.designPattern.docsUrl %} + + Read the pattern in the docs + {% include "components/icons/arrow-right.svg" %} + + {% endif %} +
+
+ {% endif %} + + {% if howItWorks.diagram %} +
+
+ {# width/height are here to reserve the box before the image + arrives; without them "h-auto" collapses the figure to + zero and the whole section below it jumps on load. #} + {{ howItWorks.diagram.alt }} +
+ {% if howItWorks.diagram.caption or howItWorks.diagram.placeholder %} +
{% if howItWorks.diagram.placeholder %}Placeholder diagram, pending art request. {% endif %}{{ howItWorks.diagram.caption }}
+ {% endif %} +
+ {% endif %} + + {% if howItWorks.pieces %} +

{{ howItWorks.piecesHeading or "The individual pieces" }}

+
+ {% for piece in howItWorks.pieces %} +
+
+
+ {% include "components/icons/" + piece.icon + ".svg" %} +
+ {% if loop.index < 10 %}0{% endif %}{{ loop.index }} +
+

{{ piece.title }}

+

{{ piece.detail }}

+ {% if piece.docsUrl %} + + Docs + {% include "components/icons/arrow-right.svg" %} + + {% endif %} +
+ {% endfor %} +
+ {% endif %} + + {% if howItWorks.docsCta or howItWorks.architecture %} +
+ {% if howItWorks.docsCta %} + {{ howItWorks.docsCta.label or "Read the docs" }} + {% endif %} + {% if howItWorks.architecture %} + + See the architecture this sits on + {% include "components/icons/arrow-right.svg" %} + + {% endif %} +
+ {% endif %} +
+
+ {% endif %} + {% if whyItMatters %}
-

03 · Why this is important

+

{{ secNum("why-it-matters") }} · Why this is important

{{ whyItMatters.heading }}

{{ whyItMatters.intro }}

@@ -140,11 +259,11 @@ sitemapPriority: 0.7 {% if competition %}
-

04 · Why off-the-shelf doesn't work

+

{{ secNum("competition") }} · Why off-the-shelf doesn't work

{{ competition.heading }}

{{ competition.intro }}

@@ -165,11 +284,11 @@ sitemapPriority: 0.7 {% if comparison %}
-

05 · With / without FlowFuse

+

{{ secNum("with-without") }} · With / without FlowFuse

Without FlowFuse

@@ -206,11 +325,11 @@ sitemapPriority: 0.7 {% if aiBuildLayer %}
-

06 · Build it with AI

+

{{ secNum("ai-build-layer") }} · Build it with AI

{{ aiBuildLayer.heading or "From described to deployed, with the FlowFuse Expert" }}

{{ aiBuildLayer.intro }}

diff --git a/src/use-cases/production-monitoring.njk b/src/use-cases/production-monitoring.njk index 5086a4a875..8dfbc56b0e 100644 --- a/src/use-cases/production-monitoring.njk +++ b/src/use-cases/production-monitoring.njk @@ -7,6 +7,44 @@ problem: "Your operation is running. You just can't see it clearly enough, until industries: ["automotive", "food-beverage", "life-sciences", "aviation-aerospace", "aerospace-components", "renewables", "semiconductors", "electronics-appliances"] values: ["production-performance"] +howItWorks: + heading: "How FlowFuse builds production monitoring." + intro: "Production monitoring is not one app you install. It is a handful of pieces you define once and then replicate. This is how the problem breaks down, and which FlowFuse pattern carries it across every line and site." + designPattern: + kind: "Hardware pattern" + name: "Pipeline plus environment variables" + detail: "The monitoring application is built once and distributed to every line by a DevOps pipeline. Everything site-specific, tag addresses, line names, shift boundaries, lives in environment variables instead of inside the flows, so the same snapshot runs everywhere without an edit." + docsUrl: "/docs/user/devops-pipelines/" + diagram: + placeholder: true + src: "https://placehold.co/1200x630/eef2ff/4338ca?text=Production+Monitoring+Architecture" + alt: "End-to-end architecture for production monitoring: PLCs and machines feeding edge instances, publishing to a broker and historian, with role-specific dashboards on top and a pipeline distributing the application across sites." + caption: "Machines and PLCs into edge instances, out over MQTT into your historian, role-specific dashboards on top, and one pipeline distributing the whole application across every line." + pieces: + - icon: "queue-list" + title: "Define the data model" + detail: "Name the equipment hierarchy and tag structure first: site, line, cell, signal. Every later piece depends on it, and this is exactly the part an off-the-shelf tool decides for you." + - icon: "chart" + title: "Derive the metrics" + detail: "Counts, cycle times, downtime reasons and OEE are calculated from the model rather than read off a machine. The logic sits in Node-RED flows your own team can read and change." + - icon: "device-agent" + title: "Collect at the edge" + detail: "The Device Agent runs an instance on existing edge hardware and speaks OPC-UA, Modbus, S7 or MQTT to whatever is already on the floor." + docsUrl: "/docs/device-agent/introduction/" + - icon: "arrows-right-left" + title: "Publish and store" + detail: "Contextualized data leaves the edge on a stable topic structure and lands in your historian or database. The schema and the storage stay yours." + - icon: "dashboard" + title: "Visualize per role" + detail: "A line view for the supervisor, trend detail for the maintenance engineer, a roll-up for the plant manager. FlowFuse Dashboard builds all three from the same data." + - icon: "rectangle-stack" + title: "Replicate across sites" + detail: "Snapshot the working application and let the pipeline push it to every other line, with each site's specifics supplied by environment variables." + docsUrl: "/docs/user/envvar/" + docsCta: + label: "Read the pipeline docs" + url: "/docs/user/devops-pipelines/" + aiBuildLayer: intro: "The FlowFuse Expert works on this use case with you: describe the monitoring you need and get a working starting flow, then query what it captures in plain language." steps: diff --git a/src/use-cases/shop-floor-communication.njk b/src/use-cases/shop-floor-communication.njk index 070eede175..a1a8645826 100644 --- a/src/use-cases/shop-floor-communication.njk +++ b/src/use-cases/shop-floor-communication.njk @@ -6,7 +6,44 @@ meta: problem: "The line stopped four minutes ago. The person who can fix it will find out when someone walks over." industries: ["automotive", "food-beverage", "aviation-aerospace", "electronics-appliances"] values: ["labor-operational-efficiency"] -architecture: "edge-connectivity" +howItWorks: + heading: "How FlowFuse builds connected andon." + intro: "Getting an event to the right person is a small number of pieces, not a product. The routing logic is identical at every site; only the people, channels and shift patterns differ, and that is what decides the pattern." + designPattern: + kind: "Hardware pattern" + name: "Pipeline plus external configuration" + detail: "The routing and escalation flows are built once and distributed by pipeline. Who responds, on which channel, during which shift is read at runtime from a central configuration source, so a rota change or a new contact never requires a redeploy." + docsUrl: "/docs/user/devops-pipelines/" + diagram: + placeholder: true + src: "https://placehold.co/1200x630/eef2ff/4338ca?text=Shop+Floor+Communication+Architecture" + alt: "End-to-end architecture for connected andon: machine signals and operator call buttons into edge instances, routed against a central directory of roles and shifts, delivered to displays, team channels and phones, with acknowledgment timing recorded." + caption: "Machine signals and call buttons into edge instances, routed against a central directory of roles and shifts, out to displays, team channels and phones, with every acknowledgment timed." + pieces: + - icon: "bell-alert" + title: "Capture the event" + detail: "Machine signals, alarm bits and operator call buttons all become the same kind of event, collected by an edge instance next to the equipment." + docsUrl: "/docs/device-agent/introduction/" + - icon: "queue-list" + title: "Model the event" + detail: "Each event carries type, area, severity and the role that should respond. Routing decisions are made against that shape, not against a machine address." + - icon: "users" + title: "Keep the directory outside the flow" + detail: "Roles, contacts, channels and the shift calendar live in configuration rather than inside the flows, so the floor can change who responds without touching the application." + docsUrl: "/docs/user/envvar/" + - icon: "share" + title: "Deliver where people look" + detail: "The same event fans out to andon displays, team channels and phones, each with the context the recipient needs to act on it." + - icon: "clock" + title: "Acknowledge and escalate" + detail: "An unacknowledged event climbs the chain on a timer. Nothing waits on someone happening to be free." + - icon: "circle-stack" + title: "Record the timing" + detail: "Event, notification and acknowledgment timestamps land in your database, which is what turns response time into a metric you can manage." + architecture: "edge-connectivity" + docsCta: + label: "Read the pipeline docs" + url: "/docs/user/devops-pipelines/" customerPain: heading: "Events travel at walking speed." From 9f5af6a374ce8012a66523ac872aaed96605c06e Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Tue, 4 Aug 2026 23:25:53 +0200 Subject: [PATCH 2/2] Use Cases: add System Diagnostics Restores the System Diagnostics page written in the earlier three-lens IA work and dropped when that work was cut back. Copy is recovered as written and still carries its template-copy marker for a Showcase pass. Adapted to the current layout: the architecture key moves inside a new howItWorks block covering diagnostics from a shared emitter through to one triage view, and expertDock is dropped since nothing renders it. Diagram is a placehold.co stand-in. Links it from the homepage Operational Application System entry and the footer use case list. --- src/_includes/layouts/base.njk | 1 + src/index.njk | 1 + src/use-cases/system-diagnostics.njk | 138 +++++++++++++++++++++++++++ 3 files changed, 140 insertions(+) create mode 100644 src/use-cases/system-diagnostics.njk diff --git a/src/_includes/layouts/base.njk b/src/_includes/layouts/base.njk index ceb8057f15..1ebd5a5331 100644 --- a/src/_includes/layouts/base.njk +++ b/src/_includes/layouts/base.njk @@ -414,6 +414,7 @@ eleventyComputed:
diff --git a/src/index.njk b/src/index.njk index b7f03ee6c6..62b589cd54 100644 --- a/src/index.njk +++ b/src/index.njk @@ -88,6 +88,7 @@ operationalSystem: - name: "Operational Data Pipelines" description: "Structured controller data flows, diagnostics, and routing." - name: "System Diagnostics" + url: "/use-cases/system-diagnostics/" description: "Error tracking and root cause analysis across deployed applications." meta: faq: diff --git a/src/use-cases/system-diagnostics.njk b/src/use-cases/system-diagnostics.njk new file mode 100644 index 0000000000..6c547a8be6 --- /dev/null +++ b/src/use-cases/system-diagnostics.njk @@ -0,0 +1,138 @@ +--- +title: "System Diagnostics" +meta: + title: "System Diagnostics | Use Cases | FlowFuse" + description: "Correlate signals across IT and OT systems to find out why things are slow, stuck or failing. Built on Node-RED, managed with FlowFuse." +problem: "When production IT misbehaves, the evidence is scattered across five systems and the person who can read them is on another site." +industries: ["automotive", "semiconductors"] +values: ["asset-reliability"] + +howItWorks: + heading: "How FlowFuse builds system diagnostics." + intro: "Diagnostics is a small emitter inside every deployed application and one place that collects what they report. This is how it breaks down and which FlowFuse pattern carries it." + designPattern: + kind: "Software pattern" + name: "Packaged application" + detail: "The diagnostics application is self-contained and deployed once per team. What it collects from arrives via a shared emitter block that every other application already carries, so coverage grows without touching the collector." + docsUrl: "/docs/user/shared-library/" + diagram: + placeholder: true + src: "https://placehold.co/1200x630/eef2ff/4338ca?text=System+Diagnostics+Architecture" + alt: "End-to-end architecture for system diagnostics: a shared emitter block inside every deployed application reporting structured errors to one collector, correlated by application, site and time, with alerting and a triage view." + caption: "A shared emitter inside every deployed application, reporting structured errors to one collector, correlated by application, site and time." + pieces: + - icon: "puzzle-piece" + title: "One emitter block, everywhere" + detail: "A subflow from the team library that every application carries, so an error looks the same whichever site or team produced it." + docsUrl: "/docs/user/shared-library/" + - icon: "bug" + title: "Structure the error" + detail: "Application, site, instance, severity and cause as fields rather than a log line someone has to read." + - icon: "project-nodes" + title: "Report without opening ports" + detail: "Project nodes and the broker carry reports out of edge networks that allow no inbound access." + docsUrl: "/docs/user/projectnodes/" + - icon: "funnel" + title: "Correlate across the estate" + detail: "The same fault on nine sites is one problem, not nine tickets. Grouping is what turns noise into a root cause." + - icon: "bell-alert" + title: "Alert on what is new" + detail: "Route first occurrences and rate changes to the person who owns that application, not everything to everyone." + - icon: "screen" + title: "Give triage one view" + detail: "What is broken, where, since when and how often, so the person who can read it does not have to be on site." + architecture: "it-ot-middleware" + docsCta: + label: "Read the shared library docs" + url: "/docs/user/shared-library/" + +customerPain: + heading: "Symptoms everywhere, causes nowhere." + intro: + - "Scanners time out, interfaces queue up, a line slows for no visible reason. The cause sits somewhere between the network, the middleware, the application and the machine, and each has its own console." + - "Diagnosis means an expert manually joining logs, tag values and timestamps across systems that were never meant to be read together." + cards: + - icon: "bug" + title: "Intermittent faults defy snapshots" + detail: "The problem is gone by the time someone looks; without continuous correlated capture there is nothing to analyze." + - icon: "layers" + title: "Evidence split across stacks" + detail: "Network metrics, application logs, PLC states and device telemetry live in unconnected tools." + - icon: "users" + title: "Diagnosis depends on one person" + detail: "The engineer who can read all five systems is a single point of failure for every incident." + - icon: "clock" + title: "Slow hunts, long incidents" + detail: "Hours of manual log pulling while production runs degraded." + #placeholder: template copy for review, refine per Showcase + +outcomeFirst: + heading: "One place where the signals meet." + intro: "FlowFuse flows collect and correlate the relevant signals continuously: device telemetry, interface queues, log events and process markers, so the picture exists before anyone has to ask for it." + dimensions: + - label: "Operational" + title: "Continuous evidence capture" + detail: "The signals that matter are collected and time-aligned around the clock, catching intermittent faults in the act." + - label: "Organizational" + title: "Diagnosis without the hero engineer" + detail: "Correlated views let more people resolve more incidents without cross-system expertise." + - label: "Financial" + title: "Shorter degraded-mode running" + detail: "Faster root cause means less time producing slowly, badly, or not at all." + +whyItMatters: + heading: "Degraded is the most expensive mode." + intro: "Hard failures get attention; slow drips of latency and retries quietly cost more." + points: + - title: "Intermittent issues age into outages" + detail: "What flickers today fails on the worst possible shift. Continuous capture is the only way to catch it early." + - title: "Cross-system blindness doubles incident time" + detail: "Most diagnostic time is spent gathering evidence, not analyzing it." + - title: "Tribal diagnostic knowledge does not scale" + detail: "Documenting correlation logic in flows turns one expert's method into a team capability." + +competition: + heading: "Why the usual approaches stall." + intro: "Observability tooling stops at the IT boundary; OT tooling stops at the machine." + traps: + - label: "IT observability" + title: "APM suites never see the PLC" + detail: "Enterprise monitoring covers servers and services but has no view of device or process state." + - label: "Vendor diagnostics" + title: "Every system diagnoses only itself" + detail: "Each console is right and none of them answer the cross-system question." + - label: "Manual forensics" + title: "Log pulls after the fact" + detail: "Evidence assembled per incident, too late for intermittent faults." + +comparison: + without: + - title: "Evidence gathered per incident" + detail: "Manual log pulls across systems, hours after the symptom." + - title: "One expert on the critical path" + detail: "Incidents queue behind a single person's availability." + - title: "Intermittent faults stay unsolved" + detail: "No continuous capture, no pattern, no fix." + with: + - title: "Signals correlated continuously" + detail: "Flows join telemetry, logs and process markers in real time." + - title: "Shared diagnostic views" + detail: "Dashboards anyone on the team can read and act on." + - title: "Patterns surface themselves" + detail: "Thresholds and trends flag recurring conditions before they escalate." + +aiBuildLayer: + intro: "The FlowFuse Expert works on this use case with you, from building collectors to querying what they capture." + steps: + - title: "Describe it, get a starting flow" + detail: "Tell the Expert which systems to watch; it assembles a collection and correlation starting flow. Currently in open beta on FlowFuse Cloud." + - title: "Ask questions in plain language" + detail: "Expose captured diagnostics through MCP tools and query them with Expert's Insights mode (beta): 'what changed before the scanners slowed down?'" + - title: "Own and adapt what you built" + detail: "The flow explainer documents collection logic, so the diagnostic method survives team changes." + note: "AI capabilities noted as beta are in open beta on FlowFuse Cloud at time of writing. Placeholder template copy for internal review." + +closingCta: + heading: "Stop diagnosing by archaeology" + description: "Talk to an expert about cross-system diagnostics, or wire your first correlated view today." +---