docs

docs/GITOPS-ARCHITECTURE.md

@@ -120,24 +120,25 @@ launchpad/
 ├── _app-of-apps-upc-prod.yaml       # Root ArgoCD Application (upc-prod cluster)
 │
 ├── infra/                            # Infrastructure ArgoCD Applications (Kustomize)
-│   ├── base/                         # Base Application manifests (upc-dev defaults)
-│   │   ├── kustomization.yaml
-│   │   ├── traefik-application.yaml
-│   │   ├── keycloak.yaml
-│   │   ├── grafana.yaml
-│   │   ├── gitea.yaml
-│   │   ├── gitea-actions.yaml
-│   │   ├── tempo.yaml
-│   │   ├── renovate.yaml
-│   │   ├── ...                       # All other Application manifests
-│   │   └── secrets.yaml
+│   ├── base/                         # Base Application manifests (one dir per component)
+│   │   ├── kustomization.yaml        # Aggregates all component subdirectories
+│   │   ├── traefik-application/
+│   │   │   ├── kustomization.yaml
+│   │   │   └── traefik-application.yaml
+│   │   ├── keycloak/
+│   │   │   ├── kustomization.yaml
+│   │   │   └── keycloak.yaml
+│   │   ├── grafana/
+│   │   ├── prometheus/
+│   │   ├── ...                       # Each component in its own subdirectory
+│   │   └── secrets/
 │   ├── overlays/                     # Per-cluster Kustomize overrides
-│   │   ├── upc-dev/                  # UpCloud Dev (uses base as-is)
-│   │   ├── upc-prod/                # UpCloud Prod (patches value paths)
+│   │   ├── upc-dev/                  # UpCloud Dev — includes all (resources: ../../base)
+│   │   ├── upc-prod/                # UpCloud Prod — all + patches
+│   │   ├── aks-dev/                 # Azure AKS Dev — selective components
+│   │   ├── aks-prod/               # Azure AKS Prod
 │   │   ├── eks-dev/                  # AWS EKS Dev
 │   │   ├── eks-prod/                # AWS EKS Prod
-│   │   ├── aks-dev/               # Azure AKS Dev
-│   │   ├── aks-prod/              # Azure AKS Prod
 │   │   ├── gke-dev/                 # GCP GKE Dev
 │   │   └── gke-prod/               # GCP GKE Prod
 │   ├── dashboards/                   # Grafana dashboard ConfigMaps
@@ -149,13 +150,17 @@ launchpad/
 │       └── gcp-{dev,prod}/           # GCP: premium-rwo, L4 LB
 │
 ├── apps/                             # Business Application ArgoCD manifests (Kustomize)
-│   ├── base/                         # Base app manifests
+│   ├── base/                         # One subdirectory per app
 │   │   ├── kustomization.yaml
-│   │   ├── dot-ai-stack.yaml
-│   │   └── ...
+│   │   ├── musicman/
+│   │   ├── mcp10x/
+│   │   ├── dot-ai-stack/
+│   │   ├── ts-mcp/
+│   │   └── argo-mcp/
 │   └── overlays/
-│       ├── upc-dev/                  # Uses base as-is
-│       └── upc-prod/                # Patches value paths
+│       ├── upc-dev/                  # All apps (resources: ../../base)
+│       ├── upc-prod/                # All apps + patches
+│       └── aks-dev/                 # Selective apps only
 │
 ├── cluster-resources/                # Cluster-wide Kubernetes resources
 │   ├── ...
@@ -171,6 +176,8 @@ launchpad/
 
 **Key Points**:
 - `_app-of-apps-upc-dev.yaml` and `_app-of-apps-upc-prod.yaml` are the per-cluster root Applications
+- Each component in `base/` has its own subdirectory with a `kustomization.yaml`
+- Overlays can include **all** components (`resources: [../../base]`) or **cherry-pick** specific ones (`resources: [../../base/grafana, ../../base/prometheus]`)
 - Kustomize overlays in `infra/overlays/` render base Applications with per-cluster patches
 - Helm values are split: `values/base/` (shared) + `values/upc-dev/` or `values/upc-prod/` (cluster-specific)
 - `apps/` follows the same base/overlays pattern for business applications
@@ -353,16 +360,30 @@ spec:
 
 ### Multi-Cluster Pattern
 
