docs; wip

README.md

@@ -2,30 +2,46 @@
 
 `zrok` is a service designed to provide frictionless access to ephemeral, geo-scale reverse proxy capabilities.
 
+## Concepts
+
+`zrok` is conceptually structured like this:
+
 ![zrok overview](docs/images/zrok_v0.2_overview.png)
 
-`zrok` is designed with the following properties:
+### zrok Frontend, zrok Backend
 
-## Frictionless
+The `zrok` reverse proxy is broken into two halves, a _frontend_ and a _backend_. These two components connect over an OpenZiti network. Together the frontend and the backend work together to implement a reverse proxy.
 
-`zrok` is designed to provide a "frictionless" experience. A single binary and a single command is all that is required to enable ephemeral connectivity.
+The frontend is designed to be sited on an accessible network (typically the public internet). This allows traffic from that accessible network to ingress into the `zrok` frontend, across the dynamic reverse proxy.
+
+The backend is designed to be sited in a private environment, such as a private development server, or a serverless environment, or a container sidecar. The backend only needs outbound connectivity to reach the OpenZiti network and the `zrok` controller.
+
+The controller is a lightweight control plane component, which orchestrates connectivity between frontend and backend components.
+
+## Characteristics
+
+`zrok` has the following characteristics:
+
+### Frictionless
+
+`zrok` is designed to provide a "frictionless" experience. A single binary and a single command are all that is required to take advantage of all of the power of `zrok`.
 
 `zrok` works in a large number environments: developer shells, container sidecars, serverless environments, webhooks.
 
-## Expand with OpenZiti
+### Expand with OpenZiti
 
 `zrok` is built on top of OpenZiti, a next-generation solution for secure application connectivity. `zrok` is a fantastic way to start working with OpenZiti. Start with simple `zrok` ephemeral connectivity, and then layer on additional capabilities provided by the underlying OpenZiti network.
 
 Bring `zrok` into your existing OpenZiti deployment to provide rapid, ephemeral connectivity for a number of important HTTP scenarios.
 
-## World-Scale
+### World-Scale
 
-`zrok` is the software that powers the `zrok.io` service. It is designed to scale as large as you want.
+`zrok` is the software that powers the `zrok.io` world-scale service. `zrok` can scale as large as you need.
 
-## Multiple Isolated Tenants
+### Multiple Isolated Tenants
 
 A single `zrok` instance can support any number of isolated tenants, allowing them to coexist on top of the same OpenZiti deployment in a secure manner.
 
-## Self-hosting Capable
+### Self-hosting Capable
 
 Install `zrok` on top of your own OpenZiti network. `zrok` is simple to operate and scale.

docs/images/zrok.drawio

