chore(introduction): cleanup redundant paragraphs with architecture

Signed-off-by: SkalaNetworks <contact@skala.network>

Author: SkalaNetworks

docs/introduction.md

@@ -44,7 +44,7 @@ Kubernetes is a container orchestrator, not a VM orchestrator. Using it as the c
 
 The trade-off is adapting Kubernetes to VMs, storage, and CSP-style networking. Superphenix does that by combining a multitude of **open source projects** into one coherent, cloud-native platform.
 
-## Who Superphenix is for
+## Who is Superphenix for?
 
 Superphenix can be used for very different use cases:
 
@@ -54,36 +54,8 @@ Superphenix can be used for very different use cases:
 
 If your need is **independence** and **total control** of your infrastructure to do **SaaS, PaaS and IaaS**, Superphenix should cover most of your use cases. And if it doesn't, feel free to share why with us so we can improve the project!
 
-## High-level architecture
+## Do I need to know Kubernetes to install Superphenix?
 
-### Superphenix clusters
+Superphenix uses Kubernetes under the hood, but you **do not** need Kubernetes knowledge to install or run a standard deployment. 
 
-A **Superphenix cluster** is a **Kubernetes cluster** on which the Superphenix stack is deployed. The management plane discovers and operates each cluster through a **`Cluster` custom resource** that declares its **topology**, **geography**, and **connection** details.
-
-Each cluster runs in one of two **deployment topologies**:
-
-- **Hyperconverged**: storage and virtualization run on the **same** cluster—the simplest layout, typically one cluster per availability zone.
-- **Decoupled**: clusters are dedicated to either **storage** or **virtualization**; an availability zone may therefore comprise **several** Superphenix clusters (for example, one storage cluster and one or more workload clusters).
-
-Set `deploymentTopology` and, when decoupled, `type: Storage` or `type: Virtualization` on the `Cluster` resource. See [Deployment topology](architecture/deployment-topology.md) and [Configure a cluster](installation/configuring-a-cluster.md).
-
-### Availability zones (AZs)
-
-An **Availability Zone (AZ)** a logical groupment of **Kubernetes cluster** on which Superphenix is deployed. A single AZ may span **multiple datacenters** (e.g. a stretched cluster), so one AZ is a logical unit of availability, not necessarily a single physical site.
-
-In a **hyperconverged** AZ, a single cluster usually carries the full stack. In a **decoupled** AZ, multiple clusters cooperate: storage and workload tiers are separate Kubernetes clusters registered under the same availability zone, and workload clusters connect to the storage backends defined for that zone.
-
-An AZ may **span multiple nearby datacenters** (a stretched AZ) only when inter-site latency stays very low—aim for about **2 ms round-trip** or less between sites (same campus or metro). Higher latency breaks storage replication, control-plane stability, and VM networking expectations; use **separate AZs** in the same **region** instead. Assign every cluster in the AZ the same `region` and `availabilityZone` values so the console, GitOps, and disaster-recovery policies can target the zone consistently.
-
-### Regions
-
-A **region** is primarily a **label** for grouping availability zones (`region` on each `Cluster` resource); it carries no other operational meaning. AZs can be **peered** and **storage** consumed across zones **within or across regions** when sites are close enough—proximity matters, not the region label.
-
-### Central administration
-
-All AZs are administered **centrally** using:
-
-- **GitOps**: Declarative definitions (e.g. ArgoCD, Helm) deploy and update the stack and tenant resources across AZs from a single source of truth.
-- **The web console**: A multi-tenant console lets customers of the platform manage their resources over multiple AZs from one place.
-
-Together, GitOps and the console provide a single control plane over the whole deployment, while each Superphenix cluster remains an independent Kubernetes control plane for isolation and resilience.
+With that said, it isn't useless to be knowledgeable about Kubernetes. Operators who already know Kubernetes can go further: extending the platform, debugging issues, and operating Superphenix in more advanced ways.

site/architecture/deployment-topology/index.html

@@ -2023,7 +2023,7 @@ <h3 id="recommendations">Recommendations</h3>
 <li><strong>Fully decoupled</strong>: Targets <strong>multi-AZ at scale</strong>, <strong>redundancy</strong>, and <strong>shared storage</strong>: storage and hypervisor are separate, the management plane sits on a dedicated management cluster outside all workload AZs. Suited to performance-sensitive workloads, shared storage across AZs or with external systems (e.g. VMware), and operators who need a single, resilient control plane for many AZs.</li>
 </ul>
 <p><strong>Changing your deployment later:</strong> Switching between hyperconverged and decoupled (recoupling or decoupling the infrastructure) is <strong>not supported</strong>. It is theoretically possible with significant downtime and manual migration, but it is not a supported path. <strong>Moving the management plane</strong> from one cluster to another (e.g. from an AZ to a dedicated management cluster, or the reverse) <strong>is possible</strong> and can be done as an operational procedure.</p>
