Introducción a Criptofolio

📊 Introducción a Criptofolio

Criptofolio es un gestor y analizador de carteras de criptomonedas y activos financieros diseñado para tender un puente entre las aplicaciones de consumo general y los terminales financieros institucionales más exigentes.

Construido sobre Vue 3, TypeScript, Hono, SQLite y DuckDB, Criptofolio fue concebido desde el primer día bajo los principios de Arquitectura Hexagonal estricta (Puertos y Adaptadores), máxima precisión numérica (cero errores de redondeo por IEEE-754) y privacidad absoluta para el usuario.

🎯 El Problema de los Trackers Convencionales

La inmensa mayoría de herramientas comerciales de portfolio, plataformas fiscales y hojas de cálculo convencionales sufren deficiencias estructurales graves:

Dependencia de la Nube y Fugas de Privacidad: Obligan al usuario a subir su historial completo de transacciones, claves API de exchanges y balances de billeteras a servidores de terceros en la nube.
Generación de Ganancias Fiscales Fantasmas: La mayoría de motores fiscales confunden transferencias internas entre cuentas con ventas. Mover fondos de Kraken a una billetera fría (Hardware Wallet) a menudo generaba ganancias patrimoniales ficticias o rompía la trazabilidad de los lotes de adquisición.
Corrupción por Coma Flotante: El uso de tipos primitivos como Number en JavaScript (estándar IEEE-754 de 64 bits) produce errores de redondeo progresivos al manejar decimales pequeños (0.00000001 BTC o comisiones sub-céntimo).
Rendimiento Pobre en Analítica Relacional: Ejecutar cálculos históricos de asignación FIFO y métricas temporales de riesgo sobre miles de transacciones dentro de bases de datos relacionales tradicionales provoca bloqueos y tiempos de respuesta lentos.

🏛️ Cómo lo Resuelve Criptofolio

Criptofolio replantea por completo la infraestructura de seguimiento patrimonial mediante cuatro decisiones arquitectónicas clave:

1. Privacidad Local-First y Mono-Usuario

Tanto los ledgers transaccionales como la bóveda de credenciales y las tablas analíticas residen íntegramente en tu propia máquina.

Eliminación de la sobrecarga de multi-inquilino (no existe user_id en el modelo de base de datos).
Claves de API cifradas en reposo con AES-256-GCM en una base de datos SQLite aislada.
Los buffers de memoria en V8 que contienen credenciales sensibles se sobrescriben explícitamente con ceros (buffer.fill(0)).

2. Motor Dual-Database (OLTP/OLAP)

Criptofolio divide su arquitectura de persistencia en dos motores especializados:

Ledger Transaccional SQLite (criptofolio_ledger.db): Fuente inmutable de verdad transaccional (OLTP). Las operaciones se deduplican mediante hashes criptográficos SHA-256 (id_hash).
Motor Analítico DuckDB (fiscal.duckdb): Ejecución columnar vectorizada (OLAP). DuckDB se conecta a SQLite con copia cero (ATTACH ... TYPE SQLITE), calculando valoraciones históricas, volatilidades anualizadas, caídas máximas (Drawdown) y cruces de lotes FIFO mediante Window Functions.

3. Separación de FIFO Fiscal frente a Custodia Física

La normativa española de la AEAT (IRPF) exige un criterio FIFO global por activo: una venta debe consumir el lote más antiguo de ese activo independientemente de la cuenta o billetera desde la que se venda.

Criptofolio desacopla este cálculo de la custodia física:

FIFO Fiscal: Responde a ¿qué lote consume una venta? (determina la ganancia o pérdida patrimonial).
Ledger de Custodia por Partida Doble: Responde a ¿dónde está la cantidad física del activo ahora mismo? (las transferencias internas mueven la custodia sin fragmentar lotes, sin alterar marcas temporales y sin crear hechos imponibles).

4. Precisión Absoluta en el Dominio con Branded Types

El núcleo del dominio está totalmente aislado de librerías externas y frameworks. Las cantidades monetarias cruzan las fronteras de la aplicación estrictamente como cadenas tipadas:

export type PreciseAmount = string & { readonly __brand: 'PreciseAmount' };

La aritmética de precisión arbitraria se confina limpiamente a los adaptadores de infraestructura mediante decimal.js y DECIMAL(38,18) en DuckDB.

🛠️ Stack Tecnológico en Resumen

Capa	Tecnologías	Rol Arquitectónico
Frontend UI	Vue 3 (Composition API), Pinia Colada, TailwindCSS v4, Radix-Vue	Capa de presentación reactiva, consultas asíncronas de servidor, tema Institucional Claro
Backend BFF	Hono.js, Node.js (`node:sqlite`)	Contenedor de Inyección de Dependencias, Hono RPC (`AppType`), streaming SSE, Bóveda
Capa de Dominio	TypeScript puro, Branded Types (`PreciseAmount`)	Lógica de negocio agnóstica de frameworks, contratos de Puertos
Integridad de Datos	Schemas Zod, Anti-Corruption Layer (ACL)	Validación estricta en tiempo de ejecución de DTOs externos
Persistencia (OLTP)	SQLite (`PRAGMA journal_mode = WAL`)	Ledger transaccional inmutable con triggers de auditoría
Analítica (OLAP)	DuckDB (Motor columnar con pool de conexiones)	Asignación FIFO vectorizada, métricas móviles, ASOF joins
Series Temporales	Apache Parquet (Particionado Hive)	Series históricas de precios y tipos de cambio