Adds Technical Blueprint to pkgdown site (#923)

Fixes insightsengineering/coredev-tasks#467

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/)
@@ -105,7 +105,7 @@ shinyApp(app$ui, app$server)
 
 Please see [`teal.gallery`](https://insightsengineering.github.io/teal.gallery) and [TLG Catalog](https://insightsengineering.github.io/tlg-catalog) to see examples of `teal` apps.
 
-Please start with the ["Getting Started" article](https://insightsengineering.github.io/teal/latest-tag/articles/teal.html) and then other [package vignettes](https://insightsengineering.github.io/teal/articles/index.html) for more detailed guide.
+Please start with the ["Technical Blueprint" article](https://insightsengineering.github.io/teal/latest-tag/articles/blueprint/index.html), ["Getting Started" article](https://insightsengineering.github.io/teal/latest-tag/articles/teal.html), and then other [package vignettes](https://insightsengineering.github.io/teal/latest-tag/articles/index.html) for more detailed guide.
 
 ## Getting help
 

_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

inst/WORDLIST

@@ -1,20 +1,53 @@
+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
+summarization
 tabsetted
+tdata
+TealReportCard
 themer
+Theming
+TLG
+transfered
+UI
+ui
+UIs
 uncheck
+UX

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'")
+```

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 a `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.

vignettes/blueprint/dataflow.Rmd

@@ -0,0 +1,42 @@
+---
+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. Data is loaded into the `teal` app;
+    - See the [Filter panel vignette](filter_panel.html) for details;
+2. Data is passed to the filter panel;
+    - Users _(or app developers)_ can specify filters to apply;
+    - Filters can be specified globally, for the whole app, or for specific modules;
+3. Filtered data is sent to `teal` modules for analysis;
+    - Each module creates a [`qenv`](qenv.html) object track the code that is be applied to the data _(and used for reproducibility)_;
+
+Whenever filters are added or removed, the data coming into modules is re-computed, providing the `teal` module with new filtered data to conduct the required analysis.