CONTEXT.md

Rama main · réplica de lectura del repositorio original.

# APL Core

The platform layer that installs, configures, and reconciles all APL components on a Kubernetes cluster. It owns the values repo structure, the GitOps reconciliation loop, and the ArgoCD project model.

## Language

### GitOps

**Values repo**: The single git repository (`ENV_DIR`) that is the source of truth for all platform configuration, Helm values, and raw Kubernetes manifests. The apl-operator reads from and writes to it; ArgoCD reconciles it continuously.
_Avoid_: config repo, gitops repo, env repo

**Manifests directory**: The `env/manifests/` subtree of the values repo. The only place in the values repo where raw Kubernetes resource YAMLs live. Reconciled directly by ArgoCD, not by Helmfile.
_Avoid_: raw manifests, k8s manifests folder

**Namespace directory**: A subdirectory of `env/manifests/namespaces/` whose name matches a Kubernetes namespace. The apl-operator creates one ArgoCD Application per namespace directory that syncs its contents into that namespace.

**Global directory**: `env/manifests/global/` — contains cluster-scoped resources (CRDs, ClusterRoles). Synced by a single ArgoCD Application with no destination namespace.

**Operator-owned directory**: A namespace directory whose name starts with `apl-` and whose contents are written exclusively by the apl-operator program (e.g. `apl-secrets/`, `apl-users/`). Platform admins must not write to these.
_Avoid_: system directory, reserved directory

**Platform-admin-owned directory**: A namespace directory whose name starts with `apl-` and whose contents are written by human platform admins, not the apl-operator program. `apl-addons/` is the only current example. The operator bootstraps the directory but does not manage its contents.

### ArgoCD model

**AppProject**: An ArgoCD `AppProject` resource that scopes which source repos, destination namespaces/clusters, and Kubernetes resource types an Application is permitted to use.
_Avoid_: project, argo project

**Team project**: An AppProject named `team-{id}` scoped to a single team namespace. Generated by `charts/team-ns/templates/argocd/argocd-project.yaml`.

**apl-addons project**: The AppProject named `apl-addons` that governs Applications dropped by platform admins. Fully unrestricted: any source repo, any destination namespace, any cluster, any resource type.

**gitops-ns Application**: An ArgoCD Application named `gitops-ns-{namespace}` created by the apl-operator for each namespace directory. Syncs all manifests in that directory into the corresponding namespace with `prune: true` and `CreateNamespace: true`.
_Avoid_: parent app, bootstrap app

**App-of-Apps**: The pattern where one ArgoCD Application manages a directory of other Application CRs. The `gitops-ns-apl-addons` Application is an App-of-Apps: it syncs Application CRs into the `apl-addons` namespace, where ArgoCD picks them up via the "app in any namespace" feature.

**App in any namespace**: The ArgoCD feature (controlled by `application.namespaces` in `argocd-cm`) that allows ArgoCD to watch and reconcile Application CRs living in namespaces other than `argocd`.