project-afterlife/docs/architecture-vms.md

# Arquitectura Multi-VM - Project Afterlife

## Visión General

Este documento describe la arquitectura distribuida de Project Afterlife, donde cada componente principal corre en su propia VM (máquina virtual) dedicada para maximizar aislamiento, control y escalabilidad.

```
                                    INTERNET
                                       │
                    ┌──────────────────┼──────────────────┐
                    │                  │                  │
              ┌─────▼─────┐      ┌─────▼─────┐     ┌─────▼─────┐
              │  vm-web   │      │ vm-games  │     │ vm-games  │
              │  :80/443  │      │  :ports   │     │  :ports   │
              └─────┬─────┘      └───────────┘     └───────────┘
                    │
     ┌──────────────┼──────────────┐
     │              │              │
┌────▼─────┐  ┌─────▼─────┐  ┌────▼─────┐
│ vm-auth  │  │ vm-games  │  │ vm-games │
│:9000     │  │  :ports   │  │ :ports   │
└──────────┘  └───────────┘  └──────────┘

RED PRIVADA: 10.0.0.0/24
```

---

## VMs y Sus Roles

| VM | IP Privada | Puertos Públicos | Servicios | RAM Est. |
|----|-----------|------------------|-----------|----------|
| **vm-web** | `10.0.0.10` | `80, 443` | Next.js, Strapi CMS, PostgreSQL, MinIO, Nginx, Certbot | ~1 GB |
| **vm-auth** | `10.0.0.20` | `9000` (vía proxy) | Authentik (SSO), PostgreSQL, Redis | ~1 GB |
| **vm-nier** | `10.0.0.70` | `80, 443` | NieR Reincarnation (MariesWonderland .NET 10) | ~1 GB |
| **vm-dbo** | `10.0.0.80` | `22000-22010` | Dragon Ball Online (DBO Global C++) | ~2 GB |
| **vm-maple2** | `10.0.0.40` | `20001, 21001, 20003, 21003, 4000` | MapleStory 2 (MySQL, World, Login, Game, Web) | ~2 GB |
| **vm-fusionfall** | `10.0.0.30` | `23000, 23001` | OpenFusion Server | ~512 MB |

**Soft Launch:** NieR Reincarnation, Dragon Ball Online, MapleStory 2, FusionFall

**Total RAM estimada (soft launch):** ~7.5 GB

---

## Red y Seguridad

### LAN Privada
Todas las VMs se comunican entre sí a través de una red privada dedicada (`10.0.0.0/24`). Esto permite:
- La web puede consultar el estado de los servidores de juego internamente.
- El admin panel puede conectarse a las APIs de administración de cada VM.
- **Ningún servicio interno (DB, CMS) es directamente accesible desde Internet.**

### Firewall por VM

**vm-web:**
- ALLOW IN: `80, 443` (desde anywhere)
- ALLOW IN: `22` (SSH, solo desde IP admin)
- ALLOW OUT: a `10.0.0.20:9000` (Authentik)

**vm-auth:**
- ALLOW IN: `9000` (desde `10.0.0.0/24` y redes admin)
- ALLOW IN: `22` (SSH, solo desde IP admin)
- DENY IN: `9000` desde Internet directamente (usar proxy desde vm-web si se necesita)

**vm-nier, vm-dbo, vm-maple2, vm-fusionfall:**
- ALLOW IN: puertos de juego (desde anywhere)
- ALLOW IN: `22` (SSH, solo desde IP admin)
- ALLOW IN: puertos admin/métricas (solo desde `10.0.0.20`)
- DENY everything else

---

## Autenticación Unificada (Authentik)

### Realms

| Realm | Propósito | Usuarios |
|-------|-----------|----------|
| `afterlife-players` | Login de jugadores en la web | Jugadores registrados |
| `afterlife-admins` | Panel de administración | Superadmin, Moderator, Content-Editor |

### Aplicaciones (OIDC Clients)

| Aplicación | Cliente | Callback URL |
|-----------|---------|-------------|
| Project Afterlife Web | `afterlife-web` | `https://play.consultoria-as.com/api/auth/callback/authentik` |
| Strapi CMS Admin | `afterlife-cms` | `https://play.consultoria-as.com/admin/auth/callback/authentik` |

### Flujo de Login

1. Jugador hace clic en "Iniciar sesión" en la web.
2. Redirige a Authentik (`/application/o/authorize/`).
3. Authentik autentica al usuario (email/password, social login, etc.).
4. Authentik redirige de vuelta a la web con un código de autorización.
5. La web intercambia el código por un JWT token vía `/application/o/token/`.
6. El jugador está autenticado y puede acceder a su perfil y la tienda AFC.

---

## Docker Compose por VM

Cada VM tiene su propio archivo `docker-compose.<nombre>.yml`:

