Backend Architecture & Hono RPC

⚙️ Backend Architecture & Hono RPC

The Kryptofolio backend (apps/backend) is a centralized, lightweight, and ultra-fast service built on Hono.js.

It acts as the single source of truth for:

1. REST API endpoints consumed by the Vue 3 frontend.
2. End-to-end type safety via Hono RPC without code-generation steps.
3. Encrypted API credentials storage (Vault).
4. Analytical execution coordination between SQLite and DuckDB.

---

🏛️ Server Layout & Separation of Concerns

The backend is cleanly separated into two distinct entry points:

apps/backend/src/
├── app.ts                 # Pure Hono app: middlewares, routing, and AppType export
├── index.ts               # Bootstrapper: DB connection pooling, job triggers, port binding
├── core/
│   ├── domain/            # Domain models and interfaces
│   ├── application/       # Use Cases (e.g. UnlockVaultUseCase, IngestTransactionsUseCase)
│   └── infrastructure/
│       ├── di/container.ts# Centralized Dependency Injection Composition Root
│       ├── adapters/      # SQLite & DuckDB engine adapters
│       ├── routes/        # Modular Hono route definitions
│       └── jobs/          # Scheduled background tasks (e.g. ExchangeRateSyncJob)

• app.ts (Pure Application): Defines route paths, sets up CORS, logger middlewares, and exports the AppType. It contains no network listening logic, making it effortlessly testable with app.request().
• index.ts (Runtime Bootstrapper): Initializes database files, runs schema migrations, verifies environment variables, and starts the Node.js HTTP server.

---

🔗 End-to-End Type Safety (Hono RPC)

Traditional architectures often require running heavy OpenAPI/Swagger code generators (like openapi-typescript-codegen or GraphQL codegen) whenever an endpoint changes.

Kryptofolio leverages Hono RPC, sharing TypeScript types directly across monorepo boundaries with zero build-step overhead:

1. Backend Route Definition & Export (apps/backend/src/app.ts)

import { Hono } from 'hono';
import { metricsRoutes } from './core/infrastructure/routes/metrics';
import { taxRoutes } from './core/infrastructure/routes/tax';
import { vaultRoutes } from './core/infrastructure/routes/vault';

const routes = new Hono()
  .route('/api/metrics', metricsRoutes)
  .route('/api/tax', taxRoutes)
  .route('/api/credentials', vaultRoutes);

export const app = new Hono().route('/', routes);
export type AppType = typeof routes;

2. Frontend Consumption (apps/frontend/.../BffClient.ts)

The frontend initializes the RPC client importing only the AppType type definition:

import { hc } from 'hono/client';
import type { AppType } from '@kryptofolio/backend';

export const bffClient = hc<AppType>(import.meta.env.VITE_API_URL || 'http://localhost:3001');

// Full autocomplete, argument validation, and return typing:
const response = await bffClient.api.metrics.kpis.$get();
if (response.ok) {
  const data = await response.json(); // Data is strictly typed!
  console.log(data.total_equity);
}

---

🔌 Centralized Dependency Injection (container.ts)

The backend routes do not instantiate services directly. A centralized DI container resolves concrete adapters and injects them into Use Cases:

apps/backend/src/core/infrastructure/di/container.ts

export interface Container {
  sqliteLedgerAdapter: SqliteLedgerAdapter;
  duckDbAdapter: DuckDbAdapter;
  fifoMaterializerService: FifoMaterializerService;
  vaultCredentialsPort: IVaultCredentialsPort;
  ingestAndMaterializeUseCase: IngestAndMaterializeUseCase;
}

This guarantees:

• Testability: In test environments, the container easily swaps file-backed databases for :memory: instances.
• Single Instance Pooling: DuckDB connections and SQLite handles are properly pooled and shared without leaks.

---

📡 API Routes Overview

Route Prefix	Method	Purpose
/api/metrics/kpis	GET	Portfolio summary (equity, cost basis, realized/unrealized PnL, win rate).
/api/metrics/risk	GET	Institutional metrics (Sharpe ratio, 30d volatility, ATH drawdown, Alpha, Beta).
/api/metrics/performance	GET	Daily valuation time-series in the requested currency (default EUR), converted per point at that date’s rate; points with no rate are null.
/api/tax/import	POST	Ingestion pipeline submission with source format profile.
/api/tax/lots	GET	Query calculated tax lots with remaining balances and custody provenance.
/api/settings/accounts	GET	Lists the user-facing accounts (id as value, name as label); synthetic custody counterparties are excluded by ListAccountsUseCase.
/api/tax/transactions/spot	GET	Spot transactions for the effective (edited) view, optionally filtered by accountId, through SearchSpotTransactionsUseCase. Ledger order, oldest first.
/api/credentials/vault/*	Multiple	Manage encrypted third-party credentials and vault lock state.
/api/advisor/*	Multiple	Read-only AI Portfolio Advisor: streaming chat, model chain and execution-profile configuration. See AI Advisor.