docs: screenshots and text improvements (#912)

* additional content

* even more content

site/docs/administrate/01-console.en.md

@@ -6,24 +6,62 @@ title: Console
 
 Console is the ZITADEL Graphical User Interface.
 
+#### ZITADEL Users
+
 **Users** can manage some information on their own.
 
 - profile information
 - credentials
 - external logins
 
+<div class="zitadel-gallery" itemscope itemtype="http://schema.org/ImageGallery">
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/console_user_entry.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/console_user_entry.png" itemprop="thumbnail" alt="User Entry" />
+        </a>
+        <figcaption itemprop="caption description">User Entry</figcaption>
+    </figure>
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/console_user_personal_information.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/console_user_personal_information.png" itemprop="thumbnail" alt="User Personal Information" />
+        </a>
+        <figcaption itemprop="caption description">User Personal Information</figcaption>
+    </figure>
+</div>
+
+#### ZITADEL Organisation Owners
+
 Users (**org owners**) who manage organisations do this also with Console.
 
-- Organisation settings (policies, domains, idp's)
+- Organisation settings (policies, domains, idps)
 - Manage users
 - Manage projects, clients and roles
 - Give access to users
 
+#### ZITADEL Administrators
+
 For the **IAM Administrators** there is also a section in Console solely intended to manage the system.
 
 - Check failed events
 - Reset read models
-- Define system policies
+- Manage system settings and policies
+
+<div class="zitadel-gallery" itemscope itemtype="http://schema.org/ImageGallery">
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/console_admin_entry.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/console_admin_entry.png" itemprop="thumbnail" alt="Adminstrator Entry" />
+        </a>
+        <figcaption itemprop="caption description">Adminstrator Entry</figcaption>
+    </figure>
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/console_admin_system.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/console_admin_system.png" itemprop="thumbnail" alt="System Administration" />
+        </a>
+        <figcaption itemprop="caption description">System Administration</figcaption>
+    </figure>
+</div>
+
+> ZITADEL does display a banner to warn the administrator that his account has elevated privileges!
 
 ### Technologies
 

site/docs/administrate/02-organisations.en.md

@@ -107,6 +107,23 @@ Congratulations your are done! You can check this by visiting [https://console.z
 
 > This only works when the [user](administrate#Users) is member of this [organisation](administrate#Organisations)
 
+### Manage Organisation ZITADEL Roles
+
+<div class="zitadel-gallery" itemscope itemtype="http://schema.org/ImageGallery">
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/console_org_manage_roles_1.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/console_org_manage_roles_1.png" itemprop="thumbnail" alt="Manage ZITADEL Roles 1" />
+        </a>
+        <figcaption itemprop="caption description">Manage ZITADEL Roles 1</figcaption>
+    </figure>
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/console_org_manage_roles_2.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/console_org_manage_roles_2.png" itemprop="thumbnail" alt="Manage ZITADEL Roles 2" />
+        </a>
+        <figcaption itemprop="caption description">Manage ZITADEL Roles 2</figcaption>
+    </figure>
+</div>
+
 ### Audit organisation changes
 
 All changes to the organisation are displayed on the organisation menu within [ZITADEL Console](https://console.zitadel.ch/org) organisation menu. Located on the right hand side under "activity".

site/docs/administrate/03-projects.en.md

@@ -29,7 +29,9 @@ To achieve this the owner of a project can grant (some could say delegate) certa
 After granting that organisation it can manage on its own which user has what roles.
 This feature is especially useful for service providers, because they are able to establish a great self-service culture for their business customers.
 
-**Authorizations** 
+**Authorizations**
+
+> TODO, Link to authorizations
 
 #### Project vs. granted Project
 
@@ -75,6 +77,27 @@ Create a new project with a name which explains what's the intended use of this
 
 > Screenshot here
 
+### Manage Project Authorisations
+
+> Screenshot here
+
+### Manage Project ZITADEL Roles
+
+<div class="zitadel-gallery" itemscope itemtype="http://schema.org/ImageGallery">
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/console_project_manage_roles_1.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/console_project_manage_roles_1.png" itemprop="thumbnail" alt="Manage ZITADEL Roles 1" />
+        </a>
+        <figcaption itemprop="caption description">Manage ZITADEL Roles 1</figcaption>
+    </figure>
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/console_project_manage_roles_2.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/console_project_manage_roles_2.png" itemprop="thumbnail" alt="Manage ZITADEL Roles 2" />
+        </a>
+        <figcaption itemprop="caption description">Manage ZITADEL Roles 2</figcaption>
+    </figure>
+</div>
+
 ### Audit project changes
 
 > Screenshot here

site/docs/administrate/06-users.en.md

@@ -51,8 +51,6 @@ Image 1: User List Search
     </figure>
 </div>
 
-Image 2: User List
-
 <div class="zitadel-gallery" itemscope itemtype="http://schema.org/ImageGallery">
     <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
         <a href="img/console_user_create_form.png" itemprop="contentUrl" data-size="1920x1080">
@@ -62,8 +60,6 @@ Image 2: User List
     </figure>
 </div>
 
-Image 3: User Create Form
-
 <div class="zitadel-gallery" itemscope itemtype="http://schema.org/ImageGallery">
     <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
         <a href="img/console_user_create_done.png" itemprop="contentUrl" data-size="1920x1080">
@@ -73,8 +69,6 @@ Image 3: User Create Form
     </figure>
 </div>
 
-Image 4: User Create Done
-
 #### Set Password
 
 > Screenshot here
@@ -83,10 +77,27 @@ Image 4: User Create Done
 
 > Screenshot here
 
-### Authorizations
+### Manage User Authorisations
 
 > Screenshot here
 
+### Manage User ZITADEL Roles
+
+<div class="zitadel-gallery" itemscope itemtype="http://schema.org/ImageGallery">
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/console_user_manage_roles_1.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/console_user_manage_roles_1.png" itemprop="thumbnail" alt="Manage ZITADEL Roles 1" />
+        </a>
+        <figcaption itemprop="caption description">Manage ZITADEL Roles 1</figcaption>
+    </figure>
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/console_user_manage_roles_2.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/console_user_manage_roles_2.png" itemprop="thumbnail" alt="Manage ZITADEL Roles 2" />
+        </a>
+        <figcaption itemprop="caption description">Manage ZITADEL Roles 2</figcaption>
+    </figure>
+</div>
+
 ### Audit user changes
 
 > Screenshot here

site/docs/administrate/09-authorisations.de.md

@@ -0,0 +1,5 @@
+---
+title: Autorisierungen
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/administrate/09-authorisations.en.md

@@ -0,0 +1,42 @@
+---
+title: Authorisations
+---
+
+### What are Authorisations
+
+**ZITADEL** thinks of authorisations as resource who clearly defines which user has what roles. Authorisations are also called "user grant".
+
+### Manage Authorisations
+
+You can grant Roles directly on a project. Or, if the user is in your organisation, by apply in the roles to the user directly.
+Additionaly you can use the authorization menu item to search for a user and project.
+
+<div class="zitadel-gallery" itemscope itemtype="http://schema.org/ImageGallery">
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/console_authz_overview.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/console_authz_overview.png" itemprop="thumbnail" alt="Manage Authorisations Overview" />
+        </a>
+        <figcaption itemprop="caption description">Manage Authorisations Overview</figcaption>
+    </figure>
+        <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/console_authz_add_1.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/console_authz_add_1.png" itemprop="thumbnail" alt="Manage Authorisations 1" />
+        </a>
+        <figcaption itemprop="caption description">Manage Authorisations 1</figcaption>
+    </figure>
+        <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/console_authz_add_2.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/console_authz_add_2.png" itemprop="thumbnail" alt="Manage Authorisations 2" />
+        </a>
+        <figcaption itemprop="caption description">Manage Authorisations 2</figcaption>
+    </figure>
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/console_authz_add_3.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/console_authz_add_3.png" itemprop="thumbnail" alt="Manage Authorisations 3" />
+        </a>
+        <figcaption itemprop="caption description">Manage Authorisations 3</figcaption>
+    </figure>
+</div>
+
+- [Manage Project Authorisations](administrate#Manage_Project_Authorisations)
+- [Manage User Authorisations](administrate#Manage_User_Authorisations)

site/docs/administrate/70-zitadelroles.de.md

@@ -0,0 +1,5 @@
+---
+title: ZITADEL Rollen
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/administrate/70-zitadelroles.en.md

@@ -0,0 +1,49 @@
+---
+title: ZITADEL Roles
+---
+
+### ZITADEL's Roles
+
+**ZITADEL's** own role model is built around the IAM resources. The roles have some hierarchies to them. For example a IAM_OWNER can view and edit every resource of the system. ORG_OWNERS can only manage their resources included within their organisation. This includes projects, clients, users, and so on.
+
+#### System Roles
+
+IAM_OWNER
+
+IAM_OWNER_VIEWER
+
+#### Organisation Roles
+
+ORG_OWNER
+
+ORG_OWNER_VIEWER
+
+ORG_USER_PERMISSION_EDITOR
+
+ORG_PROJECT_PERMISSION_EDITOR
+
+ORG_PROJECT_CREATOR
+
+#### Owned Project Roles
+
+PROJECT_OWNER
+
+PROJECT_OWNER_VIEWER
+
+PROJECT_OWNER_GLOBAL
+
+PROJECT_OWNER_VIEWER_GLOBAL
+
+#### Granted Project Roles
+
+PROJECT_GRANT_OWNER
+
+PROJECT_GRANT_OWNER_VIEWER
+
+### Manage ZITADEL Roles
+
+You can grant ZITADEL Roles directly on a resource like organisation or project. Or, if the user is in your organisation, by applying in the roles to the user directly.
+
+- [Manage Organisation ZITADEL Roles](administrate#Manage_Organisation_ZITADEL_Roles)
+- [Manage Project ZITADEL Roles](administrate#Manage_Organisation_ZITADEL_Roles)
+- [Manage User ZITADEL Roles](administrate#Manage_Organisation_ZITADEL_Roles)

site/docs/administrate/90-system.en.md

@@ -23,7 +23,22 @@ There is even a possibility to regenerate a read model.
 > When a read model is regenerated it might take up some time to be fully operational again
 > Depending on the model which is regenerated this might have a operational impact for the end-users
 
-> Screenshot here
+<div class="zitadel-gallery" itemscope itemtype="http://schema.org/ImageGallery">
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/console_iam_admin_views.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/console_iam_admin_views.png" itemprop="thumbnail" alt="IAM View Management" />
+        </a>
+        <figcaption itemprop="caption description">IAM View Management</figcaption>
+    </figure>
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/console_iam_admin_failed.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/console_iam_admin_failed.png" itemprop="thumbnail" alt="IAM Failed Events" />
+        </a>
+        <figcaption itemprop="caption description">IAM Failed Events</figcaption>
+    </figure>
+</div>
+
+> Additional infos to the architecture of ZITADEL is located in [Architecture Docs](documentation#Architecture)
 
 ### Secret Handling
 

site/docs/documentation/02-architecture.en.md

@@ -2,4 +2,98 @@
 title: Architecture
 ---
 
-> TBD
+> Images in better quality follow soon.
+
+### Software Architecture
+
+**ZITADEL** is built with two essential patterns. Eventsourcing and CQRS. Due to the nature of eventsourcing **ZITADEL** provides the unique capability to generate a strong audit trail of ALL the things that happen to its resources, without compromising on storage cost or audit trail length.
+
+The combination with CQRS makes **ZITADEL** eventual consistent which, from our perspective is a great benefit. It allows us to build a SOR (Source of Records) which is the one single point of truth for all computed states. The SOR needs to be transaction safe to make sure all operations are in order.
+
+Each **ZITADEL** contains all components of the IAM, from serving as API, rendering / serving GUI's, background processing of events and task or being a GITOPS style operator. This AiO (All in One) approach makes scaling from a single machine to a multi region (multi cluster) seamless.
+
+<div class="zitadel-gallery" itemscope itemtype="http://schema.org/ImageGallery">
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/zitadel_software_architecture.png" itemprop="contentUrl" data-size="1530x681">
+            <img src="img/zitadel_software_architecture.png" itemprop="thumbnail" alt="Software Architecture" />
+        </a>
+        <figcaption itemprop="caption description">Software Architecture</figcaption>
+    </figure>
+</div>
+
+#### Component Command Side
+
+The **command handler** receives all operations who alter a IAM resource. For example if a user changes his name.
+This information is then passed to **command validation** for processing of the business logic, for example to make sure that the user actually can change his name. If this succeeds all generated events are inserted into the eventstore when required all within one transaction.
+
+- Transaction safety is a MUST
+- Availability MUST be high
+
+> When we classify this with the CAP theorem we would choose **Consistent** and **Available** but leave **Performance** aside.
+
+#### Component Spooler
+
+The spoolers job is it to keep a query view up-to-date or at least look that it does not have a too big lag behind the eventstore.
+Each query view has its own spooler who is responsible to look for the events who are relevant to generate the query view. It does this by triggering the relevant projection.
+Spoolers are especially necessary where someone can query datasets instead of single ids.
+
+> The query side has the option to dynamically check the eventstore for newer events on a certain id, see query side for more information
+> Each view can have exactly one spooler, but spoolers are dynamically leader elected, so even if a spooler crashes it will be replaced in a short amount of time.
+
+#### Component Query Side
+
+The query handler receives all read relevant operations. These can either be query or simple `getById` calls.
+When receiving a query it will proceed by passing this to the repository which will call the database and return the dataset.
+If a request calls for a specific id the call will, most of the times, be revalidated against the eventstore. This is achieved by triggering the projection to make sure that the last sequence of a id is loaded into the query view.
+
+- Easy to query
+- Short response times (80%of queries below 100ms on the api server)
+- Availability MUST be high
+
+> When we classify this with the CAP theorem we would choose **Available** and **Performance** but leave **Consistent** aside
+> TODO explain more here
+
+#### Component HTTP Server
+
+The http server is responsible for serving the management GUI called **ZITADEL Console**, serving the static assets and as well rendering server side html (login, password-reset, verification, ...)
+
+### Cluster Architecture
+
+A **ZITADEL Cluster** is a highly available IAM system with each component critical for serving traffic laid out at least three times.
+As our storage (CockroachDB) relies on Raft it is also necessary to always utilizes odd numbers to address for "split brain" scenarios.
+Hence our reference design is to have three application nodes and three Storage Nodes.
+
+If you deploy **ZITADEL** with our GITOPS Tooling [**ORBOS**](https://github.com/caos/orbos) we create 7 seven nodes. One management, three application and three storage nodes.
+
+> You can horizontaly scale zitadel, but we recommend to use multiple cluster instead to reduce the blast radius from impacts to a single cluster
+
+<div class="zitadel-gallery" itemscope itemtype="http://schema.org/ImageGallery">
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/zitadel_cluster_architecture.png" itemprop="contentUrl" data-size="1530x681">
+            <img src="img/zitadel_cluster_architecture.png" itemprop="thumbnail" alt="Cluster Architecture" />
+        </a>
+        <figcaption itemprop="caption description">Cluster Architecture</figcaption>
+    </figure>
+</div>
+
+### Multi Cluster Architecture
+
+To scale **ZITADEL** is recommend to create smaller clusters, see cluster architecture and then create a fabric which interconnects the database.
+In our reference design we recommend to create a cluster per cloud provider or availability zone and to group them into regions.
+
+For example, you can run three cluster for the region switzerland. On with GCE, one with cloudscale and one with inventx.
+
+With this design even the outage of a whole data-center would have a minimal impact as all data is still available at the other two locations.
+
+> Cockroach needs to be configured with locality flags to proper distribute data over the zones
+> East - West connectivity for the database can be solved at you discretion. We recommend to expose the public ips and run traffic directly without any VPN or Mesh
+> Use MTLS in combination with IP Allowlist in the firewalls!
+
+<div class="zitadel-gallery" itemscope itemtype="http://schema.org/ImageGallery">
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/zitadel_multicluster_architecture.png" itemprop="contentUrl" data-size="1530x681">
+            <img src="img/zitadel_multicluster_architecture.png" itemprop="thumbnail" alt="Multi-Cluster Architecture" />
+        </a>
+        <figcaption itemprop="caption description">Multi-Cluster Architecture</figcaption>
+    </figure>
+</div>

site/docs/use/00-user.en.md

@@ -14,7 +14,7 @@ title: User Manual
 
 ### Manage Multi Factor
 
-### Federation
+### Identity Linking
 
 #### Auto Register