chore: refine and deduplicate architecture pages

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

Author: pau-hedgehog

docs/architecture/management.md

@@ -1,10 +1,12 @@
 # Fabric Management
 
+This section focuses on operational aspects of Hedgehog Fabric, explaining available tools and typical workflows for administrators. It builds upon the architectural concepts explained in the [Overview](overview.md).
+
 The installation of a Hedgehog Fabric deployment is carried out using Fabricator (hhfab CLI). Once deployed, ongoing operations are managed via the [Kubernetes](https://kubernetes.io) CLI, [`kubectl`](https://kubernetes.io/docs/reference/kubectl/).
 
-In this workflow, the Kubernetes API Server processes the Fabric Custom Resources (CRs) and forwards them to the Fabric Controller. The Fabric Controller then generates the required SONiC configurations and dispatches them to the Fabric Agent, which applies these configurations to the SONiC Config DB via gNMI. Simultaneously, Alloy collects metrics and logs from the SONiC switches, sending this information to the monitoring tools for continuous monitoring.
+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.
 
-The diagram below illustrates the general workflow for fabric management as well as the interactions between control plane components and the SONiC switches that form the Fabric.
+The diagram below illustrates the general workflow for fabric management:
 
 ```mermaid
 graph TD
@@ -22,16 +24,6 @@ subgraph ControlNode["Control Node"]
   KubectlFabric["kubectl fabric"]
 end
 
-%% SONiC Switch components
-subgraph SONiCSwitch["SONiC Switch"]
-  FA[Fabric Agent]
-  Alloy[Alloy]
-  DB[SONiC Config DB]
-end
-
-%% External monitoring
-Monitoring[Loki/Grafana/Tempo/Mimir]
-
 %% Define the relationships
 Kubectl -.->|Direct kubectl commands| K8S
 User -.->|CLI| Fabricator
@@ -42,18 +34,14 @@ Fabricator -->|Applies CRs| K8S
 KubectlFabric -->|Interacts with| K8S
 K9s -->|UI Manages| K8S
 K8S -->|Sends CRDs| FC
-FC -->|Generates SONiC Configs| FA
-FA -->|Applies Config via gNMI| DB
-FA -->|Reports Metrics| Alloy
-Alloy -->|Sends Logs & Metrics| Monitoring
 ```
 
 ---
 
 ## **Management Workflow Overview**
 
 ### **User**
-- **Creates Fabric CR YAMLs** and commits them to version control.
+- **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.
 
@@ -71,19 +59,11 @@ Alloy -->|Sends Logs & Metrics| Monitoring
 
 ### **K9s**
 - A Kubernetes UI that provides visibility and control over Kubernetes resources, allowing you to manage pods, nodes, services, logs, and Fabric resources efficiently. It includes some helper plugins:
-  - **SSH** – SSH into a fabric switch
-  - **Serial** – Open a serial connection to a fabric switch
-  - **Reboot** – Reboot a fabric switch
-  - **Power Reset** Perform a power reset on a fabric switch in the NOS
-  - **Reinstall** – Reinstall a fabric switch
-
-### **SONiC Switch Relevant Components**
-- **Fabric Agent:** Receives configurations from the Fabric Controller and applies them to the SONiC switches via gNMI.
-- **Alloy:** Monitors SONiC and reports metrics.
-- **SONiC Config DB:** Stores and manages switch configuration data.
-
-### **Monitoring**
-- Logs and metrics from SONiC are collected and sent to [Loki](https://grafana.com/oss/loki/) and [Mimir](https://grafana.com/oss/mimir/) for visualization and analysis through [Grafana](https://grafana.com).
+    - **SSH** – SSH into a fabric switch
+    - **Serial** – Open a serial connection to a fabric switch
+    - **Reboot** – Reboot a fabric switch
+    - **Power Reset** Perform a power reset on a fabric switch in the NOS
+    - **Reinstall** – Reinstall a fabric switch
 
 ---
 
@@ -92,10 +72,10 @@ Alloy -->|Sends Logs & Metrics| Monitoring
 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 Actions:**
-  - The user **creates Fabric CR YAMLs** and pushes them to a [Git repository](https://git-scm.com) for version control.
+    - 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.
+    - [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.
 
 ```mermaid
 graph TD

docs/architecture/overview.md

@@ -1,5 +1,7 @@
 # Overview
 
+This section provides an architectural understanding of Hedgehog Open Network Fabric, explaining its components and their relationships.
+
 Hedgehog Open Network Fabric leverages the Kubernetes API to manage its resources. All user-facing APIs are exposed as Kubernetes Custom Resources Definitions (CRDs), allowing users to manage Fabric resources using standard Kubernetes tools.
 
 To make network switches Kubernetes-aware, the Fabric employs an **Agent** running on each switch. This agent acts as an interface  between the Kubernetes control plane and the switch internal network configuration mechanisms. It continuously syncs desired state from Kubernetes via the Fabric Controller and applies configurations using **gNMI** (gRPC Network Management Interface).