```bash
# VM Web
docker compose -f docker-compose.web.yml up -d

# VM Auth
docker compose -f docker-compose.auth.yml up -d

# VM NieR Reincarnation
docker compose -f docker-compose.nier.yml up -d

# VM Dragon Ball Online
docker compose -f docker-compose.dbo.yml up -d

# VM MapleStory 2
docker compose -f docker-compose.maple2.yml up -d

# VM OpenFusion
docker compose -f docker-compose.fusionfall.yml up -d
```

---

## Despliegue por Fases

### Fase 1: Preparación
1. Crear 6 VMs con Docker y Docker Compose.
2. Configurar red privada entre VMs (VLAN o VPN WireGuard/Tailscale).
3. Asignar IPs estáticas privadas.
4. Clonar repositorio en cada VM.

**Soft Launch:** 6 VMs totales (web, auth, nier, dbo, maple2, fusionfall)

### Fase 2: VM Auth (Authentik)
1. Desplegar `docker-compose.auth.yml`.
2. Acceder a Authentik en `http://10.0.0.20:9000`.
3. Crear realms y aplicaciones OIDC.
4. Crear usuarios admin iniciales.

### Fase 3: VM Web
1. Desplegar `docker-compose.web.yml`.
2. Configurar Nginx + SSL.
3. Configurar Strapi con token API.
4. Probar que la web funciona.
5. Integrar login con Authentik.

### Fase 4: VMs de Juegos
1. Desplegar cada VM de juego una por una.
2. Ajustar variables de entorno con IPs públicas.
3. Probar conectividad desde clientes de juego.

### Fase 5: NieR Reincarnation + DBO
1. Desplegar `docker-compose.nier.yml`.
   - Colocar AssetDatabase y MasterDatabase en el volumen de datos.
   - Parchear el APK con `scripts/patcher.ipynb` (Google Colab).
2. Desplegar `docker-compose.dbo.yml`.
   - Nota: DBO Global requiere Windows. El compose actual es un placeholder.
   - Considerar VM Windows dedicada para DBO.

### Fase 6: Panel de Admin
1. Crear aplicación de admin panel.
2. Conectar con APIs de métricas de cada VM.
3. Proteger con realm `afterlife-admins`.

### Fase 7: Go-Live
1. Actualizar DNS.
2. Hacer switch de tráfico.
3. Monitorear.

---

## Troubleshooting Multi-VM

### No hay conectividad entre VMs
```bash
# Desde vm-web, probar conectividad a otras VMs
nc -zv 10.0.0.20 9000    # Authentik
nc -zv 10.0.0.70 80      # NieR Server
nc -zv 10.0.0.70 443     # NieR gRPC
nc -zv 10.0.0.80 22000   # DBO Auth
nc -zv 10.0.0.40 20001   # Maple2 Login
nc -zv 10.0.0.30 23000   # OpenFusion
```

### Authentik no responde
```bash
# En vm-auth
docker logs auth-server
docker logs auth-worker
```

### Firewall bloquea tráfico necesario
```bash
# En cualquier VM (Ubuntu/Debian con ufw)
ufw status verbose
ufw allow from 10.0.0.0/24 to any port 3001  # Ejemplo: permitir red privada
```

### Los jugadores no pueden conectar a NieR Reincarnation
Verificar que:
1. El servidor escucha en los puertos 80 y 443 correctamente.
2. `RESOURCES_BASE_URL` tiene exactamente 43 caracteres después del host.
3. El APK del cliente fue parcheado correctamente con el notebook de Google Colab.
4. La red soporta HTTP/2 para el tráfico gRPC en el puerto 443.

---

## Backups en Arquitectura Multi-VM

Cada VM debe tener su propia estrategia de backup:

| VM | Qué respaldar | Comando |
|----|--------------|---------|
| vm-web | PostgreSQL + MinIO data | `pg_dump` + `mc mirror` |
| vm-auth | Authentik PostgreSQL | `pg_dump` |
| vm-nier | AssetDatabase + MasterDatabase + UserData | `docker volume backup` |
| vm-dbo | MariaDB data | `mysqldump` |
| vm-maple2 | MySQL data | `mysqldump` |
| vm-fusionfall | SQLite + tdata | `docker volume backup` |

---

## Escalabilidad Futura

- **vm-web**: Si el tráfico crece, escalar horizontalmente con múltiples réplicas de Next.js detrás de un load balancer.
- **vm-auth**: Authentik soporta clustering para alta disponibilidad.
- **vm-maple2**: Agregar más canales de juego duplicando el servicio `maple2-game-ch*`.
- **Nueva VM de juego**: Simplemente crear una nueva VM, configurar su `docker-compose.<juego>.yml`, y registrarla en el admin panel.