-<p>See the <a href="../../architecture/">Architecture overview</a> for organizations, projects, resources, and disaster recovery.</p>
+<p>See the <a href="../">Architecture overview</a> for organizations, projects, resources, and disaster recovery.</p>
 
 
 

site/architecture/index.html

@@ -413,30 +413,35 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
 
         <li class="md-nav__item">
-  <a href="#availability-zones" class="md-nav__link">
+  <a href="#superphenix-clusters" class="md-nav__link">
     <span class="md-ellipsis">
       <span class="md-typeset">
-        Availability zones
+        Superphenix clusters
       </span>
     </span>
   </a>
 
-    <nav class="md-nav" aria-label="Availability zones">
-      <ul class="md-nav__list">
-        
-          <li class="md-nav__item">
-  <a href="#geography" class="md-nav__link">
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#availability-zones" class="md-nav__link">
     <span class="md-ellipsis">
       <span class="md-typeset">
-        Geography
+        Availability zones
       </span>
     </span>
   </a>
 
 </li>
-        
-      </ul>
-    </nav>
+      
+        <li class="md-nav__item">
+  <a href="#regions" class="md-nav__link">
+    <span class="md-ellipsis">
+      <span class="md-typeset">
+        Regions
+      </span>
+    </span>
+  </a>
 
 </li>
 
@@ -1652,30 +1657,35 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
 
         <li class="md-nav__item">
-  <a href="#availability-zones" class="md-nav__link">
+  <a href="#superphenix-clusters" class="md-nav__link">
     <span class="md-ellipsis">
       <span class="md-typeset">
-        Availability zones
+        Superphenix clusters
       </span>
     </span>
   </a>
 
-    <nav class="md-nav" aria-label="Availability zones">
-      <ul class="md-nav__list">
-        
-          <li class="md-nav__item">
-  <a href="#geography" class="md-nav__link">
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#availability-zones" class="md-nav__link">
     <span class="md-ellipsis">
       <span class="md-typeset">
-        Geography
+        Availability zones
       </span>
     </span>
   </a>
 
 </li>
-        
-      </ul>
-    </nav>
+      
+        <li class="md-nav__item">
+  <a href="#regions" class="md-nav__link">
+    <span class="md-ellipsis">
+      <span class="md-typeset">
+        Regions
+      </span>
+    </span>
+  </a>
 
 </li>
 
@@ -1731,10 +1741,20 @@
 
 
 <h1 id="architecture-overview">Architecture overview</h1>
-<p>This page describes how Superphenix is organized: organizations and projects, where resources live, how availability zones (AZs) work, and how disaster recovery fits in. For how AZs and the management cluster can be deployed, see <a href="../architecture/deployment-topology/">Deployment topology</a>. For infrastructure planning details, see <a href="../architecture/deployment-requirements/">Hardware requirements</a> and <a href="../architecture/network-requirements/">Network requirements</a>.</p>
+<p>This page describes how Superphenix is organized: <strong>Superphenix clusters</strong>, how they are grouped into <strong>availability zones (AZs)</strong> and <strong>regions</strong>, tenant <strong>organizations</strong> and <strong>projects</strong>, where resources live, and how disaster recovery fits in. For deployment layouts and management placement, see <a href="../architecture/deployment-topology/">Deployment topology</a>. For infrastructure planning, see <a href="../architecture/deployment-requirements/">Hardware requirements</a> and <a href="../architecture/network-requirements/">Network requirements</a>.</p>
+<h2 id="superphenix-clusters">Superphenix clusters</h2>
+<p>A <strong>Superphenix cluster</strong> is a <strong>Kubernetes cluster</strong> (typically Talos Linux) on which the Superphenix stack runs. The management plane discovers and operates each cluster through a <strong><code>Cluster</code> custom resource</strong> that declares its <strong>topology</strong>, <strong>geography</strong>, and <strong>connection</strong> details.</p>
+<p>Each cluster uses one of two <strong>deployment topologies</strong>:</p>
+<ul>
+<li><strong>Hyperconverged</strong>: storage and virtualization on the <strong>same</strong> cluster; the simplest layout, usually one cluster per AZ.</li>
+<li><strong>Decoupled</strong>: clusters are dedicated to <strong>storage</strong> or <strong>virtualization</strong>; an AZ can therefore comprise <strong>several</strong> Superphenix clusters (for example, one storage cluster and one or more workload clusters).</li>
+</ul>
+<p>Set <code>deploymentTopology</code> and, when decoupled, <code>type: Storage</code> or <code>type: Virtualization</code> on the <code>Cluster</code> resource. See <a href="../architecture/deployment-topology/">Deployment topology</a> and <a href="../installation/configuring-a-cluster/">Configure a cluster</a>.</p>
 <h2 id="availability-zones">Availability zones</h2>
