docs(PE-649): initial drafts of architecture/block diagrams for examples #104

jdmedlin1 · 2025-12-22T22:11:25Z

📝 Description

This PR adds architecture block diagrams to each of the examples in this project.
Some of the diagrams may need some rearranging to best display design or sequence.

Issue: Url to Jira Issue

📋 List of Changes

Each example has a drawio file at the root of its directory.

✔️ Dev Complete Checklist

PR template filled out
Change is tested by submitter
PR follows all linting and coding standards
Github Issue exists (if applicable)
Team member has been assigned
At least one commit message is in Conventional Commit format

Copilot

Pull request overview

This PR adds architecture block diagrams in DrawIO format to 14 example directories to improve visual documentation and help developers understand the system design and data flow for each example.

Adds comprehensive architecture diagrams showing component interactions and data flows
Includes legends for visual consistency and clarity
Provides flow notes and configuration details for better understanding

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
examples/send-plugin-message/architecture.drawio	Architecture diagram showing plugin message flow from video widgets through BrightScript handler to HTML application
examples/self-signed-certs/architecture.drawio	Diagram illustrating Node.js communication with BrightSign player's DWS using self-signed certificates
examples/provisioning-server/architecture.drawio	Architecture showing provisioning server flow with player check-ins, database logging, and content downloads
examples/node-starter/architecture.drawio	Simple diagram showing BrightSign player launching autorun.brs which starts Node.js HTTP server
examples/node-simple-server/architecture.drawio	Architecture depicting Node.js server serving static files and device info API
examples/local-storage/architecture.drawio	Diagram showing HTML slideshow caching images in browser localStorage
examples/indexeddb-caching/architecture.drawio	Architecture illustrating video caching using IndexedDB for offline playback
examples/htmlwidget-iframes/architecture.drawio	Diagram showing iframe trust configuration and BrightSign API access patterns
examples/html-starter/architecture.drawio	Simple architecture showing basic HTML widget loading and static file access
examples/enable-ldws/architecture.drawio	Comparison diagram showing three methods to enable LDWS (BrightScript, Node.js, Registry)
examples/cec-interface/architecture.drawio	Comparison of two CEC implementation methods (BrightScript roCecInterface vs JavaScript @brightsign/cec)
examples/bs-sqlite-db/architecture.drawio	Architecture showing BrightScript/Node.js SQLite database operations via MessagePort
examples/bs-self-updater/architecture.drawio	Diagram depicting self-updating flow with bootstrap autorun and Node.js updater downloading new versions
examples/bluetooth-scan/architecture.drawio	Architecture showing Bluetooth scanning via HTML/JS Bluetooth API

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-22T22:18:56Z

examples/enable-ldws/architecture.drawio

@@ -0,0 +1,193 @@
+<mxfile host="app.diagrams.net" modified="2024-01-01T00:00:00.000Z" agent="Claude" version="22.0.0">


The modified date is set to "2024-01-01T00:00:00.000Z" (January 1, 2024), which appears to be a placeholder or default value. Consider updating this to reflect the actual creation/modification date of the diagram.

Copilot · 2025-12-22T22:18:56Z

examples/bs-sqlite-db/architecture.drawio

@@ -0,0 +1,110 @@
+<mxfile host="app.diagrams.net" modified="2024-01-01T00:00:00.000Z" agent="Claude" version="22.0.0">


The modified date is set to "2024-01-01T00:00:00.000Z" (January 1, 2024), which appears to be a placeholder or default value. Consider updating this to reflect the actual creation/modification date of the diagram.

Copilot · 2025-12-22T22:18:56Z

examples/indexeddb-caching/architecture.drawio

+        </mxCell>
+
+        <!-- Flow annotation -->
+        <mxCell id="flow-note" value="Caching Strategy:&lt;br&gt;1. Create IndexedDB (videos_db/videos_os)&lt;br&gt;2. Check cache for existing videos&lt;br&gt;3. Play first video (cached or download)&lt;br&gt;4. Background download remaining videos&lt;br&gt;5. Store video blobs in IndexedDB&lt;br&gt;6. Subsequent playback from cache&lt;br&gt;7. Auto-advance &amp; loop playlist" style="text;html=1;strokeColor=#333333;fillColor=#ffffff;align=left;verticalAlign=top;whiteSpace=wrap;rounded=0;fontSize=11;strokeWidth=1;" vertex="1" parent="1">


