Kryptofolio Roadmap & Future Phases

🗺️ Kryptofolio Roadmap & Future Phases

This document details the architectural trajectory of Kryptofolio across four structured evolutionary phases, plus the AI Advisor track.

---

🏁 Phase 1: Foundation & Presentation Layer (Completed)

The foundational architecture and presentation layer are fully established:

• Monorepo Topology: PNPM Workspaces with Turborepo caching (apps/frontend, apps/backend, packages/core-domain, packages/shared-types, packages/database).
• Hexagonal Architecture: Domain logic 100% agnostic of Vue, Hono, or database libraries.
• Institutional Light Design: High-contrast palette, Inter + JetBrains Mono tabular numerals, TailwindCSS v4, and Radix-Vue.
• Asynchronous State Management: Powered by Pinia Colada for declarative query caching and optimistic mutations.
• Ingestion Wizard: Multi-step CSV/XLSX parser with exchange alias auto-mapping and Spot vs. Futures validation.
• Zero-Dependency i18n: Environment-driven internationalization supporting English and Spanish.

---

⚙️ Phase 2: Core Backend Engine & RPC (Completed)

Consolidating financial calculation logic into a centralized backend service:

• Hono.js API Server: Centralized service serving typed REST routes and mock data.
• End-to-End Type Safety: Direct export of AppType consumed via Hono RPC (hc<AppType>).
• Real-Time Market Streaming: Server-Sent Events (SSE) pipeline with transparent exchange provider hot-swapping (Kraken, Binance, CoinGecko).
• Encrypted Secrets Vault: Local AES-256-GCM vault with V8 RAM memory scrubbing (buffer.fill(0)).

---

🗄️ Phase 3: Professional Dual-Database Engine (Current Focus)

Implementing our high-performance dual-engine architecture:

• Pure Domain Conditioning: Eradicated multi-tenancy (user_id) and isolated arbitrary-precision arithmetic using PreciseAmount branded types.
• SQLite Transactional Ledger: Strict schema, cryptographic idempotency hashes (id_hash), and automated audit log triggers.
• DuckDB Vectorized OLAP Engine: Zero-copy SQLite attachment (ATTACH ... TYPE SQLITE), vectorized FIFO lot matching, and statistical risk metrics (Sharpe ratio, 30d volatility, ATH drawdown, Alpha/Beta).
• Apache Parquet Federated Storage: Hive-partitioned time-series storage (data/historical/prices/year=YYYY/month=MM).
• Materialized Freshness Service: FifoChainFreshnessService and set-reconciliation FifoMaterializerService synchronizing calculated tax lots into SQLite.
• Automated Backups & VACUUM: Automated database maintenance schedules.
• Spanish Tax Reports: Automated filing generators for AEAT Modelo 721 and regional Modelo 714.

---

🤖 AI Advisor: Shipped vs Planned

The read-only AI Portfolio Advisor (OpenSpec change add-ai-portfolio-advisor, “Phase 0”) is implemented in the codebase. See the AI Advisor overview.

Shipped

• Read-only supervisor plus taxAnalyst with 25 tools (14 exposed to local runs); investmentAnalyst declared but unreachable.
• Six providers (openai, anthropic, google, opencode, ollama, ollama-cloud) with vault-backed keys; ordered model chain with per-entry retries and fallback.
• Derived local/metered execution profiles, editable limits, character budgets, mixed-chain rule.
• Deterministic grounding, injection, and tax-evasion guardrails; structural disclaimer flag.
• SSE streaming contract, non-streaming route, typed configuration routes.
• Content-free audit table (ai_advisor_runs, migrations 009 and 010); disposable conversation memory.
• Chat panel, Settings section, English and Spanish copy.
• Twelve more read and scenario tools: holding detail, account holdings by name, tax-year comparison, data gaps, metric explanations, hypothetical position value, breakeven price, derivatives PnL, custody locations, portfolio shocks, concentration risk, and spot-transaction search. All arithmetic lives in packages/core-domain through Money.
• Tiered tool exposure: a local run sees the 14 core tools, metered and mixed runs see all 25 (static code, not a setting).
• GET /api/settings/accounts and GET /api/tax/transactions/spot now go through use cases (ListAccountsUseCase, SearchSpotTransactionsUseCase); their responses are unchanged.
• performance_history in the base currency: each point is converted at its own date’s rate; points with no rate are null, drawn as gaps in the chart and shown as “—” in the summary.

Status of the changes: add-ai-portfolio-advisor is archived (openspec/changes/archive/2026-09-30-add-ai-portfolio-advisor) and its spec deltas are merged into openspec/specs/, as is the follow-up add-ai-advisor-read-and-scenario-tools (archived 2026-10-05).

Deliberately not shipped: fees_paid and cash_flow_summary. They return once Kraken’s spottofutures subtype is declared an internal transfer, fee-asset EUR valuation exists as a use case, and explicit-zero fees survive normalization in every profile. See Tool Catalogue.

Planned, not implemented

Phase	Change id	Scope
1	add-ai-advisor-investment-analyst	Activate investmentAnalyst with price_forecast, allocation_model, market_indicators, and sale tax simulation
2	add-ai-advisor-quality-and-safety	Golden set and scorers, moderation classifier, injection detection, PII redaction for cloud
3	add-ai-advisor-contextual-insights	“Explain this number”, impact triage, pre-filing checklist, structured reports
4	add-ai-advisor-data-quality-copilot	First writes: approved, per-item fixes through existing use cases
5	add-ai-advisor-tax-knowledge-rag	Cited tax corpus, local embeddings, long-term memory

Each phase has a pre-proposal, which is context rather than a spec. Other designed but unshipped items:

• Forecast criterion settings: ai_advisor_forecast_min_hit_rate and ai_advisor_forecast_min_samples are reserved names only. Nothing in the code reads, stores, or exposes them, and there is no Settings UI.
• Remembered vault unlock: proposed as vault-remember-unlock-on-device (proposal only). Today every backend restart re-locks the vault and keyed providers are skipped.

Invariants any later phase must keep: the model never produces a number; the advisor never writes on its own; no exchange trading or order execution; tax FIFO and custody are never merged or reordered by AI-layer code; no telemetry leaves the machine. Known differences between the design and the code are tracked under Known divergences.

---

🚀 Phase 4: Advanced Capabilities (Future)

• 🤖 Broader AI Agents: the first read-only advisor already exposes existing Use Cases as LLM tools (see above). Later phases extend it with investment analysis, contextual insights, and approved writes.
• 📊 DeFi Analytics: Automated Impermanent Loss calculators for Uniswap v3/Curve liquidity pools and yield-farming tracking.
• 🐳 Native Desktop & Docker Packaging: One-click zero-touch Docker Compose configurations and lightweight Tauri native desktop builds.