Introduction to Kryptofolio
📊 Introduction to Kryptofolio
Section titled “📊 Introduction to Kryptofolio”Kryptofolio is an open-source cryptocurrency and multi-asset portfolio tracker designed to bridge the gap between lightweight consumer apps and rigorous institutional financial terminals.
Built with Vue 3, TypeScript, Hono, SQLite, and DuckDB, Kryptofolio was engineered from day one to adhere to strict Hexagonal Architecture (Ports and Adapters), uncompromising mathematical precision (zero IEEE-754 floating-point errors), and total user privacy.
🎯 The Problem with Traditional Trackers
Section titled “🎯 The Problem with Traditional Trackers”Most commercial crypto portfolio trackers, tax platforms, and generic spreadsheets present critical architectural flaws:
- Cloud-Lock & Privacy Leaks: Requiring users to upload complete transaction histories, exchange API keys, and personal wallet balances to third-party cloud servers.
- False Taxable Events: Most tax engines fail to distinguish between account transfers and actual disposals. Moving funds from Kraken to a cold-storage hardware wallet often fabricated phantom capital gains or severed lot acquisition histories.
- Floating-Point Rounding Corruption: Using standard JavaScript
Number(IEEE-754 64-bit float) causes subtle rounding degradation across high-precision crypto decimals (e.g.0.00000001 BTCor sub-cent fees). - Sluggish Relational Analytics: Performing complex historical FIFO cost-basis allocation and time-series risk metrics over thousands of transactions inside traditional row-based SQL engines leads to slow page loads and locking issues.
🏛️ How Kryptofolio Solves It
Section titled “🏛️ How Kryptofolio Solves It”Kryptofolio fundamentally rethinks personal portfolio infrastructure through four key architectural decisions:
1. Local-First & Single-User Privacy
Section titled “1. Local-First & Single-User Privacy”All transactional ledgers, credential vaults, and analytical tables live entirely on your local machine.
- No multi-tenancy overhead (
user_idis eradicated from the database model). - API keys are encrypted at rest with AES-256-GCM inside an isolated SQLite vault.
- V8 memory buffers holding sensitive credentials are explicitly zeroed out (
buffer.fill(0)).
2. Dual-Database OLTP/OLAP Engine
Section titled “2. Dual-Database OLTP/OLAP Engine”Kryptofolio implements a split database architecture:
- SQLite Ledger (
kryptofolio_ledger.db): Acts as the immutable source of transactional truth (OLTP). Transactions are deduplicated via cryptographic SHA-256 hashes (id_hash). - DuckDB Analytical Engine (
fiscal.duckdb): Vectorized columnar execution (OLAP). DuckDB attaches to SQLite via zero-copy (ATTACH ... TYPE SQLITE), computing rolling valuations, annualized volatilities, drawdowns, and FIFO lot matching via Window Functions.
3. Separation of Taxation FIFO vs. Physical Custody
Section titled “3. Separation of Taxation FIFO vs. Physical Custody”Spanish tax law (AEAT IRPF) mandates a global per-asset FIFO queue: sales must consume the oldest acquisition of an asset regardless of which account holds it.
Kryptofolio decouples this from physical custody:
- Taxation FIFO: Answers which lot does a sale consume? (Drives capital gain/loss).
- Custody Double-Entry Ledger: Answers which account holds the asset right now? (Internal transfers move lot custody without splitting lots, altering timestamps, or generating taxable events).
4. Pure Domain Precision with Branded Value Objects
Section titled “4. Pure Domain Precision with Branded Value Objects”The core domain is 100% decoupled from third-party math libraries and frameworks. Financial amounts cross boundaries strictly as branded strings:
export type PreciseAmount = string & { readonly __brand: 'PreciseAmount' };Arbitrary-precision arithmetic is cleanly encapsulated in Application and Infrastructure adapters using decimal.js and DuckDB DECIMAL(38,18).
🛠️ Technology Stack at a Glance
Section titled “🛠️ Technology Stack at a Glance”| Layer | Technologies | Architectural Role |
|---|---|---|
| Frontend UI | Vue 3 (Composition API), Pinia Colada, TailwindCSS v4, Radix-Vue | Presentation layer, reactive server-state queries, Institutional Light theme |
| Backend BFF | Hono.js, Node.js (node:sqlite) |
Dependency Injection container, Hono RPC (AppType), SSE streaming, Vault |
| Domain Layer | Pure TypeScript, Branded Types (PreciseAmount) |
Framework-agnostic business logic, Ports contracts |
| Data Integrity | Zod schemas, Anti-Corruption Layer (ACL) | Runtime validation of all external inputs and DTOs |
| Storage (OLTP) | SQLite (PRAGMA journal_mode = WAL) |
Immutable transaction ledger, audit log triggers |
| Analytics (OLAP) | DuckDB (Columnar engine, Pooled connections) | Vectorized FIFO matching, rolling metrics, ASOF joins |
| Time-Series | Apache Parquet (Hive partitioned) | Historical price and exchange rate series |
🧭 Next Steps
Section titled “🧭 Next Steps”Ready to explore? Dive into the documentation: