Arquitectura y Componentes Técnicos¶
Capas (Clean Architecture)¶
Interfaces (GUI 9 páginas + CLI 20 comandos)
↓
Application (ProcessDocument + ImportExcel + ExportExcel + ServiceContainer)
↓
Domain (Document, DocumentType, DocumentStatus, ValueObjects)
↑
Infrastructure (OCR Router, SpaCy NER, Hybrid Dedup, SQLite+FTS5)
Patrones implementados¶
| Patrón | Implementación |
|---|---|
| Ports & Adapters | OCRPort, NERPort, DuplicateDetectorPort, DocumentRepository |
| ISP | 5 protocols: Reader, Writer, Searcher, Correction, Metrics |
| ROP | returns.Result en todo el pipeline |
| Strategy | OCRRouter, NER Extractors (5) |
| Template Method | PageBase (GUI), BaseOCRAdapter |
| Factory | PageFactory (singleton) |
| DI | ServiceContainer con lazy-loading |
Pipeline de Procesamiento¶
PDF → Gate Pre-OCR (SHA-256+size) → OCR Híbrido → NER Ensemble
→ Secciones/Medida Provisional → Dedup Ensemble → BD + FTS5
Detección de Duplicados¶
Gate pre-OCR (ProcessDocumentUseCase): - SHA-256 binario + file_size → short-circuit sin OCR/NER
Ensemble post-OCR (HybridEnsembleDetector, 3 niveles): 1. MinHash LSH (peso 0.25): Jaccard por shingles 2. TF-IDF Coseno (peso 0.40): Similitud léxica 3. Entity Matching (peso 0.35): Demandante + Demandado + Cédula + Correo
Boosts: +0.20 ambas partes, +0.10 cédula, +0.05 correo.
Auto-exclusión: documento no aparece como su propio duplicado.
Pesos configurables via JSON: data/config/dedup_config.json
Extracción Híbrida PDF¶
# Paso 1: Texto nativo por página (PyMuPDF)
# Página con ≥50 chars → usar directo (confidence=0.99, engine=NATIVE)
# Página con <50 chars → marcar para OCR
# Paso 2: OCR solo para páginas sin texto nativo
# Alta calidad → Tesseract, fallback PaddleOCR si confidence <70%
# Baja calidad → PaddleOCR directo
Caché TF-IDF (CRÍTICO)¶
Sin caché: 2-5 min con 10,000 docs. Con caché: <2 seg.
# ✅ Caché incremental
cached_matrix = load_from_cache("data/cache/tfidf.pkl")
new_vector = vectorizer.transform([new_doc])
updated = vstack([cached_matrix, new_vector])
save_to_cache(updated)
Rebuild si >10% documentos nuevos. Test: test_similarity_search_under_2_seconds_with_1000_docs()
NER Ensemble¶
5 extractores (Strategy): Marker(p=1), SpaCy(p=2), Regex(p=3), Address(p=4), Contact(p=5) 4 validadores (Chain): Structural, Temporal, RadicadoFormat, Dedup F1 Global: 85.3% | Correo/Cédula: 100% | Demandante: 74%
Base de Datos¶
SQLite + FTS5 + WAL mode. 5 tablas, 33 columnas documents, 11 índices.
FK ON DELETE CASCADE en corrections y processing_stats.
Ver diagrama completo: docs/diagrams/07_database_schema.md
Diagramas¶
9 diagramas actualizados en docs/diagrams/:
01-System Context, 02-Architecture, 03-Processing Flow, 04-Dedup,
05-Classes, 06-Components, 07-DB Schema, 08-GUI Nav, 09-NER Pipeline