insightsengineering · donyunardi · Oct 12, 2023 · Sep 21, 2023 · Sep 21, 2023 · Sep 22, 2023
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# `teal`: Interactive Exploratory Data Analysis with Shiny Web-Applications <a href='https://insightsengineering.github.io/teal/'><img src="man/figures/teal.png" align="right" height="139" style="max-width: 100%;"/></a  >
+# `teal`: Interactive Exploratory Data Analysis with Shiny Web-Applications <a href='https://insightsengineering.github.io/teal/'><img src="man/figures/teal.png" align="right" height="139" style="max-width: 100%; max-height: 139px;"/></a  >
 
 <!-- start badges -->
 [![Check 🛠](https://github.com/insightsengineering/teal/actions/workflows/check.yaml/badge.svg)](https://insightsengineering.github.io/teal/main/unit-test-report/)

diff --git a/_pkgdown.yml b/_pkgdown.yml
@@ -6,7 +6,7 @@ template:
 
 navbar:
   structure:
-    left: [intro, reference, articles, tutorials, news, reports]
+    left: [intro, reference, articles, blueprint, tutorials, news, reports]
     right: [search, github]
   components:
     reports:
@@ -16,33 +16,77 @@ navbar:
           href: coverage-report/
         - text: Unit test report
           href: unit-test-report/
+    blueprint:
+      text: Technical Blueprint
+      menu:
+        - text: About Blueprint
+          href: articles/blueprint/index.html
+        - text: Introduction
+          href: articles/blueprint/intro.html
+        - text: Actors
+          href: articles/blueprint/actors.html
+        - text: Data Flow
+          href: articles/blueprint/dataflow.html
+        - text: Product Map
+          href: articles/blueprint/products_map.html
+        - text: Features
+          navbar: Features
+        - text: "`qenv`"
+          href: articles/blueprint/qenv.html
+        - text: Filter Panel
+          href: articles/blueprint/filter_panel.html
+        - text: Delayed Data Loading (DDL)
+          href: articles/blueprint/ddl.html
+        - text: Module and Encapsulation
+          href: articles/blueprint/module_encapsulation.html
+
     github:
       icon: fa-github
       href: https://github.com/insightsengineering/teal
 
 articles:
-  - title: Get Started
-    navbar: ~
-    contents:
-      - teal
-  - title: Articles
-    navbar: Using teal
-    contents:
-      - filter-panel
-      - teal-options
-      - teal-bs-themes
-  - title: Articles
-    navbar: Data in teal Apps
-    contents:
-      - including-adam-data-in-teal
-      - including-general-data-in-teal
-      - including-mae-data-in-teal
-      - preprocessing-data
-  - title: Articles
-    navbar: Extending teal
-    contents:
-      - creating-custom-modules
-      - adding-support-for-reporting
+- title: Get Started
+  navbar: ~
+  contents:
+    - teal
+- title: Using teal
+  navbar: Using teal
+  contents:
+    - filter-panel
+    - teal-options
+    - teal-bs-themes
+- title: Data in teal Apps
+  navbar: Data in teal Apps
+  contents:
+    - including-adam-data-in-teal
+    - including-general-data-in-teal
+    - including-mae-data-in-teal
+    - preprocessing-data
+- title: Extending teal
+  navbar: Extending teal
+  contents:
+    - creating-custom-modules
+    - adding-support-for-reporting
+- title: 📃 Technical Blueprint
+  desc: >
+    The purpose of the blueprint is to aid new developer’s comprehension of the
+    fundamental principles of the `teal` framework. We will explore crucial `teal`
+    concepts such as data flow, actors, and filter panel, among others.
+  contents:
+    - blueprint/index
+    - blueprint/intro
+    - blueprint/actors
+    - blueprint/dataflow
+    - blueprint/products_map
+- title: ""
+  desc: >
+    Features
+  contents:
+  - blueprint/qenv
+  - blueprint/filter_panel
+  - blueprint/ddl
+  - blueprint/module_encapsulation
+
 
 reference:
   - title: Core `teal` Functions

diff --git a/inst/WORDLIST b/inst/WORDLIST
@@ -1,20 +1,52 @@
+Acknowledgement
 ADaM
+adam
+analysing
+bs
+CDISC
+cloneable
+customizable
+dataflow
+Dataflow
+ddl
+DDL
+desc
+dropdown
+env
 Forkers
+funder
+Genentech
+github
 Hoffmann
+href
+https
+init
+insightsengineering
+io
+mae
 MultiAssayExperiment
-TLG
-Theming
-UI
-UIs
-UX
-cloneable
-funder
+navbar
+nesttemplate
 omics
 pharmaverse
+pre
+Pre
 preprocessed
 programmatically
+qenv
+rcode
 repo
 reproducibility
+srv
 tabsetted
+tdata
+TealReportCard
 themer
+Theming
+TLG
+transfered
+UI
+ui
+UIs
 uncheck
+UX
diff --git a/man/figures/filterpanel.png b/man/figures/filterpanel.png
diff --git a/man/figures/notification.jpg b/man/figures/notification.jpg
diff --git a/man/figures/reporter.jpg b/man/figures/reporter.jpg
diff --git a/man/figures/showrcode.jpg b/man/figures/showrcode.jpg
diff --git a/man/figures/teal.png b/man/figures/teal.png
diff --git a/vignettes/blueprint/_setup.Rmd b/vignettes/blueprint/_setup.Rmd
@@ -0,0 +1,10 @@
+
+```{css, echo=FALSE}
+pre.mermaid {
+  background: transparent;
+}
+```
+
+```{r, echo=FALSE}
+shiny::tags$script(type = "module", "import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/+esm'")
+```
diff --git a/vignettes/blueprint/actors.Rmd b/vignettes/blueprint/actors.Rmd
@@ -0,0 +1,120 @@
+---
+title: "Actors"
+author: "NEST CoreDev"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Actors}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+There are two main actors in the `teal` development:
+
+* `teal` App Developer
+* `teal` Module Developer
+
+## `teal` App Developer
+
+```{r, child="_setup.Rmd"}
+```
+
+```{r actors_mermaid1, echo=FALSE}
+shiny::pre(
+  class = "mermaid",
+  "
+%% This is a mermaid diagram, if you see this the plot failed to render. Sorry.
+graph LR
+    A[Teal App Developer]--utilizes--> B[teal modules]
+    B--to create--> C[teal app]
+    D[app user]--uses--> C
+style A fill:lightblue
+style C fill:gold
+style D fill:pink
+"
+)
+```
+
+The primary responsibility of a `teal` app developer is to leverage the available building blocks of the `teal` framework to create a functional `teal` app that analyses the data.
+
+To expedite the app creation process, developers can take advantage of pre-existing `teal` modules found in R packages like `teal.modules.general` and `teal.modules.clinical`.
+
+These modules are designed with a focus on standardization and versatility, making them suitable for a wide range of use cases.
+
+When developing a `teal` app, the developer will select the most appropriate `teal` modules and integrate them into the app's interface to ensure seamless usability for end-users.
+
+To learn more about the existing modules, visit [`teal.gallery`](https://insightsengineering.github.io/teal.gallery/) that contains several demo applications and their source code.
+
+## `teal` Module Developer
+
+```{r actors_mermaid2, echo=FALSE}
+shiny::pre(
+  class = "mermaid",
+  "
+%% This is a mermaid diagram, if you see this the plot failed to render. Sorry.
+graph LR
+    A[Teal App Developer]--utilizes--> B[teal modules]
+    E[Teal Module Developer]--develops--> B
+    B--to create--> C[teal app]
+    D[app user]--uses--> C
+style A fill:lightblue
+style E fill:lightgreen
+style D fill:pink
+style C fill:gold
+"
+)
+```
+
+The main duty of a `teal` module developer is to construct a compatible `teal` module that can be utilized within the `teal` framework.
+
+Several factors influence the scope and requirements for building a `teal` module.
+
+When creating a reusable `teal` module, it's advisable to focus on making it as general and adaptable as feasible to maximize the possibilities of being re-used in the future.
+However, developers have the freedom to create a `teal` module that is customized to suit the specific demands of a project.
+
+Ultimately, one or more `teal` modules are employed to construct the `teal` app.
+
+To learn more about creating custom modules follow the [Tutorial on Creating a Custom Module](https://insightsengineering.github.io/teal/latest-tag/articles/creating-custom-modules.html).
+
+## Workflow in a Clinical Trial Study
+
+```{r actors_mermaid3, echo=FALSE}
+shiny::pre(
+  class = "mermaid",
+  "
+%% This is a mermaid diagram, if you see this the plot failed to render. Sorry.
+%%| fig-width: 7.5
+graph LR
+    subgraph Study B
+        A2[Study Teal App Developer]--utilizes--> B2[teal modules]
+        E2[Study Teal Module Developer]-.develops.-> B2
+        B2--to create--> C2[study teal app]
+        D2[study app user]--uses--> C2
+    end
+    E3[Teal Module Developer]--develops--> B
+    E3--develops-->B2
+    subgraph Study A
+        A[Study Teal App Developer]--utilizes--> B[teal modules]
+        E[Study Teal Module Developer]-.develops.-> B
+        B--to create--> C[study teal app]
+        D[study app user]--uses--> C
+    end
+style A fill:lightblue
+style A2 fill:lightblue
+style E fill:limegreen
+style E2 fill:limegreen
+style E3 fill:lightgreen
+style D fill:pink
+style D2 fill:pink
+style C fill:gold
+style C2 fill:gold
+"
+)
+```
+
+In a clinical trial study setting, a unique **study `teal` app developer** is assigned to each study team and is accountable for developing a tailored `teal` app for their respective study.
+
+The **study `teal` app developer** will initially leverage existing `teal` modules from R packages created by **`teal` module developers**.
+
+In cases where there is a need to create new modules tailored to the study, a **study `teal` module developer** will need to be involved.
+
+Upon completion, each study team will have their own designated `teal` app tailored to their specific study.
diff --git a/vignettes/blueprint/dataflow.Rmd b/vignettes/blueprint/dataflow.Rmd
@@ -0,0 +1,43 @@
+---
+title: "Data Flow"
+author: "NEST CoreDev"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Data Flow}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, child="_setup.Rmd"}
+```
+
+```{r dataflow_mermaid1, echo=FALSE}
+shiny::pre(
+  class = "mermaid",
+  "
+%% This is a mermaid diagram, if you see this the plot failed to render. Sorry.
+sequenceDiagram;
+    autonumber
+    participant data
+    participant filters
+    participant filtered data
+    participant teal module
+    data->filters: gets
+    filters->>filtered data: becomes
+    filtered data->>teal module: sent to
+"
+)
+```
+
+The sequence diagram above illustrates the different stages that data goes through within the `teal` framework, supported by the `teal.slice` R package:
+
+1. Users _(or app developers)_ select which filters to apply;
+    - See the [Filter panel vignette](filterpanel.qmd) for details;
+1. The R code is automatically generated from the selected filters;
+    - Creates a [`qenv`](qenv.qmd) R object that contains the code that will be applied to the data _(and used for reproducibility)_;
+1. Apply the filters to the data _(creating a filtered data instance)_;
+    - A module can have a custom set of filters that is only applied to it;
+
+1. The filtered data is sent to the `teal` modules as the main data source for analysis.
+
+Whenever filters are added or removed, these stages are restarted, providing the `teal` module with new filtered data to conduct the required analysis.
diff --git a/vignettes/blueprint/ddl.Rmd b/vignettes/blueprint/ddl.Rmd
@@ -0,0 +1,47 @@
+---
+title: "Delayed Data Loading (DDL)"
+author: "NEST CoreDev"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Delayed Data Loading (DDL)}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+## Introduction
+
+The `teal` framework introduced the Delayed Data Loading mechanism to enhance the user experience while reading and loading data in the app.
+
+## Background
+
+Usually, when running a shiny app, the dataset must be immediately available in the session for processing and reading. However, if the data is stored externally (such as in a database or other data repository), loading the shiny app may be delayed because the data needs to be fetched first.
+If there is additional data processing code, this may further extend the loading process.
+
+To address this, we created the Delayed Data Loading mechanism. Learn how to use it [here](https://insightsengineering.github.io/teal.data/latest-tag/articles/using-delayed-data-basic.html).
+
+## What is Delayed Data Loading?
+
+Delayed Data Loading is an R object managed in `teal.data`, which stores instructions on how to obtain the data, including how to read and process it before it is used in `teal`.
+By adopting this approach, `teal` apps can load more quickly, and the data can be fetched after the app is loaded.
+
+## Splash Screen
+
+`teal` provides a comprehensive solution for managing the delayed data loading mechanism, which includes the incorporation of a splash screen.
+The splash screen serves as a visual cue to the user that data is being loaded and that they should wait for the app to be ready.
+
+Moreover, the splash screen can be modified to query the user for a password or other access credentials needed to fetch the data.
+In cases where the modified splash screen is used, `teal` will display the customized version to prompt the user for the necessary information.
+
+After the data is fetched and loaded, `teal` removes the splash screen and replaces it with the content of the corresponding `teal` modules.
+`teal` also displays a notification indicating that the data has been loaded, and the app has fully started up.
+
+![Notification that the data is loaded and app is ready to use](notification.jpg)
+
+## Additional resources
+
+The vignettes on `teal.data` documentation provide with basic and advanced examples for this feature.
+
+- [Pre-processing Delayed Data](https://insightsengineering.github.io/teal.data/latest-tag/articles/preprocessing-delayed-data.html)
+- [Using Delayed Data Loading (basic)](https://insightsengineering.github.io/teal.data/latest-tag/articles/using-delayed-data-basic.html)
+- [Creating Delayed Data Classes (Advanced)](https://insightsengineering.github.io/teal.data/latest-tag/articles/using-delayed-data-advanced.html)
+- [Testing Delayed Data Loading](https://insightsengineering.github.io/teal.data/latest-tag/articles/testing-delayed-data.html)