# Visión general

> **TODO (fase 2+):** narrativa completa explicando cada capa del
> diagrama, con foco en el "por qué" de cada frontera de confianza. El
> diagrama de abajo es real (validado contra `docs/known-issues.md` y
> los playbooks de incidentes de `apps-registry`), pero el texto que lo
> acompaña es solo el esqueleto.

## Flujo de una petición pública

```mermaid
flowchart LR
    User(["Usuario"]) -->|HTTPS| CF["Cloudflare<br/>(DNS proxied + túnel)"]
    CF -->|HTTP/2, red host| CFD["cloudflared<br/>(app ZimaOS)"]
    CFD --> NPM["Nginx Proxy Manager<br/>192.168.68.61:90"]
    NPM --> LB["k3d-lab-cluster-serverlb<br/>(k3d-proxy, 90→80)"]
    LB --> TR["Traefik<br/>(ingress del cluster)"]
    TR -->|Host: shop.cruzcloud.net| FE["frontend-svc<br/>(Next.js)"]
    TR -->|Host: commerce.cruzcloud.net| MED["medusa-svc<br/>(Medusa API)"]
    TR -->|Host: media.cruzcloud.net| MIN["minio-svc<br/>(imágenes de producto)"]
    TR -->|Host: gitea.cruzcloud.net| GIT["Gitea"]
    TR -->|Host: docs.cruzcloud.net| DOCS["docs-portal-svc<br/>(este sitio)"]

    subgraph GitOps["Control plane GitOps"]
        ARGO["Argo CD"] -->|sync| FE
        ARGO -->|sync| MED
        ARGO -->|sync| DOCS
        GIT -.->|watch repos| ARGO
    end
```

## Componentes

| Capa | Qué es | Dónde vive |
|---|---|---|
| Cloudflare Tunnel | Expone `*.cruzcloud.net` a internet sin abrir puertos en el NAS | Fuera del cluster, app nativa ZimaOS (`cloudflared`) |
| Nginx Proxy Manager | Enruta por dominio hacia el cluster | Fuera del cluster, contenedor `nginxproxymanager` |
| k3d | Cluster Kubernetes local (multi-nodo, Docker) | Host ZimaOS |
| Traefik | Ingress controller del cluster | Dentro de k3d |
| Argo CD | Sincroniza el estado del cluster con Git (patrón App of Apps) | Namespace `argocd` |
| Gitea | Origen de verdad de los manifiestos y del código de las apps | Contenedor propio, expuesto vía túnel |

Ver también: [Red y exposición](red-y-exposicion.md) · [Flujo GitOps](gitops-flujo.md) · [Glosario](glosario.md)