# Qué es cada pieza del sistema y para qué sirve

Una guía rápida para entender por qué existe cada tecnología y qué pasaría si no la tuvieras.

---

## Astro

**¿Qué es?**
Un framework para construir sitios web. Genera HTML estático a partir de componentes y archivos Markdown/MDX.

**¿Para qué lo usamos?**
Es la web pública `carlospalanca.es`. Sirve el blog, los artículos y el contenido del canal.

**¿Por qué Astro y no WordPress/otro?**
- El output es HTML puro — se sirve desde nginx sin ningún proceso Node corriendo en el servidor
- Los agentes pueden crear contenido nuevo simplemente añadiendo archivos `.md` vía Pull Request
- Muy rápido y barato de hostear (solo archivos estáticos)

**¿Qué pasaría sin él?**
No tendrías web donde publicar el contenido que generan los agentes.

---

## GitHub

**¿Qué es?**
Plataforma de control de versiones y colaboración de código.

**¿Para qué lo usamos?**
- Almacena todo el código del proyecto
- Es donde los agentes crean Pull Requests con contenido nuevo
- Es el punto de partida del pipeline de despliegue (push a main → web actualizada)
- Sirve como historial y trazabilidad de todo lo que hacen los agentes

**¿Por qué es la "fuente de verdad"?**
Porque todo cambio pasa por aquí: el agente crea la rama, tú revisas el PR, lo mergeas, y la web se actualiza sola. Nada llega a producción sin pasar por GitHub.

**Fine-Grained PAT (token de GitHub):**
Es una llave con permisos muy limitados que usan los agentes para crear ramas y PRs. Al tener scope mínimo (solo este repo, solo contents + pull_requests), aunque un agente se comporte mal no puede tocar nada fuera de su scope.

**¿Qué pasaría sin él?**
Los agentes no tendrían dónde guardar el contenido que generan ni forma de enviártelo para revisión.

---

## GitHub Actions

**¿Qué es?**
El sistema de automatización de GitHub. Ejecuta scripts automáticamente cuando ocurren eventos (push, PR, merge).

**¿Para qué lo usamos?**
Dos workflows:

| Workflow | Cuándo se ejecuta | Qué hace |
|----------|------------------|----------|
| `ci.yml` | En cada PR | Construye el sitio y comenta si el build pasa o falla |
| `deploy.yml` | Al mergear a main | Construye el sitio y lo sube al VPS via rsync |

**¿Por qué es importante el CI en los PRs?**
Cuando Samwell crea un PR con un artículo de blog, puede tener un error en el frontmatter (YAML mal escrito, campo que falta) que rompa el build. El CI lo detecta antes de que llegue a producción y te lo avisa con un comentario en el PR.

**¿Qué pasaría sin él?**
Tendrías que hacer el build y el deploy manualmente cada vez, y podrías subir contenido roto a producción sin saberlo.

---

## VPS (Servidor Virtual Privado)

**¿Qué es?**
Un servidor Linux en la nube que está encendido 24/7 y es accesible desde internet.

**¿Para qué lo usamos?**
- Sirve la web estática de Astro (via nginx)
- Corre OpenWebUI (el gateway de los LLMs)
- Corre los 9 Discord bots (via Docker)

**¿Por qué no usar Vercel/Netlify para la web y nada más?**
Porque también necesitas hostear OpenWebUI y los 9 bots, que son procesos Docker de larga duración. Vercel solo sirve para webs estáticas. Con un VPS tienes todo en un sitio.

**¿Qué pasaría sin él?**
No tendrías dónde correr los bots ni OpenWebUI.

---

## nginx

**¿Qué es?**
Un servidor web y proxy inverso. Recibe las peticiones HTTP/HTTPS y las dirige al sitio correcto.

**¿Para qué lo usamos?**
Dos funciones en este proyecto:

1. **Servir la web:** cuando alguien abre `carlospalanca.es`, nginx lee los archivos de `/var/www/carlospalanca.es/` y los devuelve.
2. **Proxy a OpenWebUI:** cuando alguien abre `ai.carlospalanca.es`, nginx redirige la petición a `localhost:3000` donde corre OpenWebUI — sin exponer el puerto directamente a internet.

**¿Por qué no exponer OpenWebUI directamente en el puerto 3000?**
Porque nginx gestiona el SSL (HTTPS). Sin nginx, OpenWebUI estaría en `http://` sin cifrado. También permite tener múltiples servicios en el mismo servidor con distintos dominios.

**¿Qué pasaría sin él?**
La web no sería accesible y OpenWebUI no tendría HTTPS.

---

## Let's Encrypt / Certbot

**¿Qué es?**
Un servicio gratuito que emite certificados SSL. Certbot es la herramienta que los instala y renueva automáticamente.

**¿Para qué lo usamos?**
Para que la web use HTTPS (`https://carlospalanca.es`) en lugar de HTTP sin cifrado. Sin certificado, los navegadores muestran "Conexión no segura".

