# lacamposm/news-clustering architecture

> Architecture diagram of the GitHub repository lacamposm/news-clustering, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lacamposm/news-clustering
- Repository: https://github.com/lacamposm/news-clustering

## Overview

Para diseñar el diagrama de arquitectura para este proyecto de News Clustering, sigue estos pasos y recomendaciones específicas, teniendo en cuenta tanto la información del árbol de archivos como la descripción detallada en el README:

##### Componentes principales del sistema
- Data Acquisition & Preprocesamiento:
- Módulo Scraper: Basado en utils/scraper.py, responsable de extraer URLs y contenido íntegro de las noticias.
- Persistencia de datos “raw”: Archivo en el directorio data/bronze contiene datos primarios (por ejemplo, en formato parquet) obtenidos del periódico.
- Procesamiento con LLMs y Embeddings:
- Módulo LLM: utils/llms.py se encarga de generar resúmenes y generar embeddings, utilizando Ollama y los modelos sugeridos.
- Clustering & Modelado:
- La orquestación principal se encuentra en main_news.py, que llama a las funciones de scraping, resumen, embebido y posteriormente invoca técnicas de modelado y clustering.
- Módulo Model: En el paquete model se implementa la lógica de clustering (por ejemplo, validación de clusters, selección de modelos) y se pueden ver artefactos (como el archivo .joblib) relacionados con el modelo.
- Algoritmos y técnicas: Aparte de clustering (K-means, HDBSCAN) se realizan reducciones de dimensionalidad (PCA, UMAP) y visualizaciones (t-SNE, UMAP) posiblemente integradas en utils/plots.py.
- Persistencia y Almacenamiento:
- Directorio data/silver: Almacena datos intermedios o transformados, como resúmenes y versiones mejoradas de los datos generados.
- Archivos de formatos variados como .parquet y .json indican transiciones entre “bronze” (datos en bruto) y “silver” (datos procesados).

##### Relaciones e interacciones
- El flujo comienza en main_news.py, que orquesta todo el proceso.
- Primero se ejecuta el scraper para recolectar noticias, generando datos en data/bronze.
- Luego, mediante funciones en utils/llms.py, se obtienen los resúmenes y embeddings, generando nuevos archivos en data/silver.
- Posteriormente, el módulo model utiliza estos datos transformados para aplicar algoritmos de clustering, reducciones de dimensionalidad y validación de los clusters.
- Finalmente, posiblemente se generen visualizaciones y evaluaciones con utilerías en utils/plots.py y utils/custom_eval_metrics.py.

##### Patrones arquitectónicos y tecnologías
- La separación de responsabilidades es clave: cada módulo (scraper, procesador/LLM, modelado y evaluación) cumple funciones específicas.
- Se adopta un enfoque batch o en pipeline, donde la salida de cada etapa sirve de entrada para la siguiente.
- El uso de librerías de Python y herramientas como Ollama para LLMs son componentes externos críticos, por lo que en el diagrama se debe resaltar la integración con estos servicios.

##### Directrices para el diagrama
a. Divide el diagrama en “capas” o “módulos”:
- Capa de Adquisición de Datos: Representa el scraper y el almacenamiento inicial (data/bronze).
- Capa de Procesamiento & Transformación: Incluye el módulo LLM (utils/llms.py), donde se generan resúmenes y embeddings.
- Capa de Modelado y Clustering: Representa el main script (main_news.py) y el paquete model, donde se ejecutan los algoritmos de reducción de dimensionalidad y clustering.
- Capa de Persistencia y Almacenamiento: Muestra cómo se guardan los archivos intermedios en data/silver.
b. Representa las dependencias/flujo de datos:
- Usa flechas direccionales para indicar la secuencia: de la adquisición (scraper) → preprocesamiento con LLM → clustering y modelado → visualización/evaluación.
c. Incluye elementos para la integración con servicios externos:
d. Codificación de colores y formas:
- Usa colores diferentes o formas (por ejemplo, rectángulos para módulos, cilindros para bases de datos) para distinguir procesos internos, almacenamiento y dependencias externas.
e. Etiquetado claro:
- Asegúrate de nombrar cada componente (por ejemplo, “Scraper (utils/scraper.py)”, “LLM & Embeddings (utils/llms.py)”, “Clustering (model y main_news.py)”) para mayor claridad.

##### Sugerencias adicionales
- Dado que el proyecto realiza un pipeline batch de adquisición, procesamiento y análisis, asegúrate de capturar la secuencia temporal y la transformación de datos (de “bronze” a “silver”).
- Destaca que el diagrama es iterativo: cada etapa transforma y enriquece los datos brutos en insights a través de técnicas de reducción de dimensionalidad y clustering.
- Considera hacer referencias a las bibliotecas clave (por ejemplo, joblib en model para serialización del modelo, y herramientas de visualización si están implementadas) para ofrecer un contexto completo.

Resumiendo, el diagrama se estructura en:
1. Componente de extracción de datos (Scraper).
2. Componente de procesamiento (LLM para resumen y embebido).
3. Componente de modelado & clustering.
4. Almacenamiento de datos intermedios y finales.
5. Integración con servicios externos (Ollama).

Siguiendo estas instrucciones, podrás representar visualmente la arquitectura del sistema de News Clustering, facilitando la comprensión de la secuencia de operaciones y la interacción entre los diversos módulos y tecnologías empleados en el proyecto.

## Diagram (Mermaid)

```mermaid
graph TD
    Orch["Orchestration (main_news.py)"]:::orchestration

    subgraph "Capa de Adquisición"
        A1["Scraper (utils/scraper.py)"]:::acquisition
        A2(("Raw Data (Bronze)")):::storage
        A1 --> A2
    end
    Orch --> A1

    subgraph "Capa de Procesamiento & Transformación"
        P1["LLM & Embeddings (utils/llms.py)"]:::processing
        P2(("Processed Data (Silver)")):::storage
        P1 --> P2
        P1 -.->|"Ollama"| Ext["Ollama Service"]:::external
    end
    A2 --> P1

    subgraph "Capa de Modelado & Clustering"
        M1["Clustering & Modeling (model)"]:::modeling
    end
    P2 --> M1

    subgraph "Capa de Visualización & Evaluación"
        V1["Visualization (utils/plots.py)"]:::visual
        V2["Evaluation (utils/custom_eval_metrics.py)"]:::visual
        V1 --> V2
    end
    M1 --> V1

    click Orch "https://github.com/lacamposm/news-clustering/blob/main/main_news.py"
    click A1 "https://github.com/lacamposm/news-clustering/blob/main/utils/scraper.py"
    click A2 "https://github.com/lacamposm/news-clustering/tree/main/data/bronze"
    click P1 "https://github.com/lacamposm/news-clustering/blob/main/utils/llms.py"
    click P2 "https://github.com/lacamposm/news-clustering/tree/main/data/silver"
    click M1 "https://github.com/lacamposm/news-clustering/tree/main/model"
    click V1 "https://github.com/lacamposm/news-clustering/blob/main/utils/plots.py"
    click V2 "https://github.com/lacamposm/news-clustering/blob/main/utils/custom_eval_metrics.py"

    classDef orchestration fill:#D4AC0D,stroke:#873600,stroke-width:2px;
    classDef acquisition fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef processing fill:#A9DFBF,stroke:#239B56,stroke-width:2px;
    classDef storage fill:#F5CBA7,stroke:#AF601A,stroke-width:2px;
    classDef modeling fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef visual fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
```
