# programanacionalalgortimosverdes/pnav-hackathon-2 architecture

> Architecture diagram of the GitHub repository programanacionalalgortimosverdes/pnav-hackathon-2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/programanacionalalgortimosverdes/pnav-hackathon-2
- Repository: https://github.com/programanacionalalgortimosverdes/pnav-hackathon-2

## Overview

Para guiar al principal software engineer en la elaboración de un diagrama de arquitectura preciso para este repositorio de material del Hackathon, sigue estos pasos:

##### Identifica el tipo de proyecto y su propósito
- Proyecto: Repositorio de “Material para el Segundo Hackathon” (colección de guías PDF y Jupyter notebooks).
- Propósito: Proveer documentación, ejemplos de adquisición de datos, generación de datasets y notebooks de ayuda para procesos de inferencia, fine-tuning y seguimiento de consumo energético.

##### Analiza la estructura de archivos
- Top-level:
- `.gitignore`, `README.md`, `requirements.txt`, `setup.py`
- `.images/` (logos)
- `content/`
- Dentro de `content/` hay tres carpetas principales:
- `000_guides/`: PDFs con instrucciones para participantes
- `100_data/`: notebooks de adquisición y pre-procesamiento de datos
- `200_help/`: notebooks de métodos de inferencia, fine-tune, medición de huella y uso de ALIA

##### Extrae información relevante del README
- Stack tecnológico: Python 3.12, módulos listados en `requirements.txt`.
- Flujo: desde obtención de datos via APIs (Eidos, Red Natura, GeoServer) hasta generación de QA datasets, entrenamiento y evaluación con métricas de consumo (CodeCarbon) y ejemplos de uso de ALIA.

##### Los componentes principales para el diagrama
a. **Componentes internos**
- Guías (PDF) → `content/000_guides`
- Pipelines de datos (Jupyter notebooks) → `content/100_data`
- Notebooks de ayuda a ML (inferencia, fine-tune, CodeCarbon, ALIA) → `content/200_help`
- Entorno de ejecución → Python 3.12 + Jupyter
- Dependencias y scripts de instalación → `requirements.txt`, `setup.py`
b. **Componentes externos**
- APIs de datos: Eidos, Red Natura, GeoServer
- Repositorios de modelos o infraestructuras de cómputo (opcional: dónde se corre el fine-tune/inferencia)

##### Relaciona e interactúa los componentes
- Las **Guías** proveen al usuario la metodología para:
→ Ejecutar notebooks de `100_data`
→ Seguir notebooks de `200_help`
- Los notebooks de **100_data** consumen datos desde APIs externas y generan:
→ Datasets de QA (etapa intermedia)
→ Métricas de energía inicial
- Los notebooks de **200_help** toman los datasets generados y:
→ Realizan inferencia y fine-tuning (posible integración con modelos de terceros)
→ Miden consumo via CodeCarbon
→ Muestran uso de ALIA
- El **entorno Python/Jupyter** sostiene la ejecución de todos los notebooks y gestiona dependencias.

##### Señala patrones y principios arquitectónicos
- Arquitectura en *pipeline* de datos: Ingestión → Procesamiento → Entrenamiento/Evaluación
- Separación clara en carpetas por responsabilidad (guías vs. datos vs. ayudas)
- Uso de notebooks interactivas como “micro-servicios” de procesamiento (aunque todos se ejecutan en un único entorno Jupyter)

##### Recomendaciones de diseño del diagrama
- Dibuja cajas rectangulares para cada componente (Guías, Notebooks de data, Notebooks de ayuda, Entorno, APIs externas).
- Utiliza flechas direccionales para indicar flujo de datos y dependencias:
- APIs externas → Notebooks `100_data`
- Notebooks `100_data` → Datasets generados → Notebooks `200_help`
- Notebooks `200_help` → Resultados / métricas
- Azul para componentes internos (carpetas/notebooks)
- Naranja para servicios externos (APIs)
- Gris claro para artefactos estáticos (PDFs, requirements)
- Etiqueta cada flecha con el tipo de dato o acción (e.g., “GET datos”, “export QA dataset”, “medir consumo”).

##### Elementos imprescindibles en el diagrama final
- Nombres claros de cada carpeta/componente (por ejemplo: `content/100_data`)
- Direcciones de las flechas que muestren flujo de información
- Leyenda o paleta de colores para distinguir tipos de componentes
- Inclusión de tecnologías clave (Python 3.12, Jupyter, CodeCarbon, ALIA)

