From a59406c39ef38b460bb8cf943fa068d575e9e260 Mon Sep 17 00:00:00 2001 From: CAPITANSITO Date: Tue, 31 Mar 2026 14:13:25 +0200 Subject: [PATCH] Add comprehensive README and .env.example with setup instructions --- .env.example | 6 ++ README.md | 230 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 236 insertions(+) create mode 100644 .env.example create mode 100644 README.md diff --git a/.env.example b/.env.example new file mode 100644 index 00000000..77cdee90 --- /dev/null +++ b/.env.example @@ -0,0 +1,6 @@ +# Conexión a MongoDB +MONGO_URL=mongodb://localhost:27017 +DB_NAME=FLUJOS_DATOS + +# Puerto del servidor Node.js +PORT=3000 diff --git a/README.md b/README.md new file mode 100644 index 00000000..e1d62f2c --- /dev/null +++ b/README.md @@ -0,0 +1,230 @@ +# FLUJOS + +Plataforma de análisis y visualización de flujos de información. Conecta noticias, documentos y eventos históricos para entender la historia como una sucesión de eventos y combatir la desinformación. + +--- + +## Arquitectura + +``` +flujos/ +├── FLUJOS/ # Aplicación principal (Node.js + Python) +│ ├── BACK_BACK/ # Servidor Express + Flask API + módulo OBSEI +│ └── VISUALIZACION/ # Frontend (Three.js, force-graph, GraphQL) +└── FLUJOS_DATOS/ # Pipeline de datos + ├── FLUJOS_DATOS/ # Proyecto Django + scrapers + modelos Keras + ├── NOTICIAS/ # Scraper y procesador de noticias + ├── WIKIPEDIA/ # Extracción de artículos de Wikipedia + ├── TORRENTS/ # Procesamiento de documentos WikiLeaks + ├── COMPARACIONES/ # Scripts de comparación y similitud + └── SCRIPTS/ # Utilidades varias +``` + +--- + +## Requisitos previos + +### Sistema +- **Node.js** >= 18.x +- **Python** >= 3.11 +- **MongoDB** >= 6.x (corriendo en local o servidor remoto) +- **Elasticsearch** >= 8.x (opcional, para búsqueda avanzada) + +### Instalación de MongoDB (Ubuntu/Debian) +```bash +# Importar clave GPG +curl -fsSL https://pgp.mongodb.com/server-6.0.asc | sudo gpg -o /usr/share/keyrings/mongodb-server-6.0.gpg --dearmor + +# Añadir repositorio +echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-6.0.gpg ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list + +# Instalar +sudo apt update && sudo apt install -y mongodb-org + +# Arrancar +sudo systemctl start mongod && sudo systemctl enable mongod +``` + +--- + +## Instalación + +### 1. Clonar el repositorio + +```bash +git clone https://gitea.laenre.net/hacklab/FLUJOS.git +cd FLUJOS +git checkout production +``` + +### 2. Variables de entorno + +```bash +cp .env.example FLUJOS/BACK_BACK/.env +``` + +Edita el archivo `.env` con tus valores: + +| Variable | Descripción | Valor por defecto | +|-------------|------------------------------------|-------------------------------| +| `MONGO_URL` | URL de conexión a MongoDB | `mongodb://localhost:27017` | +| `DB_NAME` | Nombre de la base de datos | `FLUJOS_DATOS` | +| `PORT` | Puerto del servidor Node.js | `3000` | + +### 3. Instalar dependencias Node.js + +```bash +# Dependencias del servidor principal +cd FLUJOS/BACK_BACK +npm install + +# Dependencias del frontend +cd ../VISUALIZACION +npm install +``` + +### 4. Entorno virtual Python + +```bash +cd ../../FLUJOS_DATOS +python3 -m venv myenv +source myenv/bin/activate +``` + +### 5. Instalar dependencias Python + +```bash +# Dependencias del pipeline de datos +pip install transformers==4.10.0 tensorflow==2.17.0 scikit-learn==0.24.2 \ + pandas==1.3.2 numpy==1.19.5 elasticsearch==7.13.4 nltk==3.6.2 + +# Módulo OBSEI (análisis y clasificación) +pip install obsei[all] + +# Dependencias Django +cd FLUJOS_DATOS +pip install django +``` + +### 6. Migraciones Django (base de datos SQLite auxiliar) + +```bash +cd FLUJOS_DATOS +python manage.py migrate +``` + +--- + +## Base de datos MongoDB + +La aplicación principal lee de la base de datos `FLUJOS_DATOS` en MongoDB. Las colecciones necesarias son: + +### Colecciones + +| Colección | Descripción | +|-----------------|--------------------------------------------------| +| `wikipedia` | Artículos de Wikipedia procesados y tokenizados | +| `noticias` | Noticias escrapeadas y procesadas | +| `torrents` | Documentos de WikiLeaks procesados | +| `comparaciones` | Relaciones de similitud entre documentos | + +### Esquema de documentos (`wikipedia`, `noticias`, `torrents`) + +```json +{ + "archivo": "nombre_del_archivo.txt", + "tema": "tema principal", + "subtema": "subtematica", + "texto": "contenido del documento...", + "fecha": "2024-01-15T00:00:00Z" +} +``` + +### Esquema de `comparaciones` + +```json +{ + "noticia1": "nombre_archivo_1.txt", + "noticia2": "nombre_archivo_2.txt", + "porcentaje_similitud": 0.87 +} +``` + +> **Nota:** Las colecciones se pueblan ejecutando los scripts del pipeline de datos (ver sección siguiente). Los datos en bruto (archivos descargados) no están incluidos en el repositorio por su tamaño. + +--- + +## Pipeline de datos + +Los scripts se ejecutan en este orden para poblar la base de datos: + +``` +1. Scraping → FLUJOS_DATOS/NOTICIAS/main_noticias.py + FLUJOS_DATOS/WIKIPEDIA/main.py + FLUJOS_DATOS/TORRENTS/procesar_torrents.py + +2. Procesamiento → FLUJOS_DATOS/FLUJOS_DATOS/FLUJOS_DATOS/DATA/scraper.py + FLUJOS_DATOS/FLUJOS_DATOS/FLUJOS_DATOS/DATA/guarda_csv.py + +3. Modelos Keras → FLUJOS_DATOS/FLUJOS_DATOS/FLUJOS_DATOS/KERAS/train_model.py + +4. Comparaciones → FLUJOS_DATOS/COMPARACIONES/pipeline_completo.py +``` + +> Consulta `FLUJOS_DATOS/DOCS/LEEME.txt` y `FLUJOS_DATOS/DOCS/comandos_clave.txt` para más detalle sobre cada paso. + +--- + +## Arrancar la aplicación + +### Servidor principal (Node.js) + +```bash +cd FLUJOS/BACK_BACK +npm start +# o en desarrollo: +npm run dev +``` + +La aplicación estará disponible en `http://localhost:3000` + +### API Flask (análisis con TensorFlow) + +```bash +cd FLUJOS/BACK_BACK +source ../../FLUJOS_DATOS/myenv/bin/activate +python flask_api/app.py +``` + +--- + +## Estructura de la API + +| Endpoint | Método | Descripción | +|--------------|--------|-----------------------------------------------------| +| `/` | GET | Página principal | +| `/api/data` | GET | Devuelve nodos y enlaces para visualización | + +### Parámetros de `/api/data` + +| Parámetro | Tipo | Requerido | Descripción | +|---------------|--------|-----------|----------------------------------------------| +| `tema` | string | Sí | Tema principal a consultar | +| `subtematica` | string | No | Filtro por subtema | +| `palabraClave`| string | No | Búsqueda por texto libre | +| `fechaInicio` | date | No | Filtro fecha inicio (ISO 8601) | +| `fechaFin` | date | No | Filtro fecha fin (ISO 8601) | +| `nodos` | int | No | Límite de nodos (máx. 500, por defecto 100) | +| `complejidad` | float | No | % mínimo de similitud entre nodos (0-100) | + +--- + +## Contribuir + +1. Haz fork del repositorio en `gitea.laenre.net/hacklab/FLUJOS` +2. Crea una rama desde `production` +3. Haz tus cambios y abre un Pull Request + +--- + +*"Los gigantes vistos en perspectiva parecen marionetas."*