docs: add images depicting the architecture

README.md

@@ -25,9 +25,27 @@
 
 <hr>
 
+## 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
+
+![Architecture](https://www.plantuml.com/plantuml/png/VP2nRi8m48PtFyKrB310QDKkKMG1OQ6b4XLLzqjoX0Z7jiuELLNrtHj722gGEjh_tVzzzinvPDysIjpvFJK4npfdr5u8TwYrHSO62jDOeqbx-1O000ii3XMRLfUPKORJrBAnf1Inb32OJXyNJtFn8uJjvh0YYB9Ld2rXez3l33VHgUPI6wL5A4e6d_lQaypMgpJkRsG4w23KtqEQmfa3Klu5lBGviIPFxgPwRgsg2_IrqQ4AhRqUuCfaoskX3soLX-sNBc3uRF9Hxt5qtLdyxxvgEg4R-uSR-z1oOiDa8eDO0g-eksrtdVNSSmh3EDum1RSuXhqnXr7uYn8zvkW8DiRvgilVre5UvkBYshzAY8u5ux7iiWIstZ11M1Oz1jAGz8C9l3DgjoC6HmMJTs96kcmRzGi0)
+
+<small><a href="./docs/application-architecture.puml">Source</a>.</small>
+
 ## 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:**
 
 [![Initial Vault Structure](img/initial-vault-structure.png)](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
+
+!["switch" Workflow](https://www.plantuml.com/plantuml/png/nLF1RjGm4BtxAmPnWKFLRWMNFQ2M8d7X02nmT-qXiUHuZ3tUYh_7cpJOHbQ4gfLwoMx6y-Qzl7c-YIm3fycA5ppYX70qzq4w5iBdkb76vnVu7CYZjHZWvTNLc_TlRvlJ7p9PRlifyX3myELJKxuD0zrzQ4lUMwCa6t92E684EcAeo_lw1LB4U7e4s0aX5PkZP2pwX2XIBzujolRm5NybZ0npFyxmWbtKpq-uo9Y_0_OhZyQskIMf0H_HOJZrPGirJU1bZ0yKT8kexCdQY3DWeRekW9MnjhBy_LVe8Ic5CHQbDQxloNUlDtbhMxRPIdUNwF1WM8srzy3qo7jEkYLSU_WMp33aKY1hAN6XU4pVyfCHRSWElvqglTNH2jXKLHE82lp44BRI5gywtzyGjR6w8-TGCMJpnsBsTgPQtdN6F1qZotjhueYw7xAw-lGxVIs49V9vhhMG71kxhX4KJTxYQLO0DXFcMc__nUSLc9LpYjqOTBOwDyChZquRDrp6PSkNFwMng5ztjetkVs_txfbkz-vSjxjKIh-uGQVJPFy0)

docs/application-architecture.puml

@@ -0,0 +1,30 @@
+@startuml
+
+!theme vibrant
+
+skinparam component {
+    BackgroundColor<<propeller>> #004B5A
+}
+
+package "CI/CD Platform" {
+    component "<color:#white>CLI</color>" as prop1 << propeller >>
+}
+
+package Kubernetes {
+    component Application as app
+    component ArgoCD
+    component "Vault Sync (Job)" as vsync
+
+    component "<color:#white>Image</color>" 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

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