@@ -1 +1 @@
-<mxfile host="Electron" modified="2022-10-05T16:35:53.023Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/20.3.0 Chrome/104.0.5112.114 Electron/20.1.3 Safari/537.36" etag="xI9ovg_G-sjW6UjPZaTN" version="20.3.0" type="device"><diagram id="7Uu1JcSXeUW2rxoxs6Qh" name="Page-1">5Vrfc+I2EP5reDzG+mXjxyQkTafTDtfcTO760nFsBTQxFhUiwP31lbEMlmXAcWyTyeUl0kpeSd9+Wq1WDNDNfPObCBazP3lE4wF0os0AjQcQAoiI+pdKtlriEJxJpoJFWnYQPLCfNO+opSsW0aXRUXIeS7YwhSFPEhpKQxYIwddmt2cem6Mugim1BA9hENvSRxbJWSb1Hecgv6dsOtMj47xhHuR9tWA5CyK+LojQ7QDdCM5lVppvbmicgpfDkn13d6R1Py9BE1nngz+uHuVXNPX/+1c8xklIv7Dx1y9wlKl5DeKVXrCerdzmCAi+SiKaagEDdL2eMUkfFkGYtq6V0ZVsJuexbn5mcXzDYy5236LnUUjDUMmjYDnb61hKwV9oodvTiGDiqBY9Gyok3RxdJ9ijp2hH+ZxKsVVd9AdEM04TjvhZdX0wHvS0SWYFwwGshYEmzHSv+QCqKmhc34Kx2y3GY3I7GuMyxm0gCc9CiWCvUIIuoYzoc7CKZTvYYcc1sEP5TAvgAVABHukKO9wtCymICPXO7nTf9VDgtoMxGJn8HNn8xKMKiEed7XQL4p9q+QPo7lj1JFRpmpbuBE8kTaL3GaAFBKFjIggcG0LgVECISUcQopoQXgfhy0dAkOCPhiCxEBxvk2DOQiX8m6rFLqkqTQTfbC30FA7ShMjcwAlPaGnra1EQs2miqqHCjSr5dYoqU2HUlW6YsyhKh6m0ycFqTgfnGMJnzzHgVpgIdXaMWSb6h0lmk/wvKtdcvFhmUkOo8DcFUwWVi1QYxnwV9UJ4lKNy3OkCvyooQF0R3j9/sClPcZXeBXZIBcslC01cTP4pJMT2e7HyI60MVTik6+NNsXW81bVsXBpZN4oSuOoKE4gpledOa9sIBZTJieBB0DiQ7NWcRhXweoQJZ2qCexv71edqrmDJVyKk+pvijaOkxjPVeCU1GQaWmh0H9kt+xyZz+uKF94vyArgNiQFIWZE7JP2Sw3bBHZHjV+FGKRYHsCk3SiGp37PXsGP4esRYqonJRnwZOp5JGXyGMrvahAqmFpvGWplww+R3PVJaLrBP1Q6a0srbuZdZ7wRusCZHjwQX/XAUlbgFmzow5J5R1DVL7WtS1yx9m1fL2egMfWdkMBK56CQn00qZ2y3ytK4vRZfkKSmdjxA15Cnx0RCZqojT91FrX0gtrn6UnB0wsEJ5uvFiOTtgJ+2q0yE3XG0/Hsdqy3xMbFEpdkRVeZJ+sfX6P+kPN4Uf+VFdy4lCUvShJ/3n8YzrsYRtm94V13Sv8JLuFYISF0lD9wrdI6Tuy7XWeL1rm8LEoLA63+uHAl2SuDImvgSzLxrgYgcOncIfPE3P2jz3zZwfcHG/PG+a4nsHz2FDV+19Nld90UgYQ39I2ic0xviEWgi9Iew3SIZ2snIi2GsgqR3r3X/7NrGlt0m02M+ulceCzmJBzzn7bguqflfQ3btt02zgW/2LteMz+jVM37SdQmrRu6C6caBTzZR+vItbupRA3PSlo/wK3HPWEtp3mb37cO75Ug169zDbKSrR+nO++LrlRN+lX3yhHcFMVk/x7lH+9xS/hNqe+3PaZn/L7942qnr4fWW21w6/UkW3/wM=</diagram></mxfile>
+<mxfile host="Electron" modified="2022-10-05T18:28:36.690Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/20.3.0 Chrome/104.0.5112.114 Electron/20.1.3 Safari/537.36" etag="dpMboMi2jX4MoXVga1rh" version="20.3.0" type="device"><diagram id="7Uu1JcSXeUW2rxoxs6Qh" name="Page-1">5VpRc9soEP41fqxHgJCsx8ROLp3O3bmXzqTty40iEZuJLHwIx3Z//SEL2ULItqJIcibNS2BBC3z7sSyLB2i82PzB/eX8TxaSaACtcDNAkwGEACIs/6WSrZJY2M4kM05DJTsI7ukvkndU0hUNSaJ1FIxFgi51YcDimARCk/mcs7Xe7YlF+qhLf0YMwX3gR6b0gYZinkk9yzrI7widzdXIdt6w8PO+SpDM/ZCtCyJ0M0BjzpjISovNmEQpeDks2Xe3R1r38+IkFnU++HL1IL6imfffv/whigPyiU6+foKjTM2LH63UgtVsxTZHgLNVHJJUCxig6/WcCnK/9IO0dS2NLmVzsYhU8xONojGLGN99i55GAQkCKQ/9ZL7XkQjOnkmh2+MI29iSLWo2hAuyObpOsEdP0o6wBRF8K7uoD7BinCIc9rLq+mA86CqTzAuGA7YS+oows73mA6iyoHB9DcZOtxhP8M1oYpcxbgNJeBZKBHuFEnQJZUie/FUk2sHOthwNO5TPtAAeABXg4a6ws7tlIQEhJu7Zne45LvKddjAGI52fI5Of9qgC4lFnO92A+Jdc/gA6O1Y9clmapaVbzmJB4vBtBmgBQWjpCALLhBBYFRDauCMIUU0Ir/3g+T0giO33hiA2EJxsY39BAyn8h8jFJkSWppxttgZ6EgehQ6Rv4JjFpLT1lciP6CyW1UDiRqT8OkWVyjDqSjUsaBimw1Ta5GA1q4NzDNlnzzHgVJgIdXaMGSb6e0nin1RQk+h/EbFm/NkwlRxGhsApoDKwXKbCIGKrsBfSoxyZ444XeFWBAeqK9N75w016i6v0PrBDyk8SGui46ByUSPDt92LlR1oZypBI1SebYutkq2rZuCQ0bhUlcOU1xuczIs6d2KYRCijjEwEEJ5Ev6Is+jSrg1QhTRuUE9zb2qs/WXEHCVjwg6pviraOkxtXVuCU1GQaGmh0H9kt+w0az+uKF+5vyAjgNiQFwWZEzxP2Sw3TDHZHjd+FGKR4HsCk3SmGp17PXMOP4esRI5MREI74MLVenjH2GMrvalHAqF5vGW5lwQ8V3NVJaLrBP1g6a0srruZdZ7wRusCZHjwQX/XAUlbgFmzow5JxR1DVLzatS1yx9nVfL2WgNPWukMRI56CQn00qZ2y3ytK4vRZfkKS6djxA15Cn20BDpqrDV91FrXkoNrr6XvB3QsEJ5yvFieTtgJu6qUyJjJrcfiyK5Zd4ntqgUO6KqXEm/2Lr9n/SHm8KP/Kiu5UQhLvrQk/7zeNb1WNK2Te9q13Sv8JLuFYISF3FD9wqdI6Tuy7XWeMFrm8JYo7A83+uHAl2SuDImvgSzLxrg2hYcWoU/eJqetXnu6Tk/4Nj98rxpiu8NPIcNXbX70Vz1RSNhG3pD3D6hbds+oRZCdwj7DZKhmayccvriC2LGenffvk1N6U0cLveza+WxoLNY0LXOvt2Cqt8WdPd22zQb+Fr/Yuz4jH4N0zdtp5Ba9C6obhxoVTOlH+/ilC4l0G760lF+Ce45awnNu8zefVh3LJGD3t7Pd4pKtP6Yr75OOdF36VdfaEYw09VjtHuY/5ziFxPTc39M2+xv+d3bRlYPv7HM9trhl6ro5n8=</diagram></mxfile>