% Real-world system depictions with *depict* % Michael Stone % September 13, 2022 --- header-includes: | --- ## Who uses *depict*? Today, *depict* seems to be of greatest interest to people working in * consulting, * defense, * UX/UXR, * "cloud", and specifically to people who are interested in scaling up the use of [STPA](https://psas.scripts.mit.edu/home/get_file.php?name=STPA_handbook.pdf) inside organizations working in these areas. ## What "real-world" example uses can you share? So far, most of the uses of *depict* that I'm aware of are confidential; however, one real-world use that I can share relates to using *depict* to design itself. To be clear, today, *depict* runs entirely client-side either natively or via static HTML and WASM -- but getting to this point was a [substantial lift](../wasm-20220628/), and wasn't how I had initially envisioned things. Instead, while originally designing depict, I initially envisioned shipping it as a fairly bespoke cloud-based web app based on something like this sketch: ACME operatorDNS API (gandi)LetsEncryptclouddepict service operatordeploy-rsend-usernix builderserverterraformupdate DNSissue certrenew certcertupdate certs???build profilecontentactivate profileupdate DNSprovision server which I produced via this depiction: ``` end-user cloud -: / content acme-operator server: update certs, acme-operator dns: update DNS, acme-operator LetsEncrypt: issue cert, renew cert/ cert deploy-rs builder server: build profile, : activate profile, terraform cloud: provision server, terraform deploy-rs - terraform dns: update DNS, builder: nix builder, dns: DNS API (gandi), acme-operator: ACME operator, me acme-operator me terraform me deploy-rs me: depict service operator, cloud [ server ] ``` ---- *Note*: as a syntax reminder: * `-` means *flow* or *peer* relationships, vs known hierarchical relationships, * `:` means *labels*, whether between peers, along lines of authority, or locally * `/` means *reverse*, i.e., feedback or "return" flows, vs control actions or inputs * `[]` means *nest*, in which all contained components are present. ---- Here, the primary goal of this design is to serve content to a population of end-users: ``` end-user cloud -: / content ``` but to do that on the internet today, I am envisioning a server or service running in the cloud ``` cloud [ server ] ``` with suitable TLS certificates. ``` acme-operator server: update certs, ``` Now, of course, there are many ways to obtain appropriate certificates, some of which might be even better (faster, more reliable, more secure) than the one that I've just sketched. However, for the purpose of this design, since I'm already very familiar with it, and since I don't want to commit at this stage to which if any cloud KMS I might use instead, I'm actually going to imagine that certificates in question will be provided directly to the cloud server we've created by an "operator" process that I'm going to refer to as the `acme-operator` since I'm also contemplating, for now, using LetsEncrypt for certificate issuing via the ACME DNS-01 challenge protocol: ``` acme-operator dns: update DNS, acme-operator LetsEncrypt: issue cert, renew cert/ cert ``` Next, now that we notionally have certificates for our server, we need a way to get appropriate software running on the server to use to serve our content. Again, while there are many ways to solve (or to avoid in the first place) this problem, I'm going to pencil in Serokell's [deploy-rs](https://github.com/serokell/deploy-rs) script: ``` deploy-rs builder server: build profile, : activate profile, builder: nix builder, ``` as my main software deployment mechanism, since I'm [most comfortable](../nix-tutorial/) with [nix flakes](https://www.tweag.io/blog/2020-05-25-flakes/) for managing my software supply chain. Now that we have a cloud, certificates, and software, there are two final details required to bring closure to this sketch: a. server provisioning and b. coordination / feedback For the purposes of this sketch, I will therefore propose that I will use [terraform](https://www.terraform.io) to accomplish this provisioning: ``` terraform cloud: provision server, terraform dns: update DNS, ``` and `me` as the notional "depict service operator" who is responsible for managing these three interacting pieces and debugging anything that goes wrong via control actions, feedback, and decision-making that I did not bother to elaborate since the complexity of even this relatively simple design helped convince me that, if at all possible, I instead focus all my efforts on finding ways to reduce the total operational complexity required to deliver the service: ``` me acme-operator me terraform me deploy-rs me: depict service operator, ``` Then, with a couple of final cosmetic/labeling touches, we achieve the sketch originally shown above and repeated here for ease of reference: ACME operatorDNS API (gandi)LetsEncryptclouddepict service operatordeploy-rsend-usernix builderserverterraformupdate DNSissue certrenew certcertupdate certs???build profilecontentactivate profileupdate DNSprovision server ## Examples welcome! Do you have system sketches made with *depict* that I can share or link to? If so, please send me your depictions, along with information about whether and how you would them to be attributed!