Update app-architecture.rst (#12993)

* Update app-architecture.rst

Second-iteration changes to the App Architecture page, addressing User Management and the Alias contract.

[CHANGELOG_BEGIN]
[CHANGELOG_END]

* Update app-architecture - edits - 1

Which/ how many additional details about the public party do you want to include here? Or as another option, should it be explained in-depth elsewhere?

[CHANGELOG_BEGIN]
[CHANGELOG_END]

* Update docs/source/getting-started/app-architecture.rst

Adding Moritz's suggested changes

[CHANGELOG_BEGIN]
[CHANGELOG_END]

Co-authored-by: Moritz Kiefer <moritz.kiefer@purelyfunctional.org>

* Update docs/source/getting-started/app-architecture.rst

Changed to Moritz's suggested wording.

[CHANGELOG_BEGIN]
[CHANGELOG_END]

Co-authored-by: Moritz Kiefer <moritz.kiefer@purelyfunctional.org>

* Update docs/source/getting-started/app-architecture.rst

Adding Moritz's suggestion w/link.

[CHANGELOG_BEGIN]
[CHANGELOG_END]

Co-authored-by: Moritz Kiefer <moritz.kiefer@purelyfunctional.org>

Co-authored-by: carrie-laben <91496516+carrie-laben@users.noreply.github.com>
Co-authored-by: Moritz Kiefer <moritz.kiefer@purelyfunctional.org>

docs/source/getting-started/app-architecture.rst

@@ -33,7 +33,7 @@ Using the file *Explorer* on the left sidebar, navigate to the ``daml`` folder a
 
 The Daml code defines the *data* and *workflow* of the application.
 Both are described in the ``User`` contract *template*.
-Let's look at the data portion first.
+Let's look at the data portion first:
 
 .. literalinclude:: code/templates-tarball/create-daml-app/daml/User.daml
   :language: daml
@@ -53,12 +53,12 @@ In this case all users that a particular user is following are able to see the u
 
 It's also important to distinguish between parties, users, and aliases in terms of naming:
  - Parties are unique across the entire Daml network. These must be allocated before you can use them to log in, and allocation results in a random-looking (but not actually random) string that identifies the party and is used in your Daml code. Parties are a builtin concept.
- - On each participant node you can create users with human-readable user ids. Each user can be associated with a party allocated on that participant node, and refers to that party only on that node. Users are a purely local concept, meaning you can never address a user on another node by user id, and you never work with users in your Daml code; party ids are always used for these purposes. Users are also a builtin concept.
- - Lastly we have user aliases. These are not a builtin concept, they are defined by an Alias template within the specific model used in this guide. Aliases serve as a way to address parties on all nodes via a human readable name.
+ - On each participant node you can create users with human-readable user ids. Each user can be associated with one or more parties allocated on that participant node, and refers to that party only on that node. Users are a purely local concept, meaning you can never address a user on another node by user id, and you never work with users in your Daml code; party ids are always used for these purposes. Users are also a builtin concept.
+ - Lastly we have user aliases. These are not a builtin concept, they are defined by an *Alias template* (discussed below) within the specific model used in this guide. Aliases serve as a way to address parties on all nodes via a human readable name.
 
-The social network user discussed in this guide is really a combination of all three of these concepts. Alice, Bob, and Charlie are all aliases that correspond to a single user id and party id each. 
+The social network users discussed in this guide are really a combination of all three of these concepts. Alice, Bob, and Charlie are all aliases that correspond to a single test user and a single party id each. As part of running `daml start`, the `init-script` specified in `daml.yaml` is executed. This points at the `Setup:setup` function which defines a :doc:`Daml Script </daml-script/index>` which creates 3 users `alice`, `bob` and `charlie` as well as a corresponding party for each they can act as. In addition to that, we also create a separate public party and allow the three users to read contracts for that party. This allows us to share the alias contracts with that public party and have them be visible to all 3 users.
 
-Let's see what the ``signatory`` and ``observer`` clauses mean in our app more concretely.
+Now let's see what the ``signatory`` and ``observer`` clauses mean in our app in more concrete terms.
 The user with the alias Alice can see another user, alias Bob, in the network only when Bob is following Alice (only if Alice is in the ``following`` list in his user contract). For this to be true, Bob must have previously started to follow Alice, as he is the sole signatory on his user contract.
 If not, Bob will be invisible to Alice.
 
@@ -66,7 +66,7 @@ This illustrates two concepts that are central to Daml: *authorization* and *pri
 Authorization is about who can *do* what, and privacy is about who can *see* what.
 In Daml you must answer these questions upfront, as they are fundamental to the design of the application.
 
-The last part of the Daml model is the operation to follow users, called a *choice* in Daml.
+The next part of the Daml model is the operation to follow users, called a *choice* in Daml:
 
 .. literalinclude:: code/templates-tarball/create-daml-app/daml/User.daml
   :language: daml
@@ -86,6 +86,13 @@ That is what the ``Follow`` choice does: after checking some preconditions, it a
 
 More detailed information on choices can be found in :doc:`our docs </daml/reference/choices>`.
 
+Finally, the ``User.daml`` file contains the Alias template that manages the link between user ids and their aliases. The alias template sets the public party we created in the setup script as the observer of the contract. Because we allow all users to read contracts visible to the public party, this allows e.g., Alice to see Bob’s `Alias` contract.
+
+.. literalinclude:: code/templates-tarball/create-daml-app/daml/User.daml
+  :language: daml
+  :start-after: -- ALIAS_BEGIN
+  :end-before: -- ALIAS_END
+
 Let's move on to how our Daml model is reflected and used on the UI side.
 
 TypeScript Code Generation