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.
Login: **admin** / **admin123** (creado automáticamente si tienes `pip3 install bcrypt`).

Guía detallada para explorar la demo: [docs/POC_GUIDE.md](docs/POC_GUIDE.md)

---

## 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: [docs/DEPLOY_DEBIAN.md](docs/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

```
├── README.md
├── requirements.txt           Dependencias Python para workers ML
├── Makefile                   Compilación local de binarios Go
│
├── 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 — Workers ML (traducción, embeddings, NER, cluster, categorización)
│
├── init-db/                   SQL — Schema completo y datos iniciales
├── migrations/                SQL — Migraciones incrementales
│
├── config/
│   └── entity_config.json     Aliases y blacklist para normalización de entidades NER
│
├── data/
│   └── feeds.csv              Feeds RSS precargados para importar desde el admin
│
├── docs/
│   ├── DEPLOY_DEBIAN.md       Guía detallada de despliegue en Debian
│   ├── SECURITY_GUIDE.md      Guía de seguridad
│   ├── SECURITY_AUDIT.md      Resultado del audit de seguridad
│   ├── QDRANT_SETUP.md        Configuración de Qdrant
│   └── ...                    Resto de documentación técnica
│
├── scripts/
│   ├── generate_secure_credentials.sh
│   ├── migrate_to_secure.sh
│   └── verify_security.sh
│
├── deploy/debian/             Despliegue nativo en 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
│   ├── check.sh               Diagnóstico del sistema
│   ├── env.example            Plantilla de variables de entorno
│   ├── nginx.conf             Configuración nginx
│   └── systemd/               16 ficheros de servicio systemd
│
└── poc/
    ├── poc.sh                 POC local en 2 minutos (sin Docker, sin ML)
    └── seed.sql               10 noticias de muestra en español
```