Visión General
El Extractor de Normas BCN está diseñado como un sistema modular que sigue el patrón ELT (Extract, Load, Transform) para procesamiento de datos legales.
Principios de Diseño
- Modularidad: Componentes independientes y reutilizables
- Escalabilidad: Diseño preparado para grandes volúmenes de datos
- Resiliencia: Manejo robusto de errores y reintentos automáticos
- Trazabilidad: Logging completo de todas las operaciones
- Reproducibilidad: Docker para entornos consistentes
Diagrama de Arquitectura
┌───────────────────────────────────────────────────────────┐
│ USUARIO │
└────────────────────────────┬──────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────┐
│ INTERFACES DE USUARIO │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ CLI App │ │ REST API │ │ Web UI (*) │ │
│ │ (bcn_cli) │ │ (FastAPI) │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└────────────────────────────┬──────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────┐
│ PYTHON APPLICATION │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ BCN Client │ │ XML Parser │ │ Managers │ │
│ │ (HTTP) │→ │ (lxml) │→ │ (Database) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────┬─────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────┐
│ POSTGRESQL DATABASE │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Normas │ │Instituciones │ │Tipos Normas │ │
│ │ │ │ │ │ │ │
│ │ (+ FTS) │ │ │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────┬─────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────┐
│ DOCKER VOLUMES │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ PostgreSQL │ │ XML Files │ │
│ │ Data │ │ (backup) │ │
│ └──────────────┘ └──────────────┘ │
└───────────────────────────────────────────────────────────┘
(*) En roadmapComponentes Principales
BCN Client
Módulo HTTP para interactuar con los servicios web de la Biblioteca del Congreso Nacional.
bcn_client.py XML Parser
Procesador de documentos XML que extrae metadatos y convierte contenido a Markdown.
utils/norm_parser.py Database Managers
Capa de abstracción para operaciones de base de datos.
NormsManager
Gestión completa de normas legales
InstitutionManager
CRUD de instituciones
TiposNormasManager
Catálogo de tipos de normas
CLI Interface
Interfaz de línea de comandos para gestionar el sistema.
bcn_cli.py REST API
API REST construida con FastAPI para consultas programáticas.
api.py Flujo de Datos
El proceso de extracción de normas sigue este flujo:
Solicitud de Normas
El usuario ejecuta bcn_cli.py sync <institucion_id>
Consulta a la API BCN
BCN Client construye la URL y realiza la petición HTTP al servicio web
Descarga de XML
Se descargan los XMLs individuales de cada norma y se guardan en data/xml/
Parseo y Transformación
XML Parser extrae metadatos, genera hash MD5, y convierte a Markdown
Almacenamiento
NormsManager inserta/actualiza los datos en PostgreSQL usando upsert
Logging
Se registra el resultado de la operación en la tabla descargas
Patrones de Diseño Utilizados
Repository Pattern
Los Managers actúan como repositorios que abstraen el acceso a datos
Dependency Injection
Las conexiones de base de datos se inyectan en los managers
Singleton
El logger y el cliente HTTP se instancian una sola vez
Template Method
El flujo de sincronización define pasos que pueden personalizarse