Diagrama de Navegación GUI - Streamlit Pages¶

Descripción¶

Diagrama de navegación que muestra las 9 páginas de la interfaz Streamlit GUI, sus relaciones de navegación y los patrones de diseño utilizados (Template Method, Factory).

Diagrama Principal¶

flowchart TB
    subgraph Sidebar["📋 Sidebar Navigation"]
        Nav[Navigation Menu<br/>PageFactory.get_page]
    end

    subgraph Pages["📄 Pages (Template Method Pattern)"]
        Upload[UploadPage<br/>📤 Cargar PDF]
        Process[ProcessPage<br/>⚙️ Procesar OCR+NER]
        Validate[ValidatePage<br/>✅ Validar Entidades]
        Search[SearchPage<br/>🔍 Buscar Documentos]
        Duplicates[DuplicatesPage<br/>📋 Ver Duplicados]
        Stats[StatsPage<br/>📊 Dashboard]
        Detail[DetailPage<br/>📄 Detalle Documento]
        ManualEntry[ManualEntryPage<br/>✍️ Registro Manual]
        ImportExcel[ImportExcelPage<br/>📥 Importar Excel]
    end

    subgraph Components["🧩 Shared Components"]
        NERDisplay[ner_display.py<br/>Visualización entidades]
        OCRDisplay[ocr_display.py<br/>Visualización OCR]
        DupDisplay[duplicates_display.py<br/>Alertas duplicados]
        Breadcrumb[breadcrumb.py<br/>Navegación contextual]
        Validation[validation.py<br/>Validación campos]
    end

    subgraph Architecture["🏗️ Patterns"]
        PageBase[PageBase ABC<br/>Template Method]
        PageFactory[PageFactory<br/>Singleton + Factory]
    end

    Nav --> Upload & Process & Validate & Search & Duplicates & Stats & ImportExcel

    %% Detail y ManualEntry NO están en sidebar — acceso programático
    Search -->|"ver documento"| Detail
    Duplicates -->|"ver documento"| Detail

    Upload -->|"documento cargado"| Process
    Process -->|"procesado"| Validate
    Validate -->|"validado"| Detail

    PageFactory --> Upload & Process & Validate & Search & Duplicates & Stats & Detail & ManualEntry & ImportExcel
    Upload & Process & Validate & Search & Duplicates & Stats & Detail & ManualEntry & ImportExcel --> PageBase

    Process --> NERDisplay & OCRDisplay
    Validate --> NERDisplay & Validation
    Duplicates --> DupDisplay
    Detail --> Breadcrumb & NERDisplay

    style Upload fill:#e3f2fd
    style Process fill:#fff3e0
    style Validate fill:#e8f5e9
    style Search fill:#f3e5f5
    style Duplicates fill:#ffebee
    style Stats fill:#e0f7fa
    style Detail fill:#fce4ec
    style ManualEntry fill:#f1f8e9
    style ImportExcel fill:#e8eaf6

Descripción de Páginas¶

1. UploadPage (📤 Cargar PDF)¶

Responsabilidad: Carga de documentos PDF mediante drag-and-drop.

Flujo: 1. Usuario arrastra/selecciona archivo PDF 2. Validación de formato y tamaño 3. Almacenamiento temporal en data/uploads/ 4. Redirección a ProcessPage

Sesión: st.session_state.uploaded_file

2. ProcessPage (⚙️ Procesar OCR+NER)¶

Responsabilidad: Procesamiento automático del documento.

Pipeline: 1. OCR (Tesseract/PaddleOCR routing) 2. NER (SpaCy + EntityExtractorEnsemble) 3. Hashing (SHA-256) 4. Detección de duplicados 5. Persistencia en SQLite

Componentes visuales: Progress bar, OCR metrics, NER preview

3. ValidatePage (✅ Validar Entidades)¶

Responsabilidad: Validación humana de entidades extraídas.

Funcionalidades: - Edición inline de campos - Confirmación/corrección de entidades - Registro de correcciones (Active Learning) - Guardado de cambios

4. SearchPage (🔍 Buscar Documentos)¶

Responsabilidad: Búsqueda full-text en documentos.

Características: - Búsqueda FTS5 (SQLite) - Filtros por tipo, fecha, estado - Resultados paginados - Preview de coincidencias

5. DuplicatesPage (📋 Ver Duplicados)¶

Responsabilidad: Visualización de duplicados detectados.

Información mostrada: - Score de similitud (0-100%) - Método de detección - Entidades coincidentes - Comparación lado a lado

6. StatsPage (📊 Dashboard)¶

Responsabilidad: Métricas y estadísticas del sistema.

Métricas: - Total de documentos procesados - Duplicados detectados - Distribución por tipo - Timeline de procesamiento

7. DetailPage (📄 Detalle Documento)¶

Responsabilidad: Vista detallada de un documento individual.

Secciones: - Metadatos (radicado, fecha, juzgado) - Entidades extraídas - Contenido OCR - Historial de correcciones