-Kustomize overlays enable deploying the same Applications across clusters with different configurations:
+Kustomize overlays enable deploying the same Applications across clusters with different configurations.
+
+Each component in `infra/base/` and `apps/base/` lives in its own subdirectory. Overlays define **which components to include** and optionally **patch** them:
 
 ```yaml
-# infra/base/ contains default (upc-dev) Applications
-# Helm values are layered: base + cluster-specific
-valueFiles:
-- $values/infra/values/base/traefik-values.yaml    # Shared config
-- $values/infra/values/upc-dev/traefik-values.yaml  # Cluster-specific
+# Option 1: Include ALL components (full cluster)
+# infra/overlays/upc-dev/kustomization.yaml
+resources:
+- ../../base                    # Pulls in every component subdirectory
 
-# infra/overlays/upc-prod/kustomization.yaml patches the second valueFile
+# Option 2: Cherry-pick specific components (lightweight cluster)
+# infra/overlays/aks-dev/kustomization.yaml
+resources:
+- ../../base/traefik-application
+- ../../base/grafana
+- ../../base/prometheus
+- ../../base/loki
+# Only listed components are deployed — others are excluded
+```
+
+Per-cluster patches swap Helm value file paths:
+
+```yaml
+# infra/overlays/upc-prod/kustomization.yaml
 patches:
 - target:
     kind: Application

docs/REFERENCE.md

@@ -76,33 +76,28 @@ launchpad/
 ├── _app-of-apps-upc-dev.yaml     # Root ArgoCD Application (upc-dev)
 ├── _app-of-apps-upc-prod.yaml    # Root ArgoCD Application (upc-prod)
 │
-├── infra/                         # Infrastructure applications
-│   ├── cluster-resources-application.yaml
-│   ├── enterprise-apps.yaml
-│   ├── traefik-application.yaml
-│   ├── cert-manager-application.yaml
-│   ├── kyverno.yaml
-│   ├── kyverno-policies.yaml
-│   ├── prometheus.yaml
-│   ├── grafana.yaml
-│   ├── loki.yaml
-│   ├── tempo.yaml
-│   ├── fluent-bit.yaml
-│   ├── gitea.yaml
-│   ├── gitea-actions.yaml
-│   ├── sealedsecrets.yaml
-│   ├── secrets.yaml
-│   ├── renovate.yaml
-│   ├── base/                      # ArgoCD Application manifests (Kustomize base)
-│   │   ├── gitea.yaml
-│   │   ├── opencost.yaml
-│   │   ├── traefik-application.yaml
-│   │   ├── keycloak.yaml
-│   │   ├── grafana.yaml
-│   │   └── ...
-│   ├── overlays/
-│   │   └── upc-prod/
-│   │       └── kustomization.yaml # Patches upc-dev → upc-prod valueFile paths
+├── infra/                         # Infrastructure applications (Kustomize)
+│   ├── base/                      # One subdirectory per component
+│   │   ├── kustomization.yaml     # Aggregates all component subdirectories
+│   │   ├── traefik-application/
+│   │   │   ├── kustomization.yaml
+│   │   │   └── traefik-application.yaml
+│   │   ├── keycloak/
+│   │   │   ├── kustomization.yaml
+│   │   │   └── keycloak.yaml
+│   │   ├── grafana/
+│   │   ├── prometheus/
+│   │   ├── loki/
+│   │   ├── tempo/
+│   │   ├── gitea/
+│   │   ├── opencost/
+│   │   ├── ...                    # Each component in own directory
+│   │   └── secrets/
+│   ├── overlays/                  # Per-cluster: include all or cherry-pick
+│   │   ├── upc-dev/              # resources: [../../base] (all components)
+│   │   ├── upc-prod/            # resources: [../../base] + patches
+│   │   ├── aks-dev/             # resources: [../../base/grafana, ...] (selective)
+│   │   └── .../                  # 8 clusters total
 │   └── values/
 │       ├── base/                   # Cloud-agnostic Helm values
 │       │   ├── gitea-values.yaml
@@ -122,11 +117,18 @@ launchpad/
 │           ├── gitea-values.yaml
 │           └── opencost-values.yaml
 │
-├── apps/                          # Business applications
-│   ├── mcp10x.yaml
-│   ├── musicman.yaml
-│   ├── dot-ai-stack.yaml
-│   └── argo-mcp.yaml
+├── apps/                          # Business applications (Kustomize)
+│   ├── base/                     # One subdirectory per app
+│   │   ├── kustomization.yaml
+│   │   ├── musicman/
+│   │   ├── mcp10x/
+│   │   ├── dot-ai-stack/
+│   │   ├── ts-mcp/
+│   │   └── argo-mcp/
+│   └── overlays/                 # Per-cluster: include all or cherry-pick
+│       ├── upc-dev/
+│       ├── upc-prod/
+│       └── aks-dev/              # Selective apps only
 │
 ├── cluster-resources/             # Cluster-level resources
 │   ├── cert-manager-namespace.yaml