feat(docs): simplified architecture flow chart (#1925)

`:h telescope.nvim` now shows an overview of the telescope architecture

1 files changed, 46 insertions, 1 deletions

diff --git a/doc/telescope.txt b/doc/telescope.txt
index b1730c5..2a6b31c 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -15,6 +15,51 @@ Getting started with telescope:
      what options these implement
   6. Profit
 
+The below flow chart illustrates a simplified telescope architecture:
+┌───────────────────────────────────────────────────────────┐
+│      ┌────────┐                                           │
+│      │ Multi  │                                ┌───────+  │
+│      │ Select │    ┌───────┐                   │ Entry │  │
+│      └─────┬──*    │ Entry │    ┌────────+     │ Maker │  │
+│            │   ┌───│Manager│────│ Sorter │┐    └───┬───*  │
+│            ▼   ▼   └───────*    └────────┘│        │      │
+│            1────────┐                 2───┴──┐     │      │
+│      ┌─────│ Picker │                 │Finder│◄────┘      │
+│      ▼     └───┬────┘                 └──────*            │
+│ ┌────────┐     │       3────────+         ▲               │
+│ │Selected│     └───────│ Prompt │─────────┘               │
+│ │ Entry  │             └───┬────┘                         │
+│ └────────*             ┌───┴────┐  ┌────────┐  ┌────────┐ │
+│     │  ▲    4─────────┐│ Prompt │  │(Attach)│  │Actions │ │
+│     ▼  └──► │ Results ││ Buffer │◄─┤Mappings│◄─┤User Fn │ │
+│5─────────┐  └─────────┘└────────┘  └────────┘  └────────┘ │
+││Previewer│                                                │
+│└─────────┘                   telescope.nvim architecture  │
+└───────────────────────────────────────────────────────────┘
+
+  + The `Entry Maker` at least defines
+    - value: "raw" result of the finder
+    - ordinal: string to be sorted derived from value
+    - display: line representation of entry in results buffer
+
+  * The finder, entry manager, selected entry, and multi selections
+    comprises `entries` constructed by the `Entry Maker` from
+    raw results of the finder (`value`s)
+
+ Primary components:
+  1 Picker: central UI dedicated to varying use cases
+            (finding files, grepping, diagnostics, etc.)
+            see :h telescope.builtin
+  2 Finder: pipe or interactively generates results to pick over
+  3 Prompt: user input that triggers the finder which sorts results
+            in order into the entry manager
+  4 Results: listed entries scored by sorter from finder results
+  5 Previewer: preview of context of selected entry
+               see :h telescope.previewers
+
+A practical introduction into telescope customization is our `developers.md`
+(top-level of repo) and `:h telescope.actions` that showcase how to access
+information about the state of the picker (current selection, etc.).
 To find out more:
 https://github.com/nvim-telescope/telescope.nvim
 
@@ -29,8 +74,8 @@ https://github.com/nvim-telescope/telescope.nvim
   :h telescope.actions.set
   :h telescope.actions.utils
   :h telescope.actions.generate
-  :h telescope.previewers
   :h telescope.actions.history
+  :h telescope.previewers
 
 telescope.setup({opts})                                    *telescope.setup()*
     Setup function to be run by user. Configures the defaults, pickers and