8. ManualEntryPage (✍️ Registro Manual)¶

Responsabilidad: Registro manual de documentos sin archivo.

Campos: - Tipo de documento - Demandante/Demandado - Radicado, Juzgado - Fecha de radicación - Observaciones

9. ImportExcelPage (📥 Importar Excel)¶

Responsabilidad: Importación masiva desde archivo Excel.

Funcionalidades: - Carga de archivo .xlsx - Mapeo de columnas - Validación de datos - Importación batch - Reporte de errores

Patrones de Diseño¶

Template Method Pattern (PageBase)¶

class PageBase(ABC):
    """Clase base abstracta para todas las páginas."""

    @abstractmethod
    def render_content(self) -> None:
        """Contenido específico de la página."""
        pass

    def render(self) -> None:
        """Template method - estructura común."""
        self._scroll_to_top()
        if not self.validate_prerequisites():
            self.render_prerequisite_warning()
            return
        self.render_header()
        self._render_pending_validation_banner()  # UX-14: Banner persistente
        self.render_content()
        self.render_footer()

    def _render_pending_validation_banner(self) -> None:
        """Muestra banner si hay documento pendiente de validar.
        Solo visible en páginas distintas a 'validate'."""
        ...

Factory Pattern (PageFactory)¶

class PageFactory:
    """Factory para crear instancias de páginas."""

    _pages: Dict[str, Type[PageBase]] = {
        "upload": UploadPage,
        "process": ProcessPage,
        "validate": ValidatePage,
        "search": SearchPage,
        "duplicates": DuplicatesPage,
        "stats": StatsPage,
        "detail": DetailPage,
        "manual_entry": ManualEntryPage,
        "import_excel": ImportExcelPage,
    }

    @classmethod
    def get_page(cls, page_name: str) -> PageBase:
        """Obtiene instancia de página por nombre."""
        page_class = cls._pages.get(page_name)
        if page_class is None:
            raise ValueError(f"Página desconocida: {page_name}")
        return page_class()

Autenticación (GOB-05)¶

Antes de acceder a cualquier página, la aplicación verifica autenticación:

AUTH_ENABLED=0 (default): Bypass completo (desarrollo y tests)
AUTH_ENABLED=1: Formulario login con validación bcrypt + JWT cookie
El USERNAME autenticado se propaga a audit_events (GOB-06) y corrections.corrected_by

Flujo de Navegación Típico¶

sequenceDiagram
    participant U as Usuario
    participant S as Sidebar
    participant Up as UploadPage
    participant Pr as ProcessPage
    participant Va as ValidatePage
    participant De as DetailPage

    U->>S: Abre la aplicación
    S->>S: _check_authentication()
    alt AUTH_ENABLED=0
        S->>S: Bypass (dev/tests)
    else No autenticado
        S->>U: Formulario login
        U->>S: Credenciales
        S->>S: Validar (bcrypt + JWT cookie)
    end

    U->>S: Selecciona "Cargar"
    S->>Up: PageFactory.get_page("upload")
    Up->>Up: render()
    U->>Up: Arrastra PDF
    Up->>Pr: Redirección automática
    Pr->>Pr: Pipeline OCR+NER
    Pr->>Va: Documento procesado
    U->>Va: Corrige entidad
    Va->>Va: save_correction()
    U->>De: Click "Ver detalle"
    De->>De: render() con breadcrumb

Componentes Compartidos¶

ner_display.py¶

Visualización de entidades NER con highlighting: - Demandante (azul) - Demandado (rojo) - Radicado (verde) - Juzgado (morado) - Fecha (naranja)

duplicates_display.py¶

Componente de alerta de duplicados: - Banner de advertencia (amarillo/rojo según score) - Tabla comparativa - Botón "Ver documento original"

breadcrumb.py¶

Navegación contextual:

Inicio > Documentos > Tutela-2026-001 > Detalle

validation.py¶

Validadores de campos: - Formato de radicado (23 dígitos) - Fecha válida - Campos requeridos

Session State¶

Claves definidas en session_keys.py como constantes (SK) con schemas TypedDict:

Key	Tipo	Descripción
`current_document`	`CurrentDocument` (TypedDict)	Documento actual (id, name, type, entities, text)
`processing_result`	`ProcessDocumentResponse`	Resultado del pipeline
`uploaded_file_path`	`str`	Ruta temporal del archivo
`page`	`str`	Página actual
`detection_result`	`DuplicateDetectionResult`	Resultado detección duplicados
`ensemble_weights`	`EnsembleWeights`	Pesos NER ensemble
`USERNAME`	`str`	Username autenticado (GOB-05)
`USER_DISPLAY_NAME`	`str`	Nombre visible del operador (GOB-05)

Ver session_keys.py para el schema completo de CurrentDocument y DocumentEntities.

Leyenda de Estados¶

Símbolo	Significado
✅	Implementado y funcional
📅	Planificado para fase futura

Última actualización: 2026-03-06 (GOB-05 auth gate + session keys USERNAME/USER_DISPLAY_NAME)