diff --git a/README.md b/README.md
index 5279832..cf5c0c5 100644
--- a/README.md
+++ b/README.md
@@ -25,9 +25,27 @@
+## Target Architecture
+
+`propeller` is designed to seamlessly integrate with a specific application deployment architecture commonly used in modern environments:
+
+- **Containerized Applications:** Applications are deployed within a [Kubernetes](https://kubernetes.io/) cluster for scalability and efficient resource management.
+- **PostgreSQL Database:** Data is persisted in a robust [PostgreSQL](https://www.postgresql.org/) database, known for its reliability and feature set.
+- **Vault for Secrets Management:** Sensitive information like passwords and API keys are securely stored and managed within [Vault](https://www.hashicorp.com/products/vault) for enhanced security.
+- **ArgoCD for GitOps Automation:** [ArgoCD](https://argoproj.github.io/cd/) is utilized for GitOps principles, enabling declarative management of infrastructure and applications through Git repositories. Importantly, ArgoCD can also manage the synchronization of secrets from Vault using plugins like [@postfinance/kubectl-vault_sync](https://github.com/postfinance/kubectl-vault_sync).
+
+### Visual Representation
+
+
+
+Source.
+
## Configuration
-Propeller relies on a configuration file and an environment variable to function correctly.
+Propeller relies on a [configuration file](#configuration-file-yaml) and [environment variables](#vault-authentication-token-vault_token) to function correctly.
+
+Once you're done configuring, [initialize Vault](#initializing-vault-for-secret-management).
+And that's it: Proceed to [rotate your secrets](#rotating-secrets).
### Configuration File (YAML)
@@ -76,9 +94,13 @@ It creates the necessary structure within your Vault instance to securely store
**Command Usage:**
```cookie
-propeller init-vault
+propeller init-vault [OPTIONS]
```
+#### Options
+
+#### Result
+
After running the command, the specified Vault path will contain a JSON secret with the following structure:
```json
@@ -94,8 +116,24 @@ After running the command, the specified Vault path will contain a JSON secret w
**Note that any previously present secrets in this path will be lost in the process!**
-The "TBD" placeholders indicate that these values _must_ be filled once with the initial values before continuing the rotation process.
+The "TBD" placeholders indicate that these values _must_ be filled once with the initial values before continuing the [rotation process](#rotating-secrets).
-#### Example Result
+**Screenshot of initialized Vault secret:**
[](img/initial-vault-structure.png)
+
+### Rotating Secrets
+
+Once Vault has been initialized, you're ready to frequently rotate your database secrets.
+
+**Command Usage:**
+
+```cookie
+propeller rotate [OPTIONS]
+```
+
+#### Options
+
+#### Sequence Diagram
+
+
diff --git a/docs/application-architecture.puml b/docs/application-architecture.puml
new file mode 100644
index 0000000..c202ad7
--- /dev/null
+++ b/docs/application-architecture.puml
@@ -0,0 +1,30 @@
+@startuml
+
+!theme vibrant
+
+skinparam component {
+ BackgroundColor<> #004B5A
+}
+
+package "CI/CD Platform" {
+ component "CLI" as prop1 << propeller >>
+}
+
+package Kubernetes {
+ component Application as app
+ component ArgoCD
+ component "Vault Sync (Job)" as vsync
+
+ component "Image" as prop2 << propeller >>
+
+ ArgoCD ..> app: Manages
+ ArgoCD ..> vsync: Manages (//PreSync// hook)
+}
+
+database PostgreSQL as db
+component Vault
+
+app --> db: Store data
+vsync <--> Vault: Transfer secrets
+
+@enduml
diff --git a/docs/switch-workflow.puml b/docs/switch-workflow.puml
new file mode 100644
index 0000000..deb7438
--- /dev/null
+++ b/docs/switch-workflow.puml
@@ -0,0 +1,76 @@
+@startuml
+
+!theme vibrant
+
+participant Propeller #004B5A
+participant Vault
+participant PostgreSQL
+participant ArgoCD
+participant Application
+
+note over Application: Application uses user 1
+
+activate Propeller
+
+Propeller -> Vault: Request active user
+activate Vault
+Vault --> Propeller: user 1
+deactivate Vault
+
+Propeller -> Propeller: Generate random password
+
+Propeller -> PostgreSQL: Rotate user 2 password
+activate PostgreSQL
+PostgreSQL --> Propeller: Success
+deactivate PostgreSQL
+
+Propeller -> Vault: Update user 2 password
+activate Vault
+Vault --> Propeller: Success
+deactivate Vault
+
+Propeller -> Vault: Switch active user to user 2
+activate Vault
+Vault --> Propeller: Success
+deactivate Vault
+
+Propeller -> ArgoCD: Trigger rollout
+activate ArgoCD
+ArgoCD -> Application: Sync
+activate Application
+ArgoCD --> Propeller: Success
+deactivate ArgoCD
+
+Application -> Vault: Request active user
+activate Vault
+Vault --> Application: user 2
+deactivate Vault
+
+Application -> PostgreSQL: Connect with user 2
+activate PostgreSQL
+PostgreSQL --> Application: Connection established
+deactivate PostgreSQL
+deactivate Application
+
+note over Application: Application uses user 2
+
+loop Poll until rollout complete or timeout
+Propeller -> ArgoCD: Request rollout status
+activate ArgoCD
+ArgoCD --> Propeller: Status (pending/success/failed)
+deactivate ArgoCD
+end
+
+Propeller -> PostgreSQL: Rotate user 1 password
+activate PostgreSQL
+PostgreSQL --> Propeller: Success
+deactivate PostgreSQL
+
+Propeller -> Vault: Update user 1 password
+activate Vault
+Vault --> Propeller: Success
+deactivate Vault
+
+deactivate Propeller
+
+@enduml