The text mentions "videos_db/videos_os" but "videos_os" appears to be a typo. It should likely be "videos_store" or "videos" (the object store name within the IndexedDB database).

Suggested change

<mxCell id="flow-note" value="Caching Strategy: 1. Create IndexedDB (videos_db/videos_os) 2. Check cache for existing videos 3. Play first video (cached or download) 4. Background download remaining videos 5. Store video blobs in IndexedDB 6. Subsequent playback from cache 7. Auto-advance & loop playlist" style="text;html=1;strokeColor=#333333;fillColor=#ffffff;align=left;verticalAlign=top;whiteSpace=wrap;rounded=0;fontSize=11;strokeWidth=1;" vertex="1" parent="1">

<mxCell id="flow-note" value="Caching Strategy: 1. Create IndexedDB (videos_db/videos_store) 2. Check cache for existing videos 3. Play first video (cached or download) 4. Background download remaining videos 5. Store video blobs in IndexedDB 6. Subsequent playback from cache 7. Auto-advance & loop playlist" style="text;html=1;strokeColor=#333333;fillColor=#ffffff;align=left;verticalAlign=top;whiteSpace=wrap;rounded=0;fontSize=11;strokeWidth=1;" vertex="1" parent="1">

Copilot · 2025-12-22T22:18:57Z

examples/provisioning-server/architecture.drawio

@@ -0,0 +1,166 @@
+<mxfile host="app.diagrams.net" modified="2024-01-01T00:00:00.000Z" agent="Claude" version="22.0.0">


The modified date is set to "2024-01-01T00:00:00.000Z" (January 1, 2024), which appears to be a placeholder or default value. Consider updating this to reflect the actual creation/modification date of the diagram.

Copilot · 2025-12-22T22:18:57Z

examples/htmlwidget-iframes/architecture.drawio

@@ -0,0 +1,131 @@
+<mxfile host="app.diagrams.net" modified="2024-01-01T00:00:00.000Z" agent="Claude" version="22.0.0">


The modified date is set to "2024-01-01T00:00:00.000Z" (January 1, 2024), which appears to be a placeholder or default value. Consider updating this to reflect the actual creation/modification date of the diagram.

Copilot · 2025-12-22T22:18:59Z

examples/local-storage/architecture.drawio

@@ -0,0 +1,121 @@
+<mxfile host="app.diagrams.net" modified="2024-01-01T00:00:00.000Z" agent="Claude" version="22.0.0">


The modified date is set to "2024-01-01T00:00:00.000Z" (January 1, 2024), which appears to be a placeholder or default value. Consider updating this to reflect the actual creation/modification date of the diagram.

Suggested change

<mxfile host="app.diagrams.net" modified="2024-01-01T00:00:00.000Z" agent="Claude" version="22.0.0">

<mxfile host="app.diagrams.net" modified="2025-12-22T00:00:00.000Z" agent="Claude" version="22.0.0">

Copilot · 2025-12-22T22:18:59Z

examples/bs-self-updater/architecture.drawio

@@ -0,0 +1,169 @@
+<mxfile host="app.diagrams.net" modified="2024-01-01T00:00:00.000Z" agent="Claude" version="22.0.0">


The modified date is set to "2024-01-01T00:00:00.000Z" (January 1, 2024), which appears to be a placeholder or default value. Consider updating this to reflect the actual creation/modification date of the diagram.

Suggested change

<mxfile host="app.diagrams.net" modified="2024-01-01T00:00:00.000Z" agent="Claude" version="22.0.0">

<mxfile host="app.diagrams.net" modified="2025-12-22T00:00:00.000Z" agent="Claude" version="22.0.0">

Copilot · 2025-12-22T22:18:59Z

examples/self-signed-certs/architecture.drawio

@@ -0,0 +1,131 @@
+<mxfile host="app.diagrams.net" modified="2024-01-01T00:00:00.000Z" agent="Claude" version="22.0.0">


The modified date is set to "2024-01-01T00:00:00.000Z" (January 1, 2024), which appears to be a placeholder or default value. Consider updating this to reflect the actual creation/modification date of the diagram.

Copilot · 2025-12-22T22:19:00Z

examples/html-starter/architecture.drawio

