From c9ed6646a6f69b08127b694f36d75dc3bd2a2c78 Mon Sep 17 00:00:00 2001 From: Justin Fagnani Date: Wed, 8 Nov 2023 18:13:56 -0800 Subject: [PATCH 1/5] Add ARCHITECTURE.md --- ARCHITECTURE.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 ARCHITECTURE.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 00000000..a3c8ab35 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,51 @@ +# Architecture + +The Playground elements have three features that require a somewhat complex architecture: + +- Loading files from the main window into a preview iframe without using a server +- Compiling TypeScript files and resolving bare import specifiers on the fly +- Loading dependencies from a CDN + +To accomplish this, the Playground elements have a somewhat complex set of workers and iframes: +- A preview iframe +- A service worker to serve files to the preview iframe +- A web worker to compile TypeScript files and resolve bare import specifiers +- A proxy iframe to install and communicate with the service worker from the main page + +These workers and iframes are controlled by various Playground elements like ``, ``, and ``. + +```mermaid +flowchart TD + IDE{{<playground-ide>}} + subgraph Project + ProjectElement{{<playground-project>}} + WebWorker(Build Worker) + ProxyIframe[Proxy <iframe>] + end + subgraph Editors + FileEditor1{{<playground-file-editor>}} + FileEditor2{{<playground-file-editor>}} + end + subgraph Preview + PreviewElement{{<playground-preview>}} + PreviewIframe[Preview <iframe>] + end + subgraph Network + ServiceWorker(Service Worker) + CDN([CDN]) + end + + IDE -...-> Project + IDE -.-> Editors + IDE -.-> Preview + WebWorker -- Built Project Files --> ProjectElement + ProjectElement -- Project Files --> WebWorker + ProjectElement -- Built Project Files --> ProxyIframe + Editors -- Project Files --> ProjectElement + ProjectElement --> PreviewElement + PreviewElement <--> PreviewIframe + ProxyIframe -- Built Project Files --> ServiceWorker + ServiceWorker -- All Files --> PreviewIframe + CDN -- NPM Dependencies --> ServiceWorker + CDN -- TypeScript Types --> WebWorker +``` From 8ba0233850e2e74144e5d287baac1808e86e8d50 Mon Sep 17 00:00:00 2001 From: Justin Fagnani Date: Wed, 8 Nov 2023 18:18:41 -0800 Subject: [PATCH 2/5] Try to fix unknown GH Mermaid error --- ARCHITECTURE.md | 62 ++++++++++++++++++++++++------------------------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index a3c8ab35..7e966d1f 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -16,36 +16,36 @@ These workers and iframes are controlled by various Playground elements like `

}} - subgraph Project - ProjectElement{{<playground-project>}} - WebWorker(Build Worker) - ProxyIframe[Proxy <iframe>] - end - subgraph Editors - FileEditor1{{<playground-file-editor>}} - FileEditor2{{<playground-file-editor>}} - end - subgraph Preview - PreviewElement{{<playground-preview>}} - PreviewIframe[Preview <iframe>] - end - subgraph Network - ServiceWorker(Service Worker) - CDN([CDN]) - end + IDE{{<playground-ide>}}; + subgraph Project; + ProjectElement{{<playground-project>}}; + WebWorker(Build Worker); + ProxyIframe[Proxy <iframe>]; + end; + subgraph Editors; + FileEditor1{{<playground-file-editor>}}; + FileEditor2{{<playground-file-editor>}}; + end; + subgraph Preview; + PreviewElement{{<playground-preview>}}; + PreviewIframe[Preview <iframe>]; + end; + subgraph Network; + ServiceWorker(Service Worker); + CDN([CDN]); + end; - IDE -...-> Project - IDE -.-> Editors - IDE -.-> Preview - WebWorker -- Built Project Files --> ProjectElement - ProjectElement -- Project Files --> WebWorker - ProjectElement -- Built Project Files --> ProxyIframe - Editors -- Project Files --> ProjectElement - ProjectElement --> PreviewElement - PreviewElement <--> PreviewIframe - ProxyIframe -- Built Project Files --> ServiceWorker - ServiceWorker -- All Files --> PreviewIframe - CDN -- NPM Dependencies --> ServiceWorker - CDN -- TypeScript Types --> WebWorker + IDE -...-> Project; + IDE -.-> Editors; + IDE -.-> Preview; + WebWorker -- Built Project Files --> ProjectElement; + ProjectElement -- Project Files --> WebWorker; + ProjectElement -- Built Project Files --> ProxyIframe; + Editors -- Project Files --> ProjectElement; + ProjectElement --> PreviewElement; + PreviewElement <--> PreviewIframe; + ProxyIframe -- Built Project Files --> ServiceWorker; + ServiceWorker -- All Files --> PreviewIframe; + CDN -- NPM Dependencies --> ServiceWorker; + CDN -- TypeScript Types --> WebWorker; ``` From c1aebe3ffc6927ee75599166318bc202e623a7ea Mon Sep 17 00:00:00 2001 From: Justin Fagnani Date: Wed, 8 Nov 2023 18:19:58 -0800 Subject: [PATCH 3/5] attempt #2 --- ARCHITECTURE.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 7e966d1f..0390382c 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -16,26 +16,26 @@ These workers and iframes are controlled by various Playground elements like `

}}; + IDE{{playground-ide}}; subgraph Project; - ProjectElement{{<playground-project>}}; + ProjectElement{{playground-project}}; WebWorker(Build Worker); - ProxyIframe[Proxy <iframe>]; + ProxyIframe[Proxy iframe]; end; subgraph Editors; - FileEditor1{{<playground-file-editor>}}; - FileEditor2{{<playground-file-editor>}}; + FileEditor1{{playground-file-editor}}; + FileEditor2{{playground-file-editor}}; end; subgraph Preview; - PreviewElement{{<playground-preview>}}; - PreviewIframe[Preview <iframe>]; + PreviewElement{{playground-preview}}; + PreviewIframe[Preview iframe]; end; subgraph Network; ServiceWorker(Service Worker); CDN([CDN]); end; - IDE -...-> Project; + IDE -.-> Project; IDE -.-> Editors; IDE -.-> Preview; WebWorker -- Built Project Files --> ProjectElement; From 90c77ed19c5cd797831a3a3995edeacd8f683a1f Mon Sep 17 00:00:00 2001 From: Justin Fagnani Date: Wed, 8 Nov 2023 18:38:01 -0800 Subject: [PATCH 4/5] Simpler chart --- ARCHITECTURE.md | 55 +++++++++++++++++++++---------------------------- 1 file changed, 24 insertions(+), 31 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 0390382c..d78516ad 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -16,36 +16,29 @@ These workers and iframes are controlled by various Playground elements like `

Project; - IDE -.-> Editors; - IDE -.-> Preview; - WebWorker -- Built Project Files --> ProjectElement; - ProjectElement -- Project Files --> WebWorker; - ProjectElement -- Built Project Files --> ProxyIframe; - Editors -- Project Files --> ProjectElement; - ProjectElement --> PreviewElement; - PreviewElement <--> PreviewIframe; - ProxyIframe -- Built Project Files --> ServiceWorker; - ServiceWorker -- All Files --> PreviewIframe; - CDN -- NPM Dependencies --> ServiceWorker; - CDN -- TypeScript Types --> WebWorker; + ServiceWorker -- All Files --> PreviewIframe + ProjectElement -- Built Files --> ProxyIframe + Editors -- Project Files --> ProjectElement + ProjectElement -...-> PreviewElement + PreviewElement -.-> PreviewIframe + ProxyIframe -- Built Files --> ServiceWorker + WebWorker -- Built Files --> ProjectElement + ProjectElement -- Project Files --> WebWorker + CDN -- NPM Dependencies --> WebWorker ``` From 4a518712c982e5a83279b17ce2648d6fb36b77f1 Mon Sep 17 00:00:00 2001 From: Justin Fagnani Date: Tue, 14 Nov 2023 13:13:14 -0800 Subject: [PATCH 5/5] Add sequence diagram --- ARCHITECTURE.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index d78516ad..c5374193 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -7,6 +7,7 @@ The Playground elements have three features that require a somewhat complex arch - Loading dependencies from a CDN To accomplish this, the Playground elements have a somewhat complex set of workers and iframes: +- A playground-project element that coordinates most of the initialization and communication - A preview iframe - A service worker to serve files to the preview iframe - A web worker to compile TypeScript files and resolve bare import specifiers @@ -14,6 +15,8 @@ To accomplish this, the Playground elements have a somewhat complex set of worke These workers and iframes are controlled by various Playground elements like ``, ``, and ``. +This chart shows the data flow between components. The arrows show the direction of the primary flow of data, ie, the file being transferred, not the message requesting the file. + ```mermaid flowchart TD subgraph Project @@ -42,3 +45,42 @@ flowchart TD ProjectElement -- Project Files --> WebWorker CDN -- NPM Dependencies --> WebWorker ``` + +This diagram shows the sequence of messages and events between components. + +ALL_CAPS labels are direct `postMessage()` messages. methodName() labels on solid lines are Comlink remote method calls over MessagePorts. methodName() labels on loop-back dotted lines are important local invocations. Other dotted lines are responses or browser events. + +```mermaid +sequenceDiagram + participant Project as playground-project + participant Proxy as Proxy iframe + participant Preview as Preview iframe + participant ServiceWorker as Service Worker + participant BuildWorker as Build Worker + Proxy -->> Project: load event + activate Project + Project ->>+ Proxy: CONFIGURE_PROXY + deactivate Project + Proxy -->> Proxy: navigator.serviceWorker.register() + Proxy ->>+ ServiceWorker: CONNECT_SW_TO_PROJECT + Proxy ->>- Project: CONNECT_PROJECT_TO_SW + ServiceWorker ->>- Project: ACKNOWLEDGE_SW_CONNECTION + activate Project + Project ->> ServiceWorker: setFileAPI() + deactivate Project + Project -->> Project: _loadProjectFromSource() + Project ->> BuildWorker: compileProject() + activate BuildWorker + Preview -->> ServiceWorker: fetch event + activate ServiceWorker + ServiceWorker ->> Project: getFile() + activate Project + Project ->> BuildWorker: getFile() + BuildWorker -->> Project: File + deactivate BuildWorker + Project -->> ServiceWorker: File + deactivate Project + ServiceWorker -->> Preview: File + deactivate ServiceWorker + +```