**¿Qué pasaría sin él?**
La web funcionaría solo en HTTP. Nadie confiaría en ella y Google la penalizaría en SEO.

---

## Docker y Docker Compose

**¿Qué es?**
Docker empaqueta aplicaciones en contenedores — entornos aislados con todo lo que necesitan para funcionar. Docker Compose orquesta múltiples contenedores.

**¿Para qué lo usamos?**
- Cada Discord bot es un contenedor Docker separado
- OpenWebUI corre como contenedor Docker
- Esto significa que puedes levantar los 9 bots con un solo comando: `docker compose up -d`

**Ventajas:**
- Si un bot falla, no afecta a los demás
- `restart: unless-stopped` los reinicia automáticamente si crashean
- Fácil de actualizar: `docker compose build && docker compose up -d`
- El entorno es idéntico en tu máquina y en el VPS

**¿Qué pasaría sin él?**
Tendrías que instalar Python, dependencias y gestionar 9 procesos manualmente en el VPS. Docker lo simplifica enormemente.

---

## OpenWebUI

**¿Qué es?**
Una interfaz web open-source para interactuar con modelos de lenguaje (LLMs). Tiene una API compatible con el formato de OpenAI.

**¿Para qué lo usamos?**
Es el **gateway centralizado de LLM**. Los 9 bots no llaman directamente a OpenAI o Anthropic — llaman a OpenWebUI, que a su vez llama al proveedor.

**¿Por qué este intermediario?**
| Sin OpenWebUI | Con OpenWebUI |
|---------------|---------------|
| Cambiar de GPT-4o a Claude requiere editar el código de los 9 bots y redeployar | Cambias `OPENWEBUI_MODEL=claude-3-5-sonnet` en `.env` y reinicias |
| No tienes visibilidad del consumo de tokens por agente | Dashboard web con historial de conversaciones y uso |
| No puedes chatear manualmente con los modelos | Tienes una UI en `ai.carlospalanca.es` para uso personal |

**¿Qué pasaría sin él?**
Seguiría funcionando si llamas directamente a la API de OpenAI, pero perderías la flexibilidad de cambiar de modelo y el dashboard de control.

---

## Discord

**¿Qué es?**
Plataforma de mensajería con soporte para bots programables.

**¿Para qué lo usamos?**
Es la **interfaz de control del sistema**. En lugar de tener una web especial para hablar con los agentes, usas Discord. Cada agente tiene su propio canal.

**¿Por qué Discord y no Telegram, Slack u otro?**
- Permite múltiples bots con identidades visuales separadas (cada bot tiene su nombre y avatar)
- Tyrion aparece como "Tyrion Lannister", Samwell como "Samwell Tarly", etc.
- Los canales organizan las conversaciones por agente de forma natural
- Gratis para este uso

**¿Por qué 9 aplicaciones Discord separadas y no una sola?**
Porque si fuera un solo bot, todos los mensajes aparecerían del mismo bot. Así cada agente tiene su propia identidad visual en Discord, lo que hace mucho más claro quién está haciendo qué.

**¿Qué pasaría sin él?**
Necesitarías otra interfaz para dar instrucciones a los agentes (una web propia, Telegram, etc.).

---

## discord.py

**¿Qué es?**
Librería de Python para crear bots de Discord.

**¿Para qué lo usamos?**
Es el núcleo de cada agente. Gestiona la conexión con Discord, escucha mensajes en el canal asignado y envía respuestas.

**¿Qué pasaría sin él?**
Habría que usar la API de Discord directamente con HTTP puro, mucho más complejo.

---

## PyGithub

**¿Qué es?**
Librería de Python que envuelve la API REST de GitHub.

**¿Para qué lo usamos?**
En `agents/shared/github_client.py` para crear ramas, hacer commits y abrir Pull Requests desde Python con pocas líneas de código.

**¿Qué pasaría sin él?**
Habría que hacer las llamadas HTTP a la API de GitHub manualmente.

---

## Resumen visual

```
TÚ (Carlos)
  │
  │ escribes en
  ▼
Discord ──────────────────────────────────────────────────────┐
  │                                                           │
  │ discord.py escucha                                        │
  ▼                                                           │
9 Bots Python (Docker en VPS)                                 │
  │                                                           │
  │ llaman vía HTTP                                           │
  ▼                                                           │
OpenWebUI (Docker en VPS, detrás de nginx con HTTPS)          │
  │                                                           │
  │ llama a                                                   │
  ▼                                                           │
OpenAI / Anthropic / Ollama (LLM)                             │
  │                                                           │
  │ respuesta                                                 │
  ▼                                                           │
Bot crea PR con PyGithub                                       │
  │                                                           │
  ▼                                                           │
GitHub ◄──────────────────── tú revisas y mergeas ────────────┘
  │
  │ merge a main dispara
  ▼
GitHub Actions
  │
  │ build + rsync
  ▼
VPS (/var/www/carlospalanca.es/) ◄── nginx sirve
  │
  ▼
https://carlospalanca.es (web pública con Let's Encrypt)
```