chore: clarify workflows and diagrams

Signed-off-by: Pau Capdevila <[email protected]>

Author: pau-hedgehog

docs/architecture/management.md

@@ -6,15 +6,18 @@ The installation of a Hedgehog Fabric deployment is carried out using Fabricator
 
 In this workflow, the Kubernetes API Server processes the Fabric Custom Resources (CRs) and forwards them to the Fabric Controller. The Fabric Controller then translates these high-level network intents into concrete network configurations and manages their application to the underlying infrastructure. The Controller continuously monitors the state of the network resources, ensuring they match the desired state defined in the CRs.
 
+In this workflow, the user interacts with the Kubernetes API Server by creating or modifying Fabric Custom Resources (CRs). The Fabric Controller watches the Kubernetes API for changes to these CRs. Upon detecting a change, the Controller translates the high-level network intent into concrete configurations and applies them to the fabric switches.
+
+The Controller continuously reconciles the actual network state with the desired state declared in the CRs, ensuring consistency and reliability across the fabric.
+
 The diagram below illustrates the general workflow for fabric management:
 
 ```mermaid
 graph TD
 
-%% Define the nodes (General Workflow excludes Git & ArgoCD)
+%% Define the nodes
 User[User]
 Kubectl[kubectl]
-Fabricator[Fabricator]
 
 %% Control Node components
 subgraph ControlNode["Control Node"]
@@ -26,14 +29,12 @@ end
 
 %% Define the relationships
 Kubectl -.->|Direct kubectl commands| K8S
-User -.->|CLI| Fabricator
+User -.->|SSH Control| K9s
 User -.->|CLI| Kubectl
-Kubectl -.->|Plugin| KubectlFabric
-Fabricator -->|SSH access| K9s
-Fabricator -->|Applies CRs| K8S
+User -.->|SSH Control| KubectlFabric
 KubectlFabric -->|Interacts with| K8S
 K9s -->|UI Manages| K8S
-K8S -->|Sends CRDs| FC
+FC -->|Watches CRDs| K8S
 ```
 
 ---
@@ -42,7 +43,6 @@ K8S -->|Sends CRDs| FC
 
 ### **User**
 - **Creates Fabric CR YAMLs** and applies them through standard Kubernetes resource management.
-- **Directly interacts with SONiC switches** via the Fabricator CLI.
 - **Uses [`kubectl`](https://kubernetes.io/docs/reference/kubectl/) and `kubectl fabric`** to interact with the Kubernetes API for fabric resource management.
 
 ### **Kubernetes API Server (K8S)**
@@ -53,7 +53,7 @@ K8S -->|Sends CRDs| FC
 - [`kubectl`](https://kubernetes.io/docs/reference/kubectl/) is the standard CLI tool for [Kubernetes](https://kubernetes.io).
 - `kubectl fabric` is a plugin that extends `kubectl` with fabric-specific commands and interacts with the Kubernetes API Server. It supports the following commands:
     - **vpc** – Manage VPCs: create, attach, peer, or wipe all related resources
-    - **switch** – Manage switches: IP, SSH, serial, reboot, reinstall
+    - **switch** – Manage switches: get IP, SSH, serial, reboot, reinstall
     - **connection** – View connections: management, fabric, vpc-loopback
     - **switchgroup** – Create SwitchGroups
     - **external** – Manage external BGP peers and VPC peering
@@ -81,36 +81,44 @@ K8S -->|Sends CRDs| FC
 
 ---
 
-## **GitOps Functionality (ArgoCD)**
+## **GitOps Integration**
+
+GitOps is a continuous deployment approach where the desired state of a Kubernetes cluster is stored in Git. A GitOps controller monitors this repository and ensures the actual cluster state matches the declared state, using the Kubernetes API.
+
+Hedgehog Fabric is fully compatible with GitOps workflows and can be managed declaratively using any GitOps-compatible tool such as [ArgoCD](https://argo-cd.readthedocs.io/en/stable/) or [Flux](https://fluxcd.io).
 
-GitOps workflows can be leveraged using [ArgoCD](https://argo-cd.readthedocs.io/en/stable/). This is an alternative approach to show that a Fabric can be used with industry standard tools seamlessly.
+- **User Responsibilities:**
+    - Define Fabric Custom Resources (CRs) in YAML.
+    - Commit and push these CRs to a [Git repository](https://git-scm.com) for version control and collaboration.
 
-- **User Actions:**
-    - The user **creates Fabric CR YAMLs** and pushes them to a [Git repository](https://git-scm.com) for version control.
-- **ArgoCD Actions:**
-    - [ArgoCD](https://argo-cd.readthedocs.io/en/stable/) monitors the Git repository.
-    - ArgoCD **pulls the CRs from Git** and applies them to [Kubernetes](https://kubernetes.io) via the Kubernetes API Server.
+- **GitOps Tool Responsibilities:**
+    - Monitor the Git repository for updates.
+    - Apply changes to the cluster automatically via the Kubernetes API Server.
+
+This enables seamless integration of Hedgehog Fabric into modern CI/CD pipelines and Git-centric workflows.
 
 ```mermaid
 graph TD
 
-%% Define the nodes (GitOps includes Git & ArgoCD)
-User[User]
+%% Define the nodes
+User[User] 
 Kubectl[kubectl]
-    Git[Git Repository]
-ArgoCD[ArgoCD]
-
+Git[Git Repository]
+GitOps[GitOps]
 %% Control Node components
 subgraph ControlNode["Control Node"]
   K8S[Kubernetes API Server]
   FC[Fabric Controller]
 end
-
 %% Define the relationships
 User -->|Fabric CR YAMLs| Git
 Kubectl -.->|Direct kubectl commands| K8S
 User -.->|CLI| Kubectl
-Git -.->|ArgoCD pulls| ArgoCD
-ArgoCD -->|Applies CRs| K8S
-K8S -->|Sends CRDs| FC
+Git -.->|GitOps pulls| GitOps
+GitOps -->|Applies CRs| K8S
+%% Keep rel with empty text to keep layout
+K8S -->| | FC
+FC -->|Watches CRDs| K8S
+%% Style the original arrow invisible
+linkStyle 5 stroke:none,fill:none;
 ```