coconews/README.md

# COCONEWS

Plataforma de inteligencia de noticias. Agrega feeds RSS de cualquier idioma, los traduce automáticamente al español, extrae entidades, los agrupa por eventos y los hace buscables semánticamente.

---

## Qué hace

- **Ingesta** feeds RSS/Atom de cualquier idioma de forma continua
- **Traduce** al español con NLLB-200 (200 idiomas soportados)
- **Extrae entidades** (personas, organizaciones, lugares) con spaCy y las enriquece con Wikipedia
- **Genera embeddings** para búsqueda por significado, no solo por palabras clave
- **Agrupa noticias** del mismo evento automáticamente
- **Categoriza** contenido con reglas y modelos de lenguaje
- Interfaz web React con búsqueda semántica, filtros y tooltips de Wikipedia

---

## Arquitectura

```
Internet (RSS/Atom)
        │
        ▼
  rss-ingestor-go ──→ PostgreSQL ──→ langdetect
        │                    │             │
   scraper/discovery         │         translator (NLLB-200)
                             │             │
                             │         embeddings (MiniLM)
                             │             │
                             │         ner (spaCy)
                             │             │
                             │         cluster / related
                             │             │
                             │         qdrant-worker ──→ Qdrant
                             │
                    backend-go (API REST :8080)
                             │
                    nginx (:8001)
                             │
                    Frontend React
```

**Stack:**
- Go 1.25 — API REST (Gin), ingestor RSS, scraper, workers
- Python 3 — Workers ML (NLLB-200, MiniLM, spaCy, CTranslate2)
- PostgreSQL 16 — datos relacionales + full-text search
- Qdrant — búsqueda vectorial semántica
- Redis 7 — caché de consultas
- React 18 + TypeScript + Tailwind — frontend
- nginx — proxy inverso + archivos estáticos

---

## Inicio rápido (POC local)

Prueba COCONEWS en tu máquina en ~2 minutos con datos de muestra, sin instalar los modelos ML.

**Requisitos mínimos para el POC:**
- Go 1.25+
- Node.js 18+
- PostgreSQL (corriendo)
- Redis (corriendo)

```bash
git clone https://gitea.laenre.net/pietre/rss2.git coconews
cd coconews
git checkout coconews

bash poc/poc.sh
```

Abre `http://127.0.0.1:18001` en el navegador.
El primer usuario que se registre será administrador.

---

## Instalación en servidor Debian

Para un despliegue completo con todos los workers ML en producción:

### 1. Instalar prerequisites

```bash
sudo bash deploy/debian/prerequisites.sh
```

Instala: PostgreSQL 16, Redis, nginx, Go 1.25, Node.js 20, Qdrant, Python 3 venv.
Pregunta si instalar los modelos ML pesados ahora o después.

### 2. Configurar entorno

```bash
cp deploy/debian/env.example /opt/rss2/.env
nano /opt/rss2/.env   # edita contraseñas y SECRET_KEY
```

### 3. Instalar y arrancar

```bash
sudo bash deploy/debian/install.sh
```

Compila los binarios Go, el frontend React, crea los servicios systemd y arranca todo.

### Acceder

```
http://IP_DEL_SERVIDOR:8001
```

Guía completa: [DEPLOY_DEBIAN.md](DEPLOY_DEBIAN.md)

---

## Gestión de servicios

```bash
# Estado general
systemctl status rss2-backend rss2-ingestor rss2-translator

# Logs en tiempo real
journalctl -u rss2-backend -f
journalctl -u rss2-translator -f

# Reiniciar tras actualizar código
git pull
sudo bash deploy/debian/build.sh
```

---

## Actualizar el código

```bash
cd /ruta/al/repo
git pull
sudo bash deploy/debian/build.sh
```

`build.sh` recompila los binarios Go, el frontend y sincroniza los workers Python, y reinicia los servicios automáticamente.

---

## Requisitos de hardware

| Modo | CPU | RAM | Disco |
|------|-----|-----|-------|
| POC local | 2 cores | 4 GB | 10 GB |
| Producción CPU | 4+ cores | 8 GB | 40 GB |
| Producción recomendado | 8 cores | 16 GB | 80 GB |

---

## Estructura del repositorio

```
├── backend/              Go — API REST + workers (scraper, discovery, wiki, topics, related, qdrant)
├── rss-ingestor-go/      Go — Ingestor de feeds RSS
├── frontend/             React + TypeScript + Tailwind
├── workers/              Python — ML workers (traducción, embeddings, NER, cluster, categorización)
├── init-db/              SQL — Schema y datos iniciales
├── migrations/           SQL — Migraciones incrementales
├── deploy/debian/        Scripts de despliegue para Debian sin Docker
│   ├── prerequisites.sh  Instala todas las dependencias del sistema
│   ├── install.sh        Instalación completa
│   ├── build.sh          Recompila y reinicia tras actualizar código
│   ├── env.example       Plantilla de variables de entorno
│   ├── nginx.conf        Configuración nginx para despliegue nativo
│   └── systemd/          Ficheros de servicio systemd (16 servicios)
├── poc/
│   ├── poc.sh            POC local con datos de prueba (sin Docker, sin ML)
│   └── seed.sql          Datos de muestra para el POC
├── feeds.csv             Feeds RSS precargados para importar desde el admin
├── entity_config.json    Aliases y blacklist para normalización de entidades NER
└── DEPLOY_DEBIAN.md      Guía detallada de despliegue en Debian
```