-<p>An <strong>availability zone</strong> is a <strong>Kubernetes cluster</strong> on which the full Superphenix stack is deployed: virtualization, software-defined network, storage (if not decoupled), and tooling. It is the unit of capacity and failure domain: everything running in that AZ runs on that cluster.</p>
-<h3 id="geography">Geography</h3>
+<p>An <strong>availability zone (AZ)</strong> is a <strong>logical grouping</strong> of Superphenix clusters. Clusters in an AZ are treated as one unit of capacity and failure domain for placing tenant resources (VMs, networks, volumes).</p>
+<p>In a <strong>hyperconverged</strong> AZ, a single cluster usually runs virtualization, software-defined networking, and storage together. In a <strong>decoupled</strong> AZ, storage and workload tiers are separate Kubernetes clusters registered under the same <code>availabilityZone</code>; workload clusters connect to the storage backends defined for that zone.</p>
+<p>An AZ may <strong>span multiple nearby datacenters</strong> (a stretched AZ) only when inter-site latency stays very low; aim for about <strong>2 ms round-trip</strong> or less between sites (same campus or metro). Higher latency undermines storage replication, control-plane stability, and VM networking; use <strong>separate AZs</strong> in the same <strong>region</strong> instead. Assign every cluster in the AZ the same <code>region</code> and <code>availabilityZone</code> values. See <a href="../architecture/network-requirements/#stretched-az-latency-guidance">Stretched AZ latency guidance</a>.</p>
+<h2 id="regions">Regions</h2>
 <p>An AZ can <strong>span multiple datacenters</strong> as long as latency between them is low (e.g. same campus or metro). The important constraint is <strong>network latency (ping)</strong>: if the sites are too far apart, the cluster’s consistency and performance requirements may not be met. So an AZ is a logical unit of availability that can stretch across nearby datacenters, but not across distant regions.</p>
 <h2 id="organizations-and-projects">Organizations and projects</h2>
 <p>Superphenix uses a two-level hierarchy for tenant isolation and resource grouping:</p>

site/architecture/network-requirements/index.html

@@ -1919,7 +1919,7 @@
 
 
 <h1 id="network-requirements">Network requirements</h1>
-<p>Network design for Superphenix should be planned alongside hardware sizing and AZ topology. This page defines baseline expectations for link speed, VLAN segmentation, external connectivity, and IP announcement models. For server sizing and NIC assumptions, see <a href="../deployment-requirements/">Hardware requirements</a>. For AZ design constraints, see <a href="../../architecture/">Architecture overview</a>.</p>
+<p>Network design for Superphenix should be planned alongside hardware sizing and AZ topology. This page defines baseline expectations for link speed, VLAN segmentation, external connectivity, and IP announcement models. For server sizing and NIC assumptions, see <a href="../deployment-requirements/">Hardware requirements</a>. For AZ design constraints, see <a href="../">Architecture overview</a>.</p>
 <hr />
 <h2 id="baseline-and-interface-sizing">Baseline and interface sizing</h2>
 <p>Use the NIC sizing from the <a href="../deployment-requirements/">Hardware requirements</a> as the baseline for network planning:</p>
@@ -1987,7 +1987,7 @@ <h2 id="stretched-az-latency-guidance">Stretched AZ latency guidance</h2>
 <li>Increased storage latency (for example, <strong>Ceph</strong> replication and recovery paths)</li>
 <li>Slower virtual network paths between workloads in different sites</li>
 </ul>
-<p>This aligns with the <a href="../../architecture/">Architecture overview</a>, which positions an AZ as a close geographic zone (typically same campus/metro, often on the order of a few dozen kilometers at most in best cases).</p>
+<p>This aligns with the <a href="../">Architecture overview</a>, which positions an AZ as a close geographic zone (typically same campus/metro, often on the order of a few dozen kilometers at most in best cases).</p>
 <hr />
 <h2 id="ipam-behavior-across-azs">IPAM behavior across AZs</h2>
 <p>Superphenix IPAM is scoped <strong>per availability zone (AZ)</strong>. Superphenix receives one or more IP ranges (pools) and allocates addresses from those ranges to <strong>VMs</strong>, <strong>NAT gateways</strong>, <strong>containers</strong>, and other workloads/services in that AZ. If you configure overlapping ranges in different AZs, Superphenix does <strong>not</strong> provide global deduplication across AZs for those allocations and does not guarantee non-overlap between AZs.</p>