Con este enfoque tendrás un diagrama claro, detallado y adaptado exactamente a la naturaleza de este proyecto de hackathon, reflejando tanto la estructura de contenidos como el flujo de trabajo de extremo a extremo.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External APIs
    EidosAPI["Eidos API"]:::external
    RedAPI["Red Natura API"]:::external
    GeoAPI["GeoServer API"]:::external

    %% Static Artifacts
    subgraph "Static Resources"
        Guides["Guías (PDF)"]:::static
        Requirements["requirements.txt"]:::static
        Setup["setup.py"]:::static
    end

    %% Execution Environment
    Env["Entorno: Python 3.12 + Jupyter"]:::internal

    %% Data Pipeline Notebooks
    subgraph "Data Pipeline (content/100_data)" 
        DP["Data Pipelines"]:::internal
        EidosNB["101_api_eidos_iepnb.ipynb"]:::internal
        RedNB["102_api_red_natura_iepnb.ipynb"]:::internal
        GeoNB["103_api_geoserver.ipynb"]:::internal
        QAGen["104_generate_qa_dataset.ipynb"]:::internal
        EnergyNB["105_energy_consumption.ipynb"]:::internal
    end

    %% ML Help Notebooks
    subgraph "ML Help (content/200_help)"
        MLHelp["ML Help Notebooks"]:::internal
        InfNB["201_inferencia.ipynb"]:::internal
        FineTuneNB["202_fine_tune.ipynb"]:::internal
        CodeCarbonNB["203_codecarbon_implementation.ipynb"]:::internal
        AliaNB["204_ALIA.ipynb"]:::internal
    end

    %% Flows External -> Data Pipeline
    EidosAPI -->|"GET datos"| EidosNB
    RedAPI -->|"GET datos"| RedNB
    GeoAPI -->|"GET datos"| GeoNB

    %% Data Pipeline Flow
    EidosNB -->|"export QA dataset"| QAGen
    RedNB -->|"export QA dataset"| QAGen
    GeoNB -->|"export QA dataset"| QAGen
    EidosNB -->|"baseline energy"| EnergyNB
    RedNB -->|"baseline energy"| EnergyNB
    GeoNB -->|"baseline energy"| EnergyNB

    %% Data to ML Help
    QAGen -->|"QA dataset"| InfNB
    QAGen -->|"QA dataset"| FineTuneNB
    EnergyNB -->|"initial metrics"| CodeCarbonNB

    %% ML Help Flow
    FineTuneNB -->|"medir consumo"| CodeCarbonNB
    FineTuneNB -->|"mostrar uso ALIA"| AliaNB

    %% Guides to pipelines
    Guides -->|"metodología"| EidosNB
    Guides -->|"metodología"| InfNB

    %% Environment and Dependencies
    Requirements --> Env
    Setup --> Env
    Env --> DP
    Env --> MLHelp
    Env --> Guides

    %% Click Events
    click Guides "https://github.com/programanacionalalgortimosverdes/pnav-hackathon-2/tree/main/content/000_guides/"
    click DP "https://github.com/programanacionalalgortimosverdes/pnav-hackathon-2/tree/main/content/100_data/"
    click EidosNB "https://github.com/programanacionalalgortimosverdes/pnav-hackathon-2/blob/main/content/100_data/101_api_eidos_iepnb.ipynb"
    click RedNB "https://github.com/programanacionalalgortimosverdes/pnav-hackathon-2/blob/main/content/100_data/102_api_red_natura_iepnb.ipynb"
    click GeoNB "https://github.com/programanacionalalgortimosverdes/pnav-hackathon-2/blob/main/content/100_data/103_api_geoserver.ipynb"
    click QAGen "https://github.com/programanacionalalgortimosverdes/pnav-hackathon-2/blob/main/content/100_data/104_generate_qa_dataset.ipynb"
    click EnergyNB "https://github.com/programanacionalalgortimosverdes/pnav-hackathon-2/blob/main/content/100_data/105_energy_consumption.ipynb"
    click MLHelp "https://github.com/programanacionalalgortimosverdes/pnav-hackathon-2/tree/main/content/200_help/"
    click InfNB "https://github.com/programanacionalalgortimosverdes/pnav-hackathon-2/blob/main/content/200_help/201_inferencia.ipynb"
    click FineTuneNB "https://github.com/programanacionalalgortimosverdes/pnav-hackathon-2/blob/main/content/200_help/202_fine_tune.ipynb"
    click CodeCarbonNB "https://github.com/programanacionalalgortimosverdes/pnav-hackathon-2/blob/main/content/200_help/203_codecarbon_implementation.ipynb"
    click AliaNB "https://github.com/programanacionalalgortimosverdes/pnav-hackathon-2/blob/main/content/200_help/204_ALIA.ipynb"
    click Requirements "https://github.com/programanacionalalgortimosverdes/pnav-hackathon-2/blob/main/requirements.txt"
    click Setup "https://github.com/programanacionalalgortimosverdes/pnav-hackathon-2/blob/main/setup.py"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef static fill:#D3D3D3,stroke:#000,stroke-width:1px
```
