Cómo funciona el portal
Metodología técnica
El Observatorio Cívico JEM es un sitio estático preparado para GitHub Pages. La interfaz, los datos estadísticos y el repositorio de documentos se mantienen como capas independientes.
Los Parquet de JEM Silver forman parte del propio sitio en data/jem-silver/. Hugging Face se utiliza únicamente para alojar los documentos originales.
1. Arquitectura del sitio
GitHub contiene el código, los datos del portal, los análisis y los archivos Parquet. GitHub Pages publica ese conjunto como sitio estático. No se requiere una base de datos de servidor para atender las consultas.
2. Separación de los datos
data/portal/ contiene datos de navegación y contenido; data/jem-silver/ contiene los Parquet; data/catalog/ relaciona documentos y almacenamiento; data/analysis/ conserva análisis derivados.
3. Documentos en Hugging Face
Los PDF, DOC y DOCX no se publican en GitHub Pages. Se alojan en el dataset público angatupyrytau/jem. El catálogo conserva la ruta lógica del corpus y agrega hf_path, view_url y download_url cuando la ruta remota queda confirmada.
4. Sincronización del catálogo
scripts/sync_huggingface.py consulta el árbol de archivos del dataset y compara rutas exactas. No descarga documentos y no busca coincidencias aproximadas por nombre. El resultado queda registrado en hf_snapshot.json.
5. JEM Silver dentro del sitio
Los archivos causa.parquet, document.parquet, link.parquet, party.parquet y party_conflict.parquet deben permanecer en data/jem-silver/ dentro del repositorio GitHub. No se sincronizan desde Hugging Face.
6. Estadísticas en el navegador
Estadísticas utiliza DuckDB-WASM para consultar los Parquet servidos por GitHub Pages. Al estar en el mismo sitio, las consultas no dependen de la disponibilidad o de las políticas HTTP de un almacenamiento externo.
7. Catálogo documental
documents_manifest.json es el puente entre las rutas históricas del corpus y Hugging Face. Si un mismo contenido aparece varias veces, el catálogo conserva una ruta canónica y puede registrar las demás como alias.
8. Identificación e integridad
Los documentos del inventario se identifican mediante SHA-256. El proyecto también mantiene MANIFEST.sha256 para registrar la integridad de los archivos que forman parte de una publicación del portal.
9. Relación entre Parquet y documentos
En el corpus actual, document.parquet.hf_oid contiene identificadores hexadecimales de 40 caracteres y no coincide con el SHA-256 del catálogo. Por eso el portal no asume identidad entre ambos campos. Para enlazar un resultado estadístico con su archivo original debe existir una correspondencia verificada entre el hf_oid y la ruta documental del catálogo.
10. Publicación y actualización
Antes de desplegar, GitHub Actions verifica el dataset de Hugging Face, actualiza el catálogo, comprueba que los Parquet locales estén presentes, genera el manifest de integridad y publica el sitio en GitHub Pages.
Flujo de datos
Cómo se relacionan las piezas
Documento original
El archivo se publica en Hugging Face dentro de una carpeta documental del dataset.
Verificación de ruta
El sincronizador confirma que la ruta esperada existe y genera los enlaces de visualización y descarga.
Catálogo
La relación se guarda en data/catalog/ sin modificar los Parquet originales.
JEM Silver
Los Parquet se publican directamente desde data/jem-silver/ junto con GitHub Pages.
Consulta pública
Documentos abre Hugging Face; Estadísticas consulta los Parquet locales mediante DuckDB-WASM.
Alcance técnico
Qué hace el portal y qué no hace
El portal organiza, relaciona y presenta datos. No modifica los documentos alojados en Hugging Face.
Una asociación documental indica que el sistema confirmó una ruta remota prevista. Los datos extraídos por OCR o por procesamiento automático pueden requerir verificación contra el archivo original.
Cuando una métrica no puede establecerse de forma confiable, la interfaz puede conservar valores como NO_DETERMINABLE en lugar de convertir la falta de información en cero.
Gobernanza
Reglas de uso, límites legales y cómo pedir una corrección
Este archivo trata sobre procesos disciplinarios a personas identificables. Las reglas bajo las que se publica no están sobreentendidas: están escritas.
- Marco legal (texto) — base normativa de la publicación y procedimiento de corrección y supresión.
- Alcance ético (texto) — qué se publica, qué no, y por qué.
- Licencia de derivados (texto) — condiciones propuestas de reutilización.
Pedir una corrección. Si encuentra un dato equivocado, puede abrirlo como pedido de corrección. Se responde en el mismo hilo. Si la corrección procede se aplica en la siguiente edición fechada, y la edición anterior no se borra: queda con su fecha, para que quien haya citado la cifra vieja pueda seguir el rastro.
Para máquinas
Metadatos y diccionario de datos
El portal se describe a sí mismo en formatos estándar, de modo que otro sistema pueda entender qué contiene sin leer esta página.
- Diccionario de datos (Frictionless) — las 142 columnas de las 18 tablas publicadas, con sus vocabularios controlados.
- RO-Crate — descripción del conjunto y su procedencia.
- CodeMeta y CITATION.cff — cómo citar el portal y con qué se construyó.
- Ediciones — qué contiene cada edición fechada, con el SHA-256 de cada archivo.