Estrategia Dual-Database (OLTP/OLAP)

🗄️ Estrategia Dual-Database (OLTP/OLAP)

Criptofolio opera como una aplicación local-first y mono-usuario. Para equilibrar la necesidad de persistencia transaccional fiable con cálculos matemáticos de alta intensidad, el backend implementa una Arquitectura Dual-Database:

1. Ledger Transaccional (SQLite): Persistencia rápida con garantías ACID para transacciones, ajustes de usuario y credenciales cifradas.
2. Motor Analítico (DuckDB): Motor OLAP columnar y vectorizado para Window Functions complejas, cruces FIFO y métricas estadísticas de riesgo.
3. Almacenamiento Histórico (Apache Parquet): Almacenamiento columnar en disco para precios y tipos de cambio multianuales, particionado por año y mes con estructura Hive.

---

🏛️ Pipeline de Almacenamiento y Cálculo

flowchart TD
    subgraph DiskStorage ["Capa de Almacenamiento en Disco"]
        SQLite[("Ledger SQLite\n(criptofolio_ledger.db)")]
        Parquet[("Series Parquet\n(year=YYYY/month=MM)")]
    end

    subgraph DuckDBEngine ["Motor Analítico DuckDB (En Memoria / Archivo)"]
        ZeroCopy["ATTACH 'criptofolio_ledger.db' AS ledger\n(TYPE SQLITE)"]
        VectorChain["Cadena FIFO Derivada Vectorizada\n(m_calculated_tax_lots)"]
        MetricsViews["Vistas de Valoración y Riesgo\n(Vol 30d, Sharpe, Alpha/Beta)"]
    end

    subgraph ApplicationService ["Capa de Aplicación y Sincronización"]
        FreshnessService["FifoChainFreshnessService\n(Protocolo de Reconstrucción Coalescido)"]
        Materializer["FifoMaterializerService\n(Reconciliación de Conjuntos en SQLite)"]
        UseCases["Casos de Uso del Backend y Hono RPC"]
    end

    SQLite <--> ZeroCopy
    Parquet --> ZeroCopy
    ZeroCopy --> VectorChain
    VectorChain --> MetricsViews
    MetricsViews --> FreshnessService
    FreshnessService --> Materializer
    Materializer --> SQLite
    MetricsViews --> UseCases

---

⚙️ Cooperación entre Motores

1. Conexión Zero-Copy a SQLite

DuckDB incorpora soporte nativo para interactuar con SQLite sin duplicar información en memoria:

ATTACH 'criptofolio_ledger.db' AS ledger (TYPE SQLITE);

Esta instrucción permite a DuckDB consultar directamente los árboles B-Tree del archivo SQLite mientras ejecuta sus algoritmos SIMD sobre vectores de columnas a velocidad de memoria.

2. Protocolo de Reconstrucción y Materialización

En lugar de recalcular la cola FIFO de varios años en cada lectura HTTP, Criptofolio materializa los resultados analíticos derivados en tablas físicas (m_<name>):

1. Detección de Novedades (FifoChainFreshnessService): Supervisa si se han importado transacciones o introducido ajustes manuales en SQLite. Si el estado es reciente, las consultas de lectura responden al instante sin reprocesar.
2. Coalescencia de Peticiones: Si varias llamadas concurrentes solicitan una reconstrucción, comparten una única Promesa en curso, evitando saturar la CPU con ejecuciones duplicadas.
3. Reconciliación de Conjuntos (FifoMaterializerService): Al concluir el cálculo en DuckDB, el servicio actualiza SQLite mediante reconciliación de conjuntos (inserta lotes nuevos, actualiza lotes parcialmente consumidos y marca con borrado lógico los extinguidos), preservando la integridad del historial sin sobreescrituras destructivas.