docs: improve explanations and visuals

lib/README.md

@@ -6,6 +6,58 @@ To understand terminology, see http://surveilr.com/blog/surveilr-core-vs-pattern
 
 ![lib content access points](./endpoints.drawio.png)
 
+```mermaid
+flowchart LR
+
+%% Combine Industries, Patterns, and Disciplines into single boxes with their instances listed inside
+IndustriesBox["Industries:
+Digital Health, Diabetes Research, IT Asset Management, Cybersecurity, Compliance, Quality Metrics"]
+
+PatternsBox["Patterns:
+Operational Portfolios, Infrastructure Catalogs, IT Asset Management Patterns, Research Data Patterns, Clinical Data Patterns"]
+
+DisciplinesBox["Disciplines:
+Data Scientists, Cybersecurity Experts, Healthcare Professionals, IT Managers, Compliance Officers, QA Managers"]
+
+%% Connect the combined boxes to SQL Inputs
+IndustriesBox --> SQL_Inputs_Group["Custom SQL Code"]
+PatternsBox --> SQL_Inputs_Group
+DisciplinesBox --> SQL_Inputs_Group
+
+%% Group for SQL input types
+subgraph SQL_Inputs["SQL Inputs"]
+    SQLa_Input["SQLa TypeScript-based SQL
+      *.sql.ts"]
+    CapExec_Input["SQL created by 
+    other languages
+      *.sql.py, *.sql.xyz"]
+    Direct_SQL_Input["Direct (static) SQL
+      *.sql"]
+end
+
+SQL_Inputs_Group --> SQL_Inputs["SQL Inputs"]
+
+%% Process SQLa TypeScript SQL via SQL Assembler (Deno)
+SQLa_Input --> SQL_Assembler_Deno["SQL Assembler (Deno)"]
+CapExec_Input --> SQL_Assembler_Other["SQL Assembler
+(Any Language)"]
+SQL_Assembler_Deno --> SQL_Package["SQL Package"]
+SQL_Assembler_Other --> SQL_Package["SQL Package"]
+
+%% Direct SQL bypasses the assembler and goes directly to SQL Package
+Direct_SQL_Input --> SQL_Package["package.sql"]
+
+%% SQL Package flows into Surveilr Binary and RSSD Database
+SQL_Package --> Surveilr_Binary["surveilr shell
+(multi-OS executable)"]
+Surveilr_Binary --> RSSD_DB["RSSD SQLite
+ (single file database)"]
+
+%% Portable output
+RSSD_DB --> Target_System["Integrate anywhere SQLite
+ is available"]
+```
+
 ## `lib` Structure
 
 ```md
@@ -64,4 +116,13 @@ In summary:
 - Using `https://surveilr.com/lib/pattern/fhir-explorer/package.sql.ts` emits
   the **TypeScript _source code_** (for example so it can be `import`ed into Deno).
 - Using `https://surveilr.com/lib/pattern/fhir-explorer/package.sql` emits the
-  the **SQL generated from executing TypeScript**.
+  the **SQL generated from executing TypeScript**.
+
+## Automatically reloading SQL when it changes
+
+On sandboxes during development and editing of `.sql` or `.sql.ts` you may want
+to automatically re-load the contents into SQLite regularly. Since it can be
+time-consuming to re-run the same command in the CLI manually each time a file
+changes, you can use _watch mode_ instead.
+
+See [`sqlpagectl.ts`](universal/sqlpagectl.ts) for usage instructions.

lib/pattern/fhir-explorer/README.md

@@ -1,5 +1,8 @@
 # `surveilr` FHIR Explorer Pattern
 
+[Learn more about this pattern](https://surveilr.com/pattern/fhir-explorer) at
+[`www.surveilr.com`](https://surveilr.com/pattern/fhir-explorer).
+
 - `stateless-fhir.surveilr.sql` script focuses on creating views that define how
   to extract and present specific FHIR data from the `uniform_resource.content`
   JSONB column. It does not modify or store any persistent data; it only sets up
@@ -112,15 +115,6 @@ $ ../../universal/sqlpagectl.ts dev --watch . --watch ../../std --standalone
 # browse http://localhost:9000/fhir/info-schema.sql to see FHIR-specific views and tables
 ```
 
-## Automatically reloading SQL when it changes
-
-On sandboxes during development and editing of `.sql` or `.sql.ts` you may want
-to automatically re-load the contents into SQLite regularly. Since it can be
-time-consuming to re-run the same command in the CLI manually each time a file
-changes, you can use _watch mode_ instead.
-
-See: [`sqlpagectl.ts`](../../universal/sqlpagectl.ts).
-
 ## TODO
 
 - [ ] Review and consider language-agnostic