@@ -0,0 +1,90 @@
+<mxfile host="app.diagrams.net" modified="2024-01-01T00:00:00.000Z" agent="Claude" version="22.0.0">


The modified date is set to "2024-01-01T00:00:00.000Z" (January 1, 2024), which appears to be a placeholder or default value. Consider updating this to reflect the actual creation/modification date of the diagram.

Copilot · 2025-12-22T22:19:00Z

examples/bs-self-updater/architecture.drawio

+        <mxCell id="arrow3" value="3. HTTP GET&lt;br&gt;Download autorun.zip" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#000000;strokeWidth=2;startArrow=classic;startFill=1;endArrow=classic;endFill=1;" edge="1" parent="1" source="nodejs" target="server">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>


This self-update flow shows index.js performing an HTTP GET to download autorun.zip from SERVER_URL and then replacing autorun.brs with its contents, but the implementation uses plain http:// and does not perform any cryptographic integrity or authenticity checks on the zip. If an attacker can spoof or intercept the connection to the update server (for example via network MITM or by compromising the server), they can supply a malicious autorun.zip and gain arbitrary code execution on the player. The update mechanism should require HTTPS with certificate validation and verify a strong cryptographic signature or pinned hash for the update package before unzipping and activating it.

blshukla

Could we create these as mermaid diagrams in markdown files? That way it can be viewed in github easily.

jdmedlin1 · 2025-12-27T01:33:11Z

Have we decided to go forward with Mermaid or DrawIO?

If it is easy enough to change to Mermaid, then let's use that since it is easier to read and review.

bhastings1019 · 2026-01-10T00:30:18Z

Looked over a few of the examples. Couple bits of feedback.
1/ White background black text between boxes makes it difficult to see the arrow.
2/ If we stick with drawio consider bunlding to png and adding to markdown or /docs folder.

Otherwise looks good. Will continue to consult whether we best leverage drawio or mermaid, or other tools.

…wio diagrams

docs(PE-649): initial drafts of architecture diagrams for examples

c2dcc99

Copilot AI review requested due to automatic review settings December 22, 2025 22:11

jdmedlin1 self-assigned this Dec 22, 2025

jdmedlin1 requested review from bhastings1019, blshukla and evan-morgan December 22, 2025 22:11

Copilot started reviewing on behalf of jdmedlin1 December 22, 2025 22:11 View session

Copilot AI reviewed Dec 22, 2025

View reviewed changes

blshukla reviewed Dec 22, 2025

View reviewed changes

docs(PE-649): added mermaid diagrams as alternative references to dra…

ed4398b

…wio diagrams

		@@ -0,0 +1,193 @@
		<mxfile host="app.diagrams.net" modified="2024-01-01T00:00:00.000Z" agent="Claude" version="22.0.0">

		@@ -0,0 +1,110 @@
		<mxfile host="app.diagrams.net" modified="2024-01-01T00:00:00.000Z" agent="Claude" version="22.0.0">

		@@ -0,0 +1,166 @@
		<mxfile host="app.diagrams.net" modified="2024-01-01T00:00:00.000Z" agent="Claude" version="22.0.0">

		@@ -0,0 +1,131 @@
		<mxfile host="app.diagrams.net" modified="2024-01-01T00:00:00.000Z" agent="Claude" version="22.0.0">

		@@ -0,0 +1,121 @@
		<mxfile host="app.diagrams.net" modified="2024-01-01T00:00:00.000Z" agent="Claude" version="22.0.0">

		@@ -0,0 +1,169 @@
		<mxfile host="app.diagrams.net" modified="2024-01-01T00:00:00.000Z" agent="Claude" version="22.0.0">

		@@ -0,0 +1,90 @@
		<mxfile host="app.diagrams.net" modified="2024-01-01T00:00:00.000Z" agent="Claude" version="22.0.0">

docs(PE-649): initial drafts of architecture/block diagrams for examples #104

Are you sure you want to change the base?

docs(PE-649): initial drafts of architecture/block diagrams for examples #104

Uh oh!

Conversation

jdmedlin1 commented Dec 22, 2025

📝 Description

📋 List of Changes

✔️ Dev Complete Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

blshukla left a comment

Choose a reason for hiding this comment

Uh oh!

jdmedlin1 commented Dec 27, 2025 • edited by blshukla Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bhastings1019 commented Jan 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jdmedlin1 commented Dec 27, 2025 •

edited by blshukla

Loading