From 58f4c65d294ddf6e00177b91a4b28b0e28685755 Mon Sep 17 00:00:00 2001
From: Jane Chu <7559015+janechu@users.noreply.github.com>
Date: Tue, 29 Oct 2024 12:03:41 -0700
Subject: [PATCH 01/13] Add documentation explaining some architectural
 concepts

---
 .../fast-element/ARCHITECTURE.md              | 134 ++++++++++++++++++
 1 file changed, 134 insertions(+)
 create mode 100644 packages/web-components/fast-element/ARCHITECTURE.md

diff --git a/packages/web-components/fast-element/ARCHITECTURE.md b/packages/web-components/fast-element/ARCHITECTURE.md
new file mode 100644
index 00000000000..3baf5d2b396
--- /dev/null
+++ b/packages/web-components/fast-element/ARCHITECTURE.md
@@ -0,0 +1,134 @@
+# Architecture
+
+This document explains varous logical flows for how a `FASTElement` is composed, defined, rendered, and updated.
+
+## What is FASTElement?
+
+`FASTElement` is an extension of `HTMLElement` which makes use of Custom Element APIs native to the browser. It also supplies the following methods `compose`, `define`, and `from`.
+
+- The `compose` method combines the Custom Element name, template, style, and other options to create the definition for the Custom Element.
+- The `define` method makes use of the native Custom Element `define` to register the Custom Element with a Custom Element Registry.
+- The `from` method allows the use of Custom Built-Ins so that a user does not need to define a template but can specify a native `HTMLElement` such as `HTMLButtonElement`.
+
+## Creating a Custom Element from FASTElement
+
+A basic developer flow for defining a custom element looks like this:
+
+```mermaid
+flowchart TD
+    A[Create a FASTElement web component by extending the FASTElement Class] --> F
+    F[Compose with FASTElement.compose to include template and styles] --> G[Define the component in the browser with FASTElement.define]
+```
+
+Let's take a close look at the compose and define steps to see what the FAST architecture is doing.
+
+## Composing a Custom Element
+
+Using `FASTElement.compose` this creates a new `FASTElementDefinition` which includes all metadata needed for the element such as templates, attributes, styles, etc. this then registers the element with the global FAST for re-use and returns the `FASTElementDefinition` which can be referenced by `ElementController.definition`.
+
+## A Custom Element in JavaScript sent to the Browser
+
+Let's step back from defining the Custom Element and consider what is happening when we import from the `@microsoft/fast-element` package.
+
+First, a global `FAST` property will be created if one does not already exist, typically in browser on the `window`.
+
+Additionally, when Custom Elements are included in a script a few things might happen even before a Custom Element gets detected by the browser. First, there are initial side effects caused by the use of decorators. These include the `attr` and `observable` decorators made available by the `@microsoft/fast-element` package.
+
+```mermaid
+flowchart TD
+    A[The browser loads the JavaScript file containing FAST]
+    A --> B[The FAST global is added]
+    B --> C[Any defined observable decorators are added to the FAST global]
+    A --> D[Any defined attribute decorators are attached to the constructor of the FAST Custom Element]
+```
+
+### Pre-render Template
+
+The `html` tag template is typically used to create a `ViewTemplate` using the `ViewTemplate.create` method. This is executed and passed during the `compose` step and before `FASTElement` is instantiated.
+
+During the `ViewTemplate.create` step, the following happens for each string:
+- Factories with unique IDs are created for each tag template literal argument (or `TemplateValue`) which matches with the corresponding string
+- A binding is created from the `TemplateValue`
+
+A resulting string using `createHTML` function is created using the `HTMLDirective`, the previous string from the `html` tag template which determines the aspect if one exists, these aspects are the `@`, `:`, or other binding aspect attached to attributes. The `createHTML` returns a `Markup` attribute using the factory that has a unique ID. This is all concatenated as a string and passed to a new `ViewTemplate` with all the factories (empty until one is assigned) that act as a dictionary with the unique IDs as the key to look up each factory once it has been created.
+
+#### HTML Binding Directives
+
+The `HTMLBindingDirective` applies bindings to items identified as various `TemplateValue` within the `html` tag template. The `createHTML` step uses the factory associated with the binding to create strings in the markup using the factory's ID.
+
+```mermaid
+flowchart TD
+    A[A new HTMLBindingDirective is created with a data binding which has a policy, options, createObserver, and an evaluate method assigned to the passed arrow function such as x => x.foo]
+    B[oneTime binding passes the corresponding tag template argument, an arrow function]
+    C[oneWay binding passes a copy of the corresponding tag template argument, an arrow function]
+    D[An already specified binding such as a repeat or when directive]
+    A --> B
+    A --> C
+    A --> D
+    E[When a createObserver is called, an Observable.binding is created passing the arrow function to be evaluated and the subscriber to be notified]
+    C --> E
+    F[When a createObserver is called, the instance of the one time binding is returned which includes a bind method returning the arrow function executed against the controller source and context]
+    B --> F
+```
+
+## A Custom Element is Detected by the Browser
+
+Because the `FASTElement` is an extension of the `HTMLElement`, it makes use of the same lifecycle hooks and extends them with `$fastController`. It also initializes using another class `ElementController`, the methods this are called during the custom elements native `constructor`, `connectedCallback`, `disconnectedCallback`, and `attributeChangedCallback` lifecycle hooks.
+
+### 🔄 **Lifecycle**: Initialization
+
+```mermaid
+flowchart TD
+    A[A FASTElement web component is added to the DOM] --> B
+    B[FASTElement initializes the ElementController.forCustomElement passing the Custom Element instance] --> C
+    B --> F[Observables applied to the FASTElement are updated on the FAST global without values]
+    C{Is an ElementController available?}
+    C --> |yes|E
+    C --> |no|D
+    D[Initialize a new ElementController referred to as setting an element controller strategy]
+    D --> F
+    E[ElementController captures the Custom Element instance and the definition and attaches them to the $fastController which is then attached to the instance]
+```
+
+### 🔄 **Lifecycle**: Component is connected
+
+```mermaid
+flowchart TD
+    A[browser HTMLElement's connectedCallback is called] --> B
+    B[this.$fastController.connect in FASTElement is called] --> C
+    B --> D
+    B --> E
+    B --> F
+    C[bind observables by capturing the Custom Elements properties and setting the values from the bound observables on the Custom Element]
+    D[connect behaviors by call the connectedCallback on all behaviors]
+    E[render template, execute an ElementViewTemplate's render method]
+    F[add styles either as an appended StyleElement node or an adoptedStylesheet which may include and attach behaviors]
+```
+
+#### Render Template
+
+The rendering of the template on the `ElementController` is by the `renderTemplate` method which is called during the `ElementController.connect` method which is triggered by `HTMLElement`s `connectedCallback` lifecycle.
+
+The `renderTemplate` identifies the Custom Element, and the shadow root associated with the Custom Element. This then places a rendering of the template (an `ElementView`) onto the internal `view` of the controller. When creating the `ElementView`/`HTMLView` using the `ViewTemplate.render`, the `Compile.compile` identifies a `DocumentFragment` either by using an existing `<template>` tag, or creating one to wrap the contents of the shadow root. A new `CompilationContext` is created and the `compileAttributes` function is called, this results in the replacement of the placeholder attributes initally set-up during the pre-render step with their values if a value has been assigned. The factories with the associated nodes identified are then passed to the context. The view then binds all behaviors to the source element. The `CompilationContext.createView` is executed with the `DocumentFragment` as the root, and returns an `HTMLView`. This `HTMLView` includes an `appendTo` method to attach the fragment to the host element, which it then does. It should be noted that the compiled HTML is a `string`, which when set on the `DocumentFragment` as `innerHTML`, this allows the browser to dictate the creation of HTML nodes.
+
+### 🔄 **Lifecycle**: Component is disconnected
+
+When a component is disconnected, a cleanup step is created to remove associated behaviors.
+
+### 🔄 **Lifecycle**: Attribute has been changed
+
+Attributes have an `AttributeDefinition` which allows for converters, attachment of the `<attributName>Changed` aspect of the `@attr` decorator among other capabilities.
+
+```mermaid
+flowchart TD
+    A[browser HTMLElement's attributeChangedCallback is called] --> B
+    B[this.$fastController.onAttributeChangedCallback in FASTElement is called] --> C
+    C[calls the attribute definitions onAttributeChangedCallback method with the updated value] --> D
+    D[An Updates.enqueue is called which places the update in the task queue which is then executed, these are performed async unless otherwise specified]
+```
+
+These changes are observed and similar to the way `Observables` work, they utilize an `Accessor` pattern which has a `getValue` and `setValue` in which DOM updates are applied.
+
+### Observables are updated
+
+The `Reflect` API is used to override `defineProperty` in order to observe a property on an Custom Element, this overrides the getter and setter, which allows subscribers to be notified of changes. Any changes which `set` the value are passed to the `Updates` queue which has been added to the FAST Global.
\ No newline at end of file

From 25bc0021bff811b9e2dc7891c4e2093ce6d1232a Mon Sep 17 00:00:00 2001
From: Jane Chu <7559015+janechu@users.noreply.github.com>
Date: Tue, 29 Oct 2024 12:21:17 -0700
Subject: [PATCH 02/13] Formatting

---
 .../fast-element/ARCHITECTURE.md              | 48 +++++++++----------
 1 file changed, 24 insertions(+), 24 deletions(-)

diff --git a/packages/web-components/fast-element/ARCHITECTURE.md b/packages/web-components/fast-element/ARCHITECTURE.md
index 3baf5d2b396..9f8eeaaf69f 100644
--- a/packages/web-components/fast-element/ARCHITECTURE.md
+++ b/packages/web-components/fast-element/ARCHITECTURE.md
@@ -1,6 +1,6 @@
 # Architecture
 
-This document explains varous logical flows for how a `FASTElement` is composed, defined, rendered, and updated.
+This document explains various logical flows for how a `FASTElement` is composed, defined, rendered, and updated.
 
 ## What is FASTElement?
 
@@ -16,8 +16,8 @@ A basic developer flow for defining a custom element looks like this:
 
 ```mermaid
 flowchart TD
-    A[Create a FASTElement web component by extending the FASTElement Class] --> F
-    F[Compose with FASTElement.compose to include template and styles] --> G[Define the component in the browser with FASTElement.define]
+    A[Create a <code>FASTElement</code> web component by extending the <code>FASTElement</code> class] --> F
+    F[Compose with <code>FASTElement.compose</code> to include template and styles] --> G[Define the component in the browser with <code>FASTElement.define</code>]
 ```
 
 Let's take a close look at the compose and define steps to see what the FAST architecture is doing.
@@ -58,16 +58,16 @@ The `HTMLBindingDirective` applies bindings to items identified as various `Temp
 
 ```mermaid
 flowchart TD
-    A[A new HTMLBindingDirective is created with a data binding which has a policy, options, createObserver, and an evaluate method assigned to the passed arrow function such as x => x.foo]
-    B[oneTime binding passes the corresponding tag template argument, an arrow function]
-    C[oneWay binding passes a copy of the corresponding tag template argument, an arrow function]
-    D[An already specified binding such as a repeat or when directive]
+    A[A <code>new HTMLBindingDirective</code> is created with a data binding which has a policy, options, <code>createObserver</code>, and an evaluate method assigned to the passed arrow function such as <pre>x => x.foo</pre>]
+    B[<code>oneTime</code> binding passes the corresponding tag template argument, an arrow function]
+    C[<code>oneWay</code> binding passes a copy of the corresponding tag template argument, an arrow function]
+    D[An already specified binding such as a repeat or when directive is passed]
     A --> B
     A --> C
     A --> D
-    E[When a createObserver is called, an Observable.binding is created passing the arrow function to be evaluated and the subscriber to be notified]
+    E[When a <code>createObserver</code> is called, an <code>Observable.binding</code> is created passing the arrow function to be evaluated and the subscriber to be notified]
     C --> E
-    F[When a createObserver is called, the instance of the one time binding is returned which includes a bind method returning the arrow function executed against the controller source and context]
+    F[When a <code>createObserver</code> is called, the instance of the one time binding is returned which includes a bind method returning the arrow function executed against the controller source and context]
     B --> F
 ```
 
@@ -79,30 +79,30 @@ Because the `FASTElement` is an extension of the `HTMLElement`, it makes use of
 
 ```mermaid
 flowchart TD
-    A[A FASTElement web component is added to the DOM] --> B
-    B[FASTElement initializes the ElementController.forCustomElement passing the Custom Element instance] --> C
-    B --> F[Observables applied to the FASTElement are updated on the FAST global without values]
-    C{Is an ElementController available?}
+    A[A <code>FASTElement</code> web component is added to the <code>DOM</code>] --> B
+    B[<code>FASTElement</code> initializes the <code>ElementController.forCustomElement</code> passing the Custom Element instance] --> C
+    B --> F[Observables applied to the <code>FASTElement</code> are updated on the FAST global without values]
+    C{Is an <code>ElementController</code> available?}
     C --> |yes|E
     C --> |no|D
-    D[Initialize a new ElementController referred to as setting an element controller strategy]
+    D[Initialize a new <code>ElementController</code> referred to as setting an element controller strategy]
     D --> F
-    E[ElementController captures the Custom Element instance and the definition and attaches them to the $fastController which is then attached to the instance]
+    E[<code>ElementController</code> captures the Custom Element instance and the definition and attaches them to the <code>$fastController</code> which is then attached to the instance]
 ```
 
 ### 🔄 **Lifecycle**: Component is connected
 
 ```mermaid
 flowchart TD
-    A[browser HTMLElement's connectedCallback is called] --> B
-    B[this.$fastController.connect in FASTElement is called] --> C
+    A[browser <code>HTMLElement</code>'s <code>connectedCallback</code> is called] --> B
+    B[<code>this.$fastController.connect</code> in FASTElement is called] --> C
     B --> D
     B --> E
     B --> F
     C[bind observables by capturing the Custom Elements properties and setting the values from the bound observables on the Custom Element]
-    D[connect behaviors by call the connectedCallback on all behaviors]
-    E[render template, execute an ElementViewTemplate's render method]
-    F[add styles either as an appended StyleElement node or an adoptedStylesheet which may include and attach behaviors]
+    D[connect behaviors by call the <code>connectedCallback</code> on all behaviors]
+    E[render template, execute an <code>ElementViewTemplate</code>'s render method]
+    F[add styles either as an appended <code>StyleElement</code> node or an <code>adoptedStylesheet</code> which may include and attach behaviors]
 ```
 
 #### Render Template
@@ -121,10 +121,10 @@ Attributes have an `AttributeDefinition` which allows for converters, attachment
 
 ```mermaid
 flowchart TD
-    A[browser HTMLElement's attributeChangedCallback is called] --> B
-    B[this.$fastController.onAttributeChangedCallback in FASTElement is called] --> C
-    C[calls the attribute definitions onAttributeChangedCallback method with the updated value] --> D
-    D[An Updates.enqueue is called which places the update in the task queue which is then executed, these are performed async unless otherwise specified]
+    A[The browser <code>HTMLElement</code>'s <code>attributeChangedCallback</code> is called] --> B
+    B[<code>this.$fastController.onAttributeChangedCallback</code> in <code>FASTElement</code> is called] --> C
+    C[calls the attribute definitions <code>onAttributeChangedCallback</code> method with the updated value] --> D
+    D[An <code>Updates.enqueue</code> is called which places the update in the task queue which is then executed, these are performed async unless otherwise specified]
 ```
 
 These changes are observed and similar to the way `Observables` work, they utilize an `Accessor` pattern which has a `getValue` and `setValue` in which DOM updates are applied.

From 324cff7400254587ac12aad93ea5cfdc54836bd4 Mon Sep 17 00:00:00 2001
From: Jane Chu <7559015+janechu@users.noreply.github.com>
Date: Tue, 29 Oct 2024 13:24:05 -0700
Subject: [PATCH 03/13] Change files

---
 ...-fast-element-e44aecad-1602-46a6-a317-92f22a19d964.json | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 change/@microsoft-fast-element-e44aecad-1602-46a6-a317-92f22a19d964.json

diff --git a/change/@microsoft-fast-element-e44aecad-1602-46a6-a317-92f22a19d964.json b/change/@microsoft-fast-element-e44aecad-1602-46a6-a317-92f22a19d964.json
new file mode 100644
index 00000000000..1486986567e
--- /dev/null
+++ b/change/@microsoft-fast-element-e44aecad-1602-46a6-a317-92f22a19d964.json
@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "Add documentation explaining some architectural concepts",
+  "packageName": "@microsoft/fast-element",
+  "email": "7559015+janechu@users.noreply.github.com",
+  "dependentChangeType": "none"
+}

From 101cbb3a42a4d55fd6db8ff99f10483fda1cff21 Mon Sep 17 00:00:00 2001
From: Jane Chu <7559015+janechu@users.noreply.github.com>
Date: Wed, 30 Oct 2024 13:34:25 -0700
Subject: [PATCH 04/13] Update
 packages/web-components/fast-element/ARCHITECTURE.md

Co-authored-by: John Kreitlow <863023+radium-v@users.noreply.github.com>
---
 packages/web-components/fast-element/ARCHITECTURE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/web-components/fast-element/ARCHITECTURE.md b/packages/web-components/fast-element/ARCHITECTURE.md
index 9f8eeaaf69f..b67d17334cd 100644
--- a/packages/web-components/fast-element/ARCHITECTURE.md
+++ b/packages/web-components/fast-element/ARCHITECTURE.md
@@ -4,7 +4,7 @@ This document explains various logical flows for how a `FASTElement` is composed
 
 ## What is FASTElement?
 
-`FASTElement` is an extension of `HTMLElement` which makes use of Custom Element APIs native to the browser. It also supplies the following methods `compose`, `define`, and `from`.
+`FASTElement` is an extension of `HTMLElement` which makes use of Custom Element APIs native to the browser. It also supplies the following methods:
 
 - The `compose` method combines the Custom Element name, template, style, and other options to create the definition for the Custom Element.
 - The `define` method makes use of the native Custom Element `define` to register the Custom Element with a Custom Element Registry.

From 22c33d599e0778fa4a1771cff313ff1ddc057fdd Mon Sep 17 00:00:00 2001
From: Jane Chu <7559015+janechu@users.noreply.github.com>
Date: Wed, 30 Oct 2024 13:34:32 -0700
Subject: [PATCH 05/13] Update
 packages/web-components/fast-element/ARCHITECTURE.md

Co-authored-by: John Kreitlow <863023+radium-v@users.noreply.github.com>
---
 packages/web-components/fast-element/ARCHITECTURE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/web-components/fast-element/ARCHITECTURE.md b/packages/web-components/fast-element/ARCHITECTURE.md
index b67d17334cd..17482cccbf3 100644
--- a/packages/web-components/fast-element/ARCHITECTURE.md
+++ b/packages/web-components/fast-element/ARCHITECTURE.md
@@ -7,7 +7,7 @@ This document explains various logical flows for how a `FASTElement` is composed
 `FASTElement` is an extension of `HTMLElement` which makes use of Custom Element APIs native to the browser. It also supplies the following methods:
 
 - The `compose` method combines the Custom Element name, template, style, and other options to create the definition for the Custom Element.
-- The `define` method makes use of the native Custom Element `define` to register the Custom Element with a Custom Element Registry.
+- The `define` method makes use of the native Custom Element [`define()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define) to register the Custom Element with a Custom Element Registry.
 - The `from` method allows the use of Custom Built-Ins so that a user does not need to define a template but can specify a native `HTMLElement` such as `HTMLButtonElement`.
 
 ## Creating a Custom Element from FASTElement

From 561904f8bc35a715821955524e85dcef9ea36845 Mon Sep 17 00:00:00 2001
From: Jane Chu <7559015+janechu@users.noreply.github.com>
Date: Wed, 30 Oct 2024 13:34:43 -0700
Subject: [PATCH 06/13] Update
 packages/web-components/fast-element/ARCHITECTURE.md

Co-authored-by: John Kreitlow <863023+radium-v@users.noreply.github.com>
---
 packages/web-components/fast-element/ARCHITECTURE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/web-components/fast-element/ARCHITECTURE.md b/packages/web-components/fast-element/ARCHITECTURE.md
index 17482cccbf3..9194946e6d7 100644
--- a/packages/web-components/fast-element/ARCHITECTURE.md
+++ b/packages/web-components/fast-element/ARCHITECTURE.md
@@ -8,7 +8,7 @@ This document explains various logical flows for how a `FASTElement` is composed
 
 - The `compose` method combines the Custom Element name, template, style, and other options to create the definition for the Custom Element.
 - The `define` method makes use of the native Custom Element [`define()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define) to register the Custom Element with a Custom Element Registry.
-- The `from` method allows the use of Custom Built-Ins so that a user does not need to define a template but can specify a native `HTMLElement` such as `HTMLButtonElement`.
+- The `from` method allows the use of Customized Built-in elements, which extend from native elements such as `HTMLButtonElement`.
 
 ## Creating a Custom Element from FASTElement
 

From aabb86cd4830ab91fcb9c062bc1e94f9e96f2c0d Mon Sep 17 00:00:00 2001
From: Jane Chu <7559015+janechu@users.noreply.github.com>
Date: Wed, 30 Oct 2024 13:35:06 -0700
Subject: [PATCH 07/13] Update
 packages/web-components/fast-element/ARCHITECTURE.md

Co-authored-by: John Kreitlow <863023+radium-v@users.noreply.github.com>
---
 packages/web-components/fast-element/ARCHITECTURE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/web-components/fast-element/ARCHITECTURE.md b/packages/web-components/fast-element/ARCHITECTURE.md
index 9194946e6d7..4a48560c934 100644
--- a/packages/web-components/fast-element/ARCHITECTURE.md
+++ b/packages/web-components/fast-element/ARCHITECTURE.md
@@ -24,7 +24,7 @@ Let's take a close look at the compose and define steps to see what the FAST arc
 
 ## Composing a Custom Element
 
-Using `FASTElement.compose` this creates a new `FASTElementDefinition` which includes all metadata needed for the element such as templates, attributes, styles, etc. this then registers the element with the global FAST for re-use and returns the `FASTElementDefinition` which can be referenced by `ElementController.definition`.
+The `FASTElement.compose()` function creates a new `FASTElementDefinition`, which includes all metadata needed for the element (such as templates, attributes, and styles). The element definition is registered with the global `FAST` for re-use, and the `FASTElementDefinition` is returned. The resulting object can be retrieved via `ElementController.definition`.
 
 ## A Custom Element in JavaScript sent to the Browser
 

From 48cf2822a6c4d0e10de5047a0a8e95f2a50197c9 Mon Sep 17 00:00:00 2001
From: Jane Chu <7559015+janechu@users.noreply.github.com>
Date: Wed, 30 Oct 2024 13:40:01 -0700
Subject: [PATCH 08/13] Indent the creation of a custom element and composition
 with the initial explaination of FASTElement

---
 packages/web-components/fast-element/ARCHITECTURE.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/web-components/fast-element/ARCHITECTURE.md b/packages/web-components/fast-element/ARCHITECTURE.md
index 4a48560c934..7a8dbc32e78 100644
--- a/packages/web-components/fast-element/ARCHITECTURE.md
+++ b/packages/web-components/fast-element/ARCHITECTURE.md
@@ -10,7 +10,7 @@ This document explains various logical flows for how a `FASTElement` is composed
 - The `define` method makes use of the native Custom Element [`define()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define) to register the Custom Element with a Custom Element Registry.
 - The `from` method allows the use of Customized Built-in elements, which extend from native elements such as `HTMLButtonElement`.
 
-## Creating a Custom Element from FASTElement
+### Creating a Custom Element from FASTElement
 
 A basic developer flow for defining a custom element looks like this:
 
@@ -22,7 +22,7 @@ flowchart TD
 
 Let's take a close look at the compose and define steps to see what the FAST architecture is doing.
 
-## Composing a Custom Element
+### Composing a Custom Element
 
 The `FASTElement.compose()` function creates a new `FASTElementDefinition`, which includes all metadata needed for the element (such as templates, attributes, and styles). The element definition is registered with the global `FAST` for re-use, and the `FASTElementDefinition` is returned. The resulting object can be retrieved via `ElementController.definition`.
 

From 5e4fdcb55c3f1c4a19e6a02f6966b592f610bb8a Mon Sep 17 00:00:00 2001
From: Jane Chu <7559015+janechu@users.noreply.github.com>
Date: Wed, 30 Oct 2024 13:46:52 -0700
Subject: [PATCH 09/13] Cleaned up some wording

---
 packages/web-components/fast-element/ARCHITECTURE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/web-components/fast-element/ARCHITECTURE.md b/packages/web-components/fast-element/ARCHITECTURE.md
index 7a8dbc32e78..e10d88494c0 100644
--- a/packages/web-components/fast-element/ARCHITECTURE.md
+++ b/packages/web-components/fast-element/ARCHITECTURE.md
@@ -20,7 +20,7 @@ flowchart TD
     F[Compose with <code>FASTElement.compose</code> to include template and styles] --> G[Define the component in the browser with <code>FASTElement.define</code>]
 ```
 
-Let's take a close look at the compose and define steps to see what the FAST architecture is doing.
+Let's take a look at the compose step to see what the FAST architecture is doing at this stage.
 
 ### Composing a Custom Element
 

From 61ba57a45f354ed7cff2534b7d37693927a861de Mon Sep 17 00:00:00 2001
From: Jane Chu <7559015+janechu@users.noreply.github.com>
Date: Wed, 30 Oct 2024 13:47:45 -0700
Subject: [PATCH 10/13] Update
 packages/web-components/fast-element/ARCHITECTURE.md

Co-authored-by: John Kreitlow <863023+radium-v@users.noreply.github.com>
---
 packages/web-components/fast-element/ARCHITECTURE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/web-components/fast-element/ARCHITECTURE.md b/packages/web-components/fast-element/ARCHITECTURE.md
index e10d88494c0..4301e68d720 100644
--- a/packages/web-components/fast-element/ARCHITECTURE.md
+++ b/packages/web-components/fast-element/ARCHITECTURE.md
@@ -44,7 +44,7 @@ flowchart TD
 
 ### Pre-render Template
 
-The `html` tag template is typically used to create a `ViewTemplate` using the `ViewTemplate.create` method. This is executed and passed during the `compose` step and before `FASTElement` is instantiated.
+The `html` tagged template function creates a `ViewTemplate` object via the `ViewTemplate.create()` method. This is then used during the `compose` step, before `FASTElement` is instantiated.
 
 During the `ViewTemplate.create` step, the following happens for each string:
 - Factories with unique IDs are created for each tag template literal argument (or `TemplateValue`) which matches with the corresponding string

From 5a287284ecd6bc7a3cb748d0208c68e928c981f0 Mon Sep 17 00:00:00 2001
From: Jane Chu <7559015+janechu@users.noreply.github.com>
Date: Wed, 30 Oct 2024 13:48:33 -0700
Subject: [PATCH 11/13] Update
 packages/web-components/fast-element/ARCHITECTURE.md

Co-authored-by: John Kreitlow <863023+radium-v@users.noreply.github.com>
---
 packages/web-components/fast-element/ARCHITECTURE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/web-components/fast-element/ARCHITECTURE.md b/packages/web-components/fast-element/ARCHITECTURE.md
index 4301e68d720..b0fea7c11fc 100644
--- a/packages/web-components/fast-element/ARCHITECTURE.md
+++ b/packages/web-components/fast-element/ARCHITECTURE.md
@@ -54,7 +54,7 @@ A resulting string using `createHTML` function is created using the `HTMLDirecti
 
 #### HTML Binding Directives
 
-The `HTMLBindingDirective` applies bindings to items identified as various `TemplateValue` within the `html` tag template. The `createHTML` step uses the factory associated with the binding to create strings in the markup using the factory's ID.
+The `HTMLBindingDirective` applies bindings to items identified as various `TemplateValue`s within the `html` tagged template. The `createHTML` step uses the factory associated with the binding to create strings in the markup using the factory's ID.
 
 ```mermaid
 flowchart TD

From 47d5caf8d8a04f522d4c97e03191f2bce3696dca Mon Sep 17 00:00:00 2001
From: Jane Chu <7559015+janechu@users.noreply.github.com>
Date: Wed, 30 Oct 2024 14:31:22 -0700
Subject: [PATCH 12/13] Clear up some language

---
 packages/web-components/fast-element/ARCHITECTURE.md | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/packages/web-components/fast-element/ARCHITECTURE.md b/packages/web-components/fast-element/ARCHITECTURE.md
index b0fea7c11fc..3b98cfc19af 100644
--- a/packages/web-components/fast-element/ARCHITECTURE.md
+++ b/packages/web-components/fast-element/ARCHITECTURE.md
@@ -46,11 +46,13 @@ flowchart TD
 
 The `html` tagged template function creates a `ViewTemplate` object via the `ViewTemplate.create()` method. This is then used during the `compose` step, before `FASTElement` is instantiated.
 
-During the `ViewTemplate.create` step, the following happens for each string:
+During the `Compiler.compile()` method triggered by `ViewTemplate.create()` method, the following happens for each string:
 - Factories with unique IDs are created for each tag template literal argument (or `TemplateValue`) which matches with the corresponding string
 - A binding is created from the `TemplateValue`
 
-A resulting string using `createHTML` function is created using the `HTMLDirective`, the previous string from the `html` tag template which determines the aspect if one exists, these aspects are the `@`, `:`, or other binding aspect attached to attributes. The `createHTML` returns a `Markup` attribute using the factory that has a unique ID. This is all concatenated as a string and passed to a new `ViewTemplate` with all the factories (empty until one is assigned) that act as a dictionary with the unique IDs as the key to look up each factory once it has been created.
+A resulting string using a `createHTML()` function is produced using the `HTMLDirective`s executed for each factory. The behavior is augmented by the previous string from the `html` tag template which determines the aspect if one exists, these aspects are the `@`, `:`, or other binding aspect attached to attributes.
+
+The `createHTML()` function utilizes a `Markup` attribute which is assigned to a factory's unique ID. The strings are concatenated and passed to a new `ViewTemplate` with all the factories (empty until one is assigned) that act as a dictionary with the unique IDs as the key to look up each factory once it has been created. The string this creates is injected into a `<template>` as `innerHTML`, which allows the browser to create the nodes and placeholder factory IDs, with the only `DOM` node that is explicitly created being the wrapping `<template>` element.
 
 #### HTML Binding Directives
 
@@ -61,7 +63,7 @@ flowchart TD
     A[A <code>new HTMLBindingDirective</code> is created with a data binding which has a policy, options, <code>createObserver</code>, and an evaluate method assigned to the passed arrow function such as <pre>x => x.foo</pre>]
     B[<code>oneTime</code> binding passes the corresponding tag template argument, an arrow function]
     C[<code>oneWay</code> binding passes a copy of the corresponding tag template argument, an arrow function]
-    D[An already specified binding such as a repeat or when directive is passed]
+    D[An already specified binding such as a <code>repeat</code> or <code>when</code> directive is passed]
     A --> B
     A --> C
     A --> D
@@ -109,7 +111,7 @@ flowchart TD
 
 The rendering of the template on the `ElementController` is by the `renderTemplate` method which is called during the `ElementController.connect` method which is triggered by `HTMLElement`s `connectedCallback` lifecycle.
 
-The `renderTemplate` identifies the Custom Element, and the shadow root associated with the Custom Element. This then places a rendering of the template (an `ElementView`) onto the internal `view` of the controller. When creating the `ElementView`/`HTMLView` using the `ViewTemplate.render`, the `Compile.compile` identifies a `DocumentFragment` either by using an existing `<template>` tag, or creating one to wrap the contents of the shadow root. A new `CompilationContext` is created and the `compileAttributes` function is called, this results in the replacement of the placeholder attributes initally set-up during the pre-render step with their values if a value has been assigned. The factories with the associated nodes identified are then passed to the context. The view then binds all behaviors to the source element. The `CompilationContext.createView` is executed with the `DocumentFragment` as the root, and returns an `HTMLView`. This `HTMLView` includes an `appendTo` method to attach the fragment to the host element, which it then does. It should be noted that the compiled HTML is a `string`, which when set on the `DocumentFragment` as `innerHTML`, this allows the browser to dictate the creation of HTML nodes.
+The `renderTemplate` identifies the Custom Element, and the shadow root associated with the Custom Element. This then places a rendering of the template (an `ElementView`) onto the internal `view` of the controller. When creating the `ElementView`/`HTMLView` using the `ViewTemplate.render`, the `Compile.compile()` method identifies a `DocumentFragment` either by using an existing `<template>` tag, or creating one to wrap the contents of the shadow root. A new `CompilationContext` is created and the `compileAttributes` function is called, this results in the replacement of the placeholder attributes initally set-up during the pre-render step with their values if a value has been assigned. The factories with the associated nodes identified are then passed to the context. The view then binds all behaviors to the source element. The `CompilationContext.createView` is executed with the `DocumentFragment` as the root, and returns an `HTMLView`. This `HTMLView` includes an `appendTo` method to attach the fragment to the host element, which it then does. It should be noted that the compiled HTML is a `string`, which when set on the `DocumentFragment` as `innerHTML`, this allows the browser to dictate the creation of HTML nodes.
 
 ### 🔄 **Lifecycle**: Component is disconnected
 

From e8e69ad6724c3749166accb713679b63f56e16de Mon Sep 17 00:00:00 2001
From: Jane Chu <7559015+janechu@users.noreply.github.com>
Date: Wed, 27 Nov 2024 15:13:51 -0800
Subject: [PATCH 13/13] Split architecture doc into multiple explainers

---
 .../fast-element/ARCHITECTURE.md              | 136 ------------------
 .../fast-element/ARCHITECTURE_FASTELEMENT.md  |  63 ++++++++
 ...CHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md |  34 +++++
 .../fast-element/ARCHITECTURE_INTRO.md        |  10 ++
 .../fast-element/ARCHITECTURE_OVERVIEW.md     |  52 +++++++
 .../fast-element/ARCHITECTURE_UPDATES.md      |  11 ++
 6 files changed, 170 insertions(+), 136 deletions(-)
 delete mode 100644 packages/web-components/fast-element/ARCHITECTURE.md
 create mode 100644 packages/web-components/fast-element/ARCHITECTURE_FASTELEMENT.md
 create mode 100644 packages/web-components/fast-element/ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md
 create mode 100644 packages/web-components/fast-element/ARCHITECTURE_INTRO.md
 create mode 100644 packages/web-components/fast-element/ARCHITECTURE_OVERVIEW.md
 create mode 100644 packages/web-components/fast-element/ARCHITECTURE_UPDATES.md

diff --git a/packages/web-components/fast-element/ARCHITECTURE.md b/packages/web-components/fast-element/ARCHITECTURE.md
deleted file mode 100644
index 3b98cfc19af..00000000000
--- a/packages/web-components/fast-element/ARCHITECTURE.md
+++ /dev/null
@@ -1,136 +0,0 @@
-# Architecture
-
-This document explains various logical flows for how a `FASTElement` is composed, defined, rendered, and updated.
-
-## What is FASTElement?
-
-`FASTElement` is an extension of `HTMLElement` which makes use of Custom Element APIs native to the browser. It also supplies the following methods:
-
-- The `compose` method combines the Custom Element name, template, style, and other options to create the definition for the Custom Element.
-- The `define` method makes use of the native Custom Element [`define()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define) to register the Custom Element with a Custom Element Registry.
-- The `from` method allows the use of Customized Built-in elements, which extend from native elements such as `HTMLButtonElement`.
-
-### Creating a Custom Element from FASTElement
-
-A basic developer flow for defining a custom element looks like this:
-
-```mermaid
-flowchart TD
-    A[Create a <code>FASTElement</code> web component by extending the <code>FASTElement</code> class] --> F
-    F[Compose with <code>FASTElement.compose</code> to include template and styles] --> G[Define the component in the browser with <code>FASTElement.define</code>]
-```
-
-Let's take a look at the compose step to see what the FAST architecture is doing at this stage.
-
-### Composing a Custom Element
-
-The `FASTElement.compose()` function creates a new `FASTElementDefinition`, which includes all metadata needed for the element (such as templates, attributes, and styles). The element definition is registered with the global `FAST` for re-use, and the `FASTElementDefinition` is returned. The resulting object can be retrieved via `ElementController.definition`.
-
-## A Custom Element in JavaScript sent to the Browser
-
-Let's step back from defining the Custom Element and consider what is happening when we import from the `@microsoft/fast-element` package.
-
-First, a global `FAST` property will be created if one does not already exist, typically in browser on the `window`.
-
-Additionally, when Custom Elements are included in a script a few things might happen even before a Custom Element gets detected by the browser. First, there are initial side effects caused by the use of decorators. These include the `attr` and `observable` decorators made available by the `@microsoft/fast-element` package.
-
-```mermaid
-flowchart TD
-    A[The browser loads the JavaScript file containing FAST]
-    A --> B[The FAST global is added]
-    B --> C[Any defined observable decorators are added to the FAST global]
-    A --> D[Any defined attribute decorators are attached to the constructor of the FAST Custom Element]
-```
-
-### Pre-render Template
-
-The `html` tagged template function creates a `ViewTemplate` object via the `ViewTemplate.create()` method. This is then used during the `compose` step, before `FASTElement` is instantiated.
-
-During the `Compiler.compile()` method triggered by `ViewTemplate.create()` method, the following happens for each string:
-- Factories with unique IDs are created for each tag template literal argument (or `TemplateValue`) which matches with the corresponding string
-- A binding is created from the `TemplateValue`
-
-A resulting string using a `createHTML()` function is produced using the `HTMLDirective`s executed for each factory. The behavior is augmented by the previous string from the `html` tag template which determines the aspect if one exists, these aspects are the `@`, `:`, or other binding aspect attached to attributes.
-
-The `createHTML()` function utilizes a `Markup` attribute which is assigned to a factory's unique ID. The strings are concatenated and passed to a new `ViewTemplate` with all the factories (empty until one is assigned) that act as a dictionary with the unique IDs as the key to look up each factory once it has been created. The string this creates is injected into a `<template>` as `innerHTML`, which allows the browser to create the nodes and placeholder factory IDs, with the only `DOM` node that is explicitly created being the wrapping `<template>` element.
-
-#### HTML Binding Directives
-
-The `HTMLBindingDirective` applies bindings to items identified as various `TemplateValue`s within the `html` tagged template. The `createHTML` step uses the factory associated with the binding to create strings in the markup using the factory's ID.
-
-```mermaid
-flowchart TD
-    A[A <code>new HTMLBindingDirective</code> is created with a data binding which has a policy, options, <code>createObserver</code>, and an evaluate method assigned to the passed arrow function such as <pre>x => x.foo</pre>]
-    B[<code>oneTime</code> binding passes the corresponding tag template argument, an arrow function]
-    C[<code>oneWay</code> binding passes a copy of the corresponding tag template argument, an arrow function]
-    D[An already specified binding such as a <code>repeat</code> or <code>when</code> directive is passed]
-    A --> B
-    A --> C
-    A --> D
-    E[When a <code>createObserver</code> is called, an <code>Observable.binding</code> is created passing the arrow function to be evaluated and the subscriber to be notified]
-    C --> E
-    F[When a <code>createObserver</code> is called, the instance of the one time binding is returned which includes a bind method returning the arrow function executed against the controller source and context]
-    B --> F
-```
-
-## A Custom Element is Detected by the Browser
-
-Because the `FASTElement` is an extension of the `HTMLElement`, it makes use of the same lifecycle hooks and extends them with `$fastController`. It also initializes using another class `ElementController`, the methods this are called during the custom elements native `constructor`, `connectedCallback`, `disconnectedCallback`, and `attributeChangedCallback` lifecycle hooks.
-
-### 🔄 **Lifecycle**: Initialization
-
-```mermaid
-flowchart TD
-    A[A <code>FASTElement</code> web component is added to the <code>DOM</code>] --> B
-    B[<code>FASTElement</code> initializes the <code>ElementController.forCustomElement</code> passing the Custom Element instance] --> C
-    B --> F[Observables applied to the <code>FASTElement</code> are updated on the FAST global without values]
-    C{Is an <code>ElementController</code> available?}
-    C --> |yes|E
-    C --> |no|D
-    D[Initialize a new <code>ElementController</code> referred to as setting an element controller strategy]
-    D --> F
-    E[<code>ElementController</code> captures the Custom Element instance and the definition and attaches them to the <code>$fastController</code> which is then attached to the instance]
-```
-
-### 🔄 **Lifecycle**: Component is connected
-
-```mermaid
-flowchart TD
-    A[browser <code>HTMLElement</code>'s <code>connectedCallback</code> is called] --> B
-    B[<code>this.$fastController.connect</code> in FASTElement is called] --> C
-    B --> D
-    B --> E
-    B --> F
-    C[bind observables by capturing the Custom Elements properties and setting the values from the bound observables on the Custom Element]
-    D[connect behaviors by call the <code>connectedCallback</code> on all behaviors]
-    E[render template, execute an <code>ElementViewTemplate</code>'s render method]
-    F[add styles either as an appended <code>StyleElement</code> node or an <code>adoptedStylesheet</code> which may include and attach behaviors]
-```
-
-#### Render Template
-
-The rendering of the template on the `ElementController` is by the `renderTemplate` method which is called during the `ElementController.connect` method which is triggered by `HTMLElement`s `connectedCallback` lifecycle.
-
-The `renderTemplate` identifies the Custom Element, and the shadow root associated with the Custom Element. This then places a rendering of the template (an `ElementView`) onto the internal `view` of the controller. When creating the `ElementView`/`HTMLView` using the `ViewTemplate.render`, the `Compile.compile()` method identifies a `DocumentFragment` either by using an existing `<template>` tag, or creating one to wrap the contents of the shadow root. A new `CompilationContext` is created and the `compileAttributes` function is called, this results in the replacement of the placeholder attributes initally set-up during the pre-render step with their values if a value has been assigned. The factories with the associated nodes identified are then passed to the context. The view then binds all behaviors to the source element. The `CompilationContext.createView` is executed with the `DocumentFragment` as the root, and returns an `HTMLView`. This `HTMLView` includes an `appendTo` method to attach the fragment to the host element, which it then does. It should be noted that the compiled HTML is a `string`, which when set on the `DocumentFragment` as `innerHTML`, this allows the browser to dictate the creation of HTML nodes.
-
-### 🔄 **Lifecycle**: Component is disconnected
-
-When a component is disconnected, a cleanup step is created to remove associated behaviors.
-
-### 🔄 **Lifecycle**: Attribute has been changed
-
-Attributes have an `AttributeDefinition` which allows for converters, attachment of the `<attributName>Changed` aspect of the `@attr` decorator among other capabilities.
-
-```mermaid
-flowchart TD
-    A[The browser <code>HTMLElement</code>'s <code>attributeChangedCallback</code> is called] --> B
-    B[<code>this.$fastController.onAttributeChangedCallback</code> in <code>FASTElement</code> is called] --> C
-    C[calls the attribute definitions <code>onAttributeChangedCallback</code> method with the updated value] --> D
-    D[An <code>Updates.enqueue</code> is called which places the update in the task queue which is then executed, these are performed async unless otherwise specified]
-```
-
-These changes are observed and similar to the way `Observables` work, they utilize an `Accessor` pattern which has a `getValue` and `setValue` in which DOM updates are applied.
-
-### Observables are updated
-
-The `Reflect` API is used to override `defineProperty` in order to observe a property on an Custom Element, this overrides the getter and setter, which allows subscribers to be notified of changes. Any changes which `set` the value are passed to the `Updates` queue which has been added to the FAST Global.
\ No newline at end of file
diff --git a/packages/web-components/fast-element/ARCHITECTURE_FASTELEMENT.md b/packages/web-components/fast-element/ARCHITECTURE_FASTELEMENT.md
new file mode 100644
index 00000000000..e227474a2bf
--- /dev/null
+++ b/packages/web-components/fast-element/ARCHITECTURE_FASTELEMENT.md
@@ -0,0 +1,63 @@
+# FASTElement
+
+The `FASTElement` is our extension of the `HTMLElement`. As such it leverages the lifecycles but also requires additional setup before before the class `constructor` or the `connectedCallback` method is executed which are explained in the [overview](./ARCHITECTURE_OVERVIEW.md). This document explains specifically what `FASTElement` leverages inside the `HTMLElement`s lifecycle hooks.
+
+For an explanation into `HTMLElement` lifecycle hooks refer to the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks).
+
+## A Custom Element is Detected by the Browser
+
+Because the `FASTElement` is an extension of the `HTMLElement`, it makes use of the same lifecycle hooks and extends them with `$fastController`. It also initializes using another class `ElementController`, the methods this are called during the custom elements native `constructor`, `connectedCallback`, `disconnectedCallback`, and `attributeChangedCallback` lifecycle hooks.
+
+### 🔄 **Lifecycle**: Initialization
+
+```mermaid
+flowchart TD
+    A[A <code>FASTElement</code> web component is added to the <code>DOM</code>] --> B
+    B[<code>FASTElement</code> initializes the <code>ElementController.forCustomElement</code> passing the Custom Element instance] --> C
+    B --> F[Observables applied to the <code>FASTElement</code> are updated on the FAST global without values]
+    C{Is an <code>ElementController</code> available?}
+    C --> |yes|E
+    C --> |no|D
+    D[Initialize a new <code>ElementController</code> referred to as setting an element controller strategy]
+    D --> F
+    E[<code>ElementController</code> captures the Custom Element instance and the definition and attaches them to the <code>$fastController</code> which is then attached to the instance]
+```
+
+### 🔄 **Lifecycle**: Component is connected
+
+```mermaid
+flowchart TD
+    A[browser <code>HTMLElement</code>'s <code>connectedCallback</code> is called] --> B
+    B[<code>this.$fastController.connect</code> in FASTElement is called] --> C
+    B --> D
+    B --> E
+    B --> F
+    C[bind observables by capturing the Custom Elements properties and setting the values from the bound observables on the Custom Element]
+    D[connect behaviors by call the <code>connectedCallback</code> on all behaviors]
+    E[render template, execute an <code>ElementViewTemplate</code>'s render method]
+    F[add styles either as an appended <code>StyleElement</code> node or an <code>adoptedStylesheet</code> which may include and attach behaviors]
+```
+
+#### Render Template
+
+The rendering of the template on the `ElementController` is by the `renderTemplate` method which is called during the `ElementController.connect` method which is triggered by `HTMLElement`s `connectedCallback` lifecycle.
+
+The `renderTemplate` identifies the Custom Element, and the shadow root associated with the Custom Element. This then places a rendering of the template (an `ElementView`) onto the internal `view` of the controller. When creating the `ElementView`/`HTMLView` using the `ViewTemplate.render`, the `Compile.compile()` method identifies a `DocumentFragment` either by using an existing `<template>` tag, or creating one to wrap the contents of the shadow root. A new `CompilationContext` is created and the `compileAttributes` function is called, this results in the replacement of the placeholder attributes initally set-up during the pre-render step with their values if a value has been assigned. The factories with the associated nodes identified are then passed to the context. The view then binds all behaviors to the source element. The `CompilationContext.createView` is executed with the `DocumentFragment` as the root, and returns an `HTMLView`. This `HTMLView` includes an `appendTo` method to attach the fragment to the host element, which it then does. It should be noted that the compiled HTML is a `string`, which when set on the `DocumentFragment` as `innerHTML`, this allows the browser to dictate the creation of HTML nodes.
+
+### 🔄 **Lifecycle**: Component is disconnected
+
+When a component is disconnected, a cleanup step is created to remove associated behaviors.
+
+### 🔄 **Lifecycle**: Attribute has been changed
+
+Attributes have an `AttributeDefinition` which allows for converters, attachment of the `<attributName>Changed` aspect of the `@attr` decorator among other capabilities.
+
+```mermaid
+flowchart TD
+    A[The browser <code>HTMLElement</code>'s <code>attributeChangedCallback</code> is called] --> B
+    B[<code>this.$fastController.onAttributeChangedCallback</code> in <code>FASTElement</code> is called] --> C
+    C[calls the attribute definitions <code>onAttributeChangedCallback</code> method with the updated value] --> D
+    D[An <code>Updates.enqueue</code> is called which places the update in the task queue which is then executed, these are performed async unless otherwise specified]
+```
+
+These changes are observed and similar to the way `Observables` work, they utilize an `Accessor` pattern which has a `getValue` and `setValue` in which DOM updates are applied.
\ No newline at end of file
diff --git a/packages/web-components/fast-element/ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md b/packages/web-components/fast-element/ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md
new file mode 100644
index 00000000000..8c9c447b5a9
--- /dev/null
+++ b/packages/web-components/fast-element/ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md
@@ -0,0 +1,34 @@
+# `html` tagged template literal
+
+The `html` export from `@microsoft/fast-element` is used to create the template logic for the custom element.
+
+## Pre-processing the `html` tagged template literal contents
+
+Before the template can be used it goes through a step to convert it into a `ViewTemplate` which it does via the `ViewTemplate.create()` method. This is then used during the `compose` step, before `FASTElement` is instantiated.
+
+During the `Compiler.compile()` method(triggered by `ViewTemplate.create()` method), the following happens for each string:
+- Factories with unique IDs are created for each tag template literal argument (or `TemplateValue`) which matches with the corresponding string
+- A binding is created from the `TemplateValue`
+
+A resulting string using a `createHTML()` function is produced using the `HTMLDirective`s executed for each factory. The behavior is augmented by the previous string from the `html` tag template which determines the aspect if one exists, these aspects are the `@`, `:`, or other binding aspect attached to attributes.
+
+The `createHTML()` function utilizes a `Markup` attribute which is assigned to a factory's unique ID. The strings are concatenated and passed to a new `ViewTemplate` with all the factories (empty until one is assigned) that act as a dictionary with the unique IDs as the key to look up each factory once it has been created. The string this creates is injected into a `<template>` as `innerHTML`, which allows the browser to create the nodes and placeholder factory IDs, with the only `DOM` node that is explicitly created being the wrapping `<template>` element.
+
+## Directives
+
+The `HTMLBindingDirective` applies bindings to items identified as various `TemplateValue`s within the `html` tagged template. The `createHTML` step uses the factory associated with the binding to create strings in the markup using the factory's ID.
+
+```mermaid
+flowchart TD
+    A[A <code>new HTMLBindingDirective</code> is created with a data binding which has a policy, options, <code>createObserver</code>, and an evaluate method assigned to the passed arrow function such as <pre>x => x.foo</pre>]
+    B[<code>oneTime</code> binding passes the corresponding tag template argument, an arrow function]
+    C[<code>oneWay</code> binding passes a copy of the corresponding tag template argument, an arrow function]
+    D[An already specified binding such as a <code>repeat</code> or <code>when</code> directive is passed]
+    A --> B
+    A --> C
+    A --> D
+    E[When a <code>createObserver</code> is called, an <code>Observable.binding</code> is created passing the arrow function to be evaluated and the subscriber to be notified]
+    C --> E
+    F[When a <code>createObserver</code> is called, the instance of the one time binding is returned which includes a bind method returning the arrow function executed against the controller source and context]
+    B --> F
+```
\ No newline at end of file
diff --git a/packages/web-components/fast-element/ARCHITECTURE_INTRO.md b/packages/web-components/fast-element/ARCHITECTURE_INTRO.md
new file mode 100644
index 00000000000..b260a28ef46
--- /dev/null
+++ b/packages/web-components/fast-element/ARCHITECTURE_INTRO.md
@@ -0,0 +1,10 @@
+# Introduction
+
+This document (and the linked documents) explains how the exports and side effects of `@microsoft/fast-element` are used to create custom elements.
+
+## Glossary
+
+- [Overview](./ARCHITECTURE_OVERVIEW.md): How the `@microsoft/fast-element` should be used by a developer and what code is executed during the first render.
+- [`FASTElement`](./ARCHITECTURE_FASTELEMENT.md): How the `FASTElement` is architected.
+- [`html` tagged template literal](./ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md): How the `html` tagged template literal takes and converts the contents into a `VIEWTemplate`.
+- [`Updates` queue](./ARCHITECTURE_UPDATES.md): How updates to attributes and observables are processed.
\ No newline at end of file
diff --git a/packages/web-components/fast-element/ARCHITECTURE_OVERVIEW.md b/packages/web-components/fast-element/ARCHITECTURE_OVERVIEW.md
new file mode 100644
index 00000000000..68e609acbd8
--- /dev/null
+++ b/packages/web-components/fast-element/ARCHITECTURE_OVERVIEW.md
@@ -0,0 +1,52 @@
+# General FAST usage
+
+`FASTElement` is an extension of `HTMLElement` which makes use of Custom Element APIs native to the browser. It also supplies the following methods:
+
+- The `compose` method combines the Custom Element name, template, style, and other options to create the definition for the Custom Element.
+- The `define` method makes use of the native Custom Element [`define()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define) to register the Custom Element with a Custom Element Registry.
+- The `from` method allows the use of Customized Built-in elements, which extend from native elements such as `HTMLButtonElement`.
+
+### Creating a Custom Element from FASTElement
+
+A basic developer flow for defining a custom element looks like this:
+
+```mermaid
+flowchart TD
+    A[Create a <code>FASTElement</code> web component by extending the <code>FASTElement</code> class] --> F
+    F[Compose with <code>FASTElement.compose</code> to include template and styles] --> G[Define the component in the browser with <code>FASTElement.define</code>]
+```
+
+Let's take a look at the compose step to see what the FAST architecture is doing at this stage.
+
+### Composing a Custom Element
+
+The `FASTElement.compose()` function creates a new `FASTElementDefinition`, which includes all metadata needed for the element (such as templates, attributes, and styles). The element definition is registered with the global `FAST` for re-use, and the `FASTElementDefinition` is returned. The resulting object can be retrieved via `ElementController.definition`.
+
+## A Custom Element in JavaScript is sent to the Browser
+
+Let's step back from defining the Custom Element and consider what is happening when we import from the `@microsoft/fast-element` package.
+
+First, a global `FAST` property will be created if one does not already exist, typically in browser on the `window`.
+
+Additionally, when Custom Elements are included in a script a few things might happen even before a Custom Element gets detected by the browser. First, there are initial side effects caused by the use of decorators. These include the `attr` and `observable` decorators made available by the `@microsoft/fast-element` package.
+
+Here is a basic flow of what code is executed and when during initial load of a script that contains a FAST defined Custom Element:
+
+```mermaid
+flowchart TD
+    A@{ shape: circle, label: "The browser loads the JavaScript file containing FAST and FAST Custom Element definitions" }
+    B@{ shape: rect, label: "The FAST global is added to the window" }
+    A --> B
+    C@{ shape: rect, label: "A Custom Element executes the <code>compose</code> step"}
+    B --> C
+    D@{ shape: procs, label: "<ul style="text-align: left"><li>Any defined observable decorators are added to the FAST global</li><li>An attribute decorator locates the associated Custom Elements constructor which it uses to push itself to the Custom Elements attribute collection</li></ul>"}
+    C --> D
+    F@{ shape: rect, label: "An HTML tagged template literal is executed for the FAST Custom Element and applied to the definition" }
+    D --> F
+    G@{ shape: rect, label: "The <code>define</code> step is hit and the <code>customElement</code> is registered with the Custom Element Registry" }
+    F --> G
+    H@{ shape: rect, label: "A Custom Element is detected on the page and the browser initializes it" }
+    I@{ shape: dbl-circ, label: "The lifecycle steps for <code>FASTElement</code> are executed" }
+    G --> H
+    H --> I
+```
\ No newline at end of file
diff --git a/packages/web-components/fast-element/ARCHITECTURE_UPDATES.md b/packages/web-components/fast-element/ARCHITECTURE_UPDATES.md
new file mode 100644
index 00000000000..6d2502d3d18
--- /dev/null
+++ b/packages/web-components/fast-element/ARCHITECTURE_UPDATES.md
@@ -0,0 +1,11 @@
+# `Updates`
+
+The `Updates` API is part of the `FAST` global. The updates that are queued include updates to attributes, observables, and observed arrays.
+
+## Attributes
+
+An attribute change may be queued when the value of the attribute is updated. This change is triggered by `HTMLElement` lifecycle hook `attributeChangedCallback`. The `Updates` queue is used to try to reflect the attribute with the updated value onto the element using `DOM` APIs.
+
+## Observables
+
+The `Reflect` API is used to override `defineProperty` in order to observe a property on an Custom Element, this overrides the getter and setter, which allows subscribers to be notified of changes. Any changes which `set` the value are passed to the `Updates` queue.
\ No newline at end of file