# Privatefolio Docs

> Documentation for users & developers.

## AI setup

### Overview

* Leverages Vercel AI SDK for an interactive portfolio analysis assistant in both frontend and backend.
* Users chat with an AI that can query on-chain data, run SQL via tools, and fetch current market info via web search.

### Providers & SDKs

* **Vercel AI SDK** (`ai`, `@ai-sdk/react`, `@ai-sdk/ui-utils`): powers chat streaming and UI hooks in the frontend.
* **OpenAI** (`@ai-sdk/openai` v1.3.22): used for chat completions and tool-enabled search via `createOpenAI().responses(modelId)` and `tools.webSearchPreview()`.
* **Anthropic** (`@ai-sdk/anthropic` v1.2.12): language models via `createAnthropic({ apiKey }).languageModel(modelId)`.
* **Perplexity** (`@ai-sdk/perplexity` v1.1.9): language models via `createPerplexity({ apiKey }).languageModel(modelId)`.

### Frontend Integration

* **Assistant Page**: `packages/frontend/src/pages/AssistantPage/AssistantPage.tsx` sets up tabs and routes.
* **Chat UI**: `AssistantChat.tsx` uses `useChat` from `@ai-sdk/react` to manage messages, stream responses, and handle stops.
* **State Management**: nanostores (`$assistantModel`, `$assistantMode`, `$activeAccount`) control model selection and account context.
* **UI Components**: model selector (`AssistantModelSelect.tsx`), settings (`AssistantSettings.tsx`), message toolbar and history components.

### Backend / API Integration

* **Assistant HTTP API**: `packages/backend/src/api/account/assistant-http-api.ts` exports `handleAssistantChat`.
  * Endpoint: `POST /assistant-chat`
  * Request: JSON `{ accountName, id (conversationId), modelId, messages: Message[] }`.
  * Response: chunked streaming (`Transfer-Encoding: chunked`) via `streamText` from Vercel AI SDK.
* **Business Logic**:
  * Fetch encrypted API key (`getApiKey`) from KV store.
  * Select model and provider options based on `model.family` and `model.capabilities`.
  * Assemble system prompt (`getAssistantSystemPrompt` in `settings/assistant.ts`).
  * Initialize tools (`getAssistantTools`) for on-chain data access.
* **Chat Persistence**: `assistant-api.ts` provides upsert and query functions (`upsertChatMessage`, `getChatHistoryByConversation`).

### Environment Variables & Configuration

* **Backend Service**:
  * `JWT_SECRET`: decrypts per-account AI keys stored in KV.
  * `PORT`: HTTP server port (default 5555).
* **Provider Credentials** (per account, stored encrypted in KV):
  * `assistant_openai_key` (prefixed `sk-`)
  * `assistant_anthropic_key` (prefixed `sk-ant-`)
  * `assistant_perplexity_key` (prefixed `pplx-`)

### Prompt & Model Management

* **System Prompt**: template in `packages/backend/src/settings/assistant.ts` via `getAssistantSystemPrompt`, includes timestamp and tool descriptions.
* **Models**: definitions in `packages/backend/src/settings/assistant-models.ts`, listing IDs, families, capabilities, context windows, and cost per 1k tokens.
* **Metadata**: each chat message stores `modelId`, `usage`, `finishReason`, and prompt context in JSON metadata.

### Development & Testing

* **Local Setup**: run `yarn dev` (frontend & backend) or `yarn dev:electron` for desktop.
* **AI Keys**: load provider API keys into KV using the `AuthSecrets` mechanism and `assistant_*_key` entries.
* **Testing**:
  * Frontend: `packages/frontend` uses Vitest and mocks `useChat` as needed.
  * Backend: run `vitest` in `packages/backend`, stub `streamText` or mock `createOpenAI`/`createAnthropic` calls.

### Security & Cost Considerations

* Store AI keys encrypted; never log raw keys.
* Monitor token usage via metadata (`usage` returned by `streamText`) and use cost settings in `assistant-models.ts`.
* Choose smaller, cost-efficient models (`o4-mini`, `gpt-4.1-mini`) when high throughput is needed.
* Rate limits and authentication enforced via JWT and per-account secrets; no built-in rate throttling in AI API layer—implement externally if needed.


## Backend

### Overview

Privatefolio Backend is a Node.js/Bun service that aggregates multi-chain cryptocurrency data, provides a REST and WebSocket API, and persists data in a local SQLite database. It powers the desktop app and frontend with real-time account balances, transactions, and price history.

### Architecture

```
Frontend  <── HTTP/WebSocket ──>  Backend Server  <── API SDK ──>  Data Aggregator (Relayer)
                                              │
                                              └── SQLite (persistent storage)
```

* **API Server** handles HTTP routes and WebSocket RPC for frontend communication.
* **Backend Relayer** schedules tasks for data fetching, processing, and side-effects.
* **Database** uses SQLite for fast, local persistence.
* **Utilities** provide config management, process control, and inter-service communications.

### Package structure

```text
packages/backend/
├── src/
│   ├── api/            # HTTP & WebSocket API definitions
│   ├── config/         # Environment and settings loaders
│   ├── sqlite/         # Schema and migration logic
│   ├── utils/          # Helper functions
│   ├── backend-server.ts  # HTTP/WebSocket server implementation
│   ├── backend-relayer.ts # Task scheduler and data aggregator
│   └── start.ts        # Entry point wiring server + relayer
├── data/               # Runtime database and log files
├── build/              # Compiled outputs for production
├── test/               # Vitest test suites organized by feature
└── package.json        # Scripts, dependencies, and build setup
```

### Core Components

* **API Server** (`src/backend-server.ts`): serves REST (`/ping`, `/info`, `/download`, `/upload`) and WebSocket RPC. Serves static frontend build.
* **Backend Relayer** (`src/backend-relayer.ts`, `src/start.ts`): uses Cron via `croner` and audit-log subscriptions to enqueue data tasks (balances, prices, net worth).
* **Database** (`src/sqlite/`): initializes and migrates SQLite database; defines interfaces in `src/interfaces.ts`.
* **Utilities** (`src/utils/`, `src/backend-comms.ts`): config parsing, throttling, file upload/download handlers, and inter-process messaging.
* **Configuration** (`src/server-env.ts`, `src/settings.ts`): loads environment variables (PORT, APP\_VERSION, GIT\_HASH, GIT\_DATE) and default settings (throttle durations, data dirs).

### API Endpoints

* **HTTP**
  * `GET /ping` → `pong`
  * `GET /info` → build metadata (version, commit, build date)
  * `GET /download` & `POST /upload` → file operations for account backups
  * `OPTIONS /*` → CORS preflight
  * Static file serving from frontend build
* **WebSocket RPC**
  * Dynamic method invocation: send `{ id, method, params }`, receives `{ id, result }` or error.
  * Supports callback functions via `FunctionReference` messages.

### Database

* Uses SQLite via `sqlite3` (Node.js) and `sqlite` (Bun) packages.
* Database files located under `packages/backend/data/databases/`.
* Schema and migrations defined in `src/sqlite/`; initialized on startup.
* Data access via typed interfaces (`src/interfaces.ts`).

### Configuration

* Environment variables:
  * `PORT` (default 4001 dev, 5555 prod)
  * `APP_VERSION`, `GIT_HASH`, `GIT_DATE` (populated from git/npm)
  * `DATA_LOCATION` (overrides default data directory)
  * `BUN_SQL`, `GITHUB_CI` (test flags)
* Settings file: `src/settings.ts` defines throttle durations and cron schedule.

### Development

Prerequisites: Node.js v20+, Bun, Yarn.

```sh
yarn             # install dependencies
yarn build       # compile TypeScript & build frontend
yarn dev         # runs backend (watch) + relayer
```

### Testing

```sh
yarn test        # run Vitest (Node SQLite)
yarn test:bun    # run Bun-specific SQLite tests
yarn test:ci     # CI mode (Node + Bun)
```

Tests located in `packages/backend/test/` organized by feature (e.g., `balances`, `tags`, `bun`).

### Deployment

```sh
# build production bundle
yarn build
# Docker image build & run (from packages/backend)
yarn docker:build
yarn docker:run
yarn docker:remove
```

In Electron, backend is started automatically on app launch.


## Desktop Apps

This document describes the Electron setup for the Privatefolio desktop application.

### Overview

Privatefolio uses Electron to package and distribute the frontend as a desktop application. The Electron setup is located in the `packages/electron` directory and is built using Electron Forge.

### Project Structure

```
packages/electron/
├── build/            # Output directory for compiled TypeScript
├── out/              # Output directory for packaged app
├── src/              # Source code
│   ├── api.ts        # API definitions
│   ├── backend-manager.ts  # Backend process manager
│   ├── ipc-main.ts   # IPC communication setup
│   ├── preload.ts    # Preload script for renderer
│   ├── start.ts      # Main entry point
│   └── utils.ts      # Utility functions
├── forge.config.js   # Electron Forge configuration
├── package.json      # Package configuration
└── tsconfig.json     # TypeScript configuration
```

### Main Components

#### Entry Point (`start.ts`)

The main entry point for the Electron app handles:

* Window creation and configuration
* System tray setup
* Development reloading (when not in production)
* Custom title bar configuration
* App lifecycle management
* Starting and stopping the backend server

#### Backend Manager (`backend-manager.ts`)

Manages the backend server process:

* Starting the backend server when the app starts
* Keeping the backend running when the app is minimized to tray
* Stopping the backend server when the app is closed
* Provides methods to check if the backend is running
* Handles backend server port management

#### IPC Communication (`ipc-main.ts`)

Handles communication between the main and renderer processes:

* Notifications
* Theme mode switching
* Log directory access
* Log reading
* Backend server management (getting URL, checking status, restarting)

#### Preload Script (`preload.ts`)

Exposes a secure API to the renderer process via the contextBridge:

* Notification sending
* Log access
* Platform information
* Theme mode switching
* Backend server operations (getting URL, checking status, restarting)

### Build Process

The application uses Electron Forge for packaging and distribution:

1. TypeScript is compiled to JavaScript (`yarn build`)
2. Icons are generated from source images (`yarn gen-icons`)
3. The app is packaged with Electron Forge (`yarn package`)
4. Platform-specific installers are created (`yarn bundle:win`, `yarn bundle:linux`, `yarn bundle:mac`)

### Development

To start the development environment:

```bash
yarn dev
```

This command:

1. Compiles TypeScript in watch mode
2. Starts Electron with hot reloading enabled
3. Starts the backend server automatically

### Production Builds

To create production builds:

```bash
# Build for development
yarn build

# Create production installers
yarn bundle:win
yarn bundle:linux
yarn bundle:mac
```

The build process creates platform-specific installers:

* Windows: Nsis installer (.exe)
* macOS: ZIP archive
* Linux: DEB and RPM packages

### Configuration

The application uses `electron-forge` for building and packaging, with configuration in `forge.config.js`. Key configurations include:

* Custom app icons
* App metadata
* Build targets per platform
* Dependency inclusion rules

### Backend Integration

The Electron app integrates with the Privatefolio backend server:

1. In production, the backend server is started automatically when the app starts
2. In development, the backend server is started separately by lerna, not by the Electron app
3. The backend continues running when the app is minimized to tray
4. The backend is gracefully stopped when the app is closed (in production)
5. The frontend communicates with the backend via HTTP/WebSocket on localhost
6. Different ports are used in development (4001) and production (5555)

#### Development Setup

In development mode:

* The backend server is started by lerna through the `yarn dev` command in the root directory
* The Electron app connects to this already-running backend server
* The backend runs on port 4001

#### Production Setup

In production mode:

* The backend server is started by the Electron app itself
* The backend process is managed by the BackendManager
* The backend runs on port 5555

#### Backend API Access

The frontend can access backend functionality through the Electron preload API:

```typescript
// Get the backend URL (which includes the correct port based on environment)
const backendUrl = window.electron.backend.getUrl();

// Check if the backend is running
const isRunning = window.electron.backend.isRunning();

// Restart the backend if needed (only works in production)
await window.electron.backend.restart();
```


### Privatefolio Expo (Mobile) Setup

This document explains how to run, build, and publish the Privatefolio mobile app powered by Expo.

#### Overview

* The mobile app currently wraps the hosted web app in a React Native `WebView` and provides a native shell for distribution on iOS/Android. Native features can be layered in incrementally.
* Source lives in `packages/expo` and uses Expo SDK 53, React 19, React Native 0.79.

#### Project Layout

* `packages/expo/package.json`: scripts and dependencies
* `packages/expo/eas.json`: EAS build/submit profiles
* `packages/expo/app.json`: Expo config (name, icons, Android package, splash, plugin config)
* `packages/expo/app/index.tsx`: App entry using `WebView` pointing to `https://privatefolio.app`

#### Prerequisites

* Node.js 20+
* Yarn 1.x (workspaces)
* Expo tooling: you can use `npx expo` without a global install
* For EAS builds: `eas-cli` (`yarn` will install it locally) and an Expo account (`eas login`)

#### Install Dependencies

From the repository root:

```bash
yarn
```

#### Run in Development

You can run from the workspace root using Yarn workspaces or by `cd` into the package.

Option A (from root, via workspace):

```bash
yarn workspace privatefolio-expo dev
```

Option B (inside the package):

```bash
cd packages/expo
yarn dev            # starts Expo with a tunnel
# or
yarn dev:android    # open Android emulator/device
yarn dev:ios        # open iOS simulator (macOS)
yarn dev:web        # run via web target
```

Notes:

* First run will prompt you to open the app on a device/simulator or a browser.
* If Metro cache causes issues, restart with `npx expo start -c`.

#### What the App Does (Today)

`packages/expo/app/index.tsx` renders a `WebView` pointing to `https://privatefolio.app` with sensible defaults (loading spinner, storage enabled, mixed content compatibility for charts, etc.). This enables a fast mobile presence while preserving the web UI. The `app.json` sets the deeplink scheme to `privatefolio` for future use.

#### Configuration Reference

* `package.json` (scripts & deps)
  * `dev`, `dev:android`, `dev:ios`, `dev:web`
  * EAS: `build:*`, `submit:*`, `publish`
  * Key deps: `expo`, `expo-router`, `react-native-webview`, `@react-navigation/native`

* `app.json` (Expo config)
  * Name/slug: `Privatefolio` / `privatefolio`
  * Scheme: `privatefolio` (deeplinks like `privatefolio://`)
  * Android: package `xyz.privatefolio.mobile`, edge-to-edge enabled, adaptive icon
  * Web: uses `metro` bundler, static output for previews
  * Plugins: `expo-router`, `expo-splash-screen`

* `eas.json` (EAS profiles)
  * `build.production`: auto-increment version, caching enabled
  * `submit.production.android`: uses `GOOGLE_SERVICE_ACCOUNT_KEY_PATH` for Play Store submission, track `production`

#### Building with EAS

Login once (only needed on a new environment):

```bash
npx eas login
```

Build commands (run from repo root or `packages/expo`):

```bash
yarn workspace privatefolio-expo bundle:android
yarn workspace privatefolio-expo bundle:ios
```

Artifacts are created on EAS servers; the CLI will provide download/install links.

#### Submitting to Stores

Android (requires a Google Cloud service account JSON with Play Console access):

```bash
export GOOGLE_SERVICE_ACCOUNT_KEY_PATH=/absolute/path/to/google-service-account.json
yarn workspace privatefolio-expo submit:android
```

iOS submission requires App Store Connect credentials and an Apple Developer account:

```bash
yarn workspace privatefolio-expo submit:ios
```

You can chain build+submit via:

```bash
yarn workspace privatefolio-expo publish
```

#### App Identity and Linking

* Android package: `xyz.privatefolio.mobile`
* Deeplink scheme: `privatefolio://` (reserved for future native navigation/deeplinks)
* If you add native navigation in the future, use `expo-linking` to handle incoming URLs and map them to screens.

#### Permissions

The `WebView` enables geolocation and file access. If you add native geolocation or file pickers, declare platform permissions in `app.json` and follow Expo documentation for permissions prompts.

#### Troubleshooting

* Clear Metro cache: `npx expo start -c`
* Kill stray Metro processes: close all `expo start` processes and restart
* Android emulator not detected: ensure Android Studio SDK tools and AVD are installed; run `adb devices`
* iOS simulator boot issues: open Xcode once and accept license; run `xcrun simctl list devices`

#### Roadmap for Native Enhancements (Optional)

* Add account storage using secure storage modules
* Implement push notifications for balance alerts
* Integrate native share sheets and file import/export
* Use `expo-router` to progressively introduce native screens

#### Notes

* This is a Yarn workspaces monorepo; prefer running scripts via `yarn workspace privatefolio-expo <script>` from the repo root.
* Do not run long-lived `start` scripts in CI; use EAS for cloud builds and local devices for development.


## Frontend

### Overview

* The Privatefolio Frontend is a React and Vite powered TypeScript application that delivers a responsive and interactive UI for tracking multi-chain cryptocurrency portfolios. It leverages Material‑UI for design, nanostores for state management, and Comlink/WebWorker‑backed SQLite for client‑side data persistence, with seamless integration into Electron.

### Architecture

* App Shell (`src/App.tsx`) initializes routing and layout.
* Views & Pages consume shared UI components and data stores.
* State Management via nanostores stores global state and persists settings.
* Service Layer communicates through REST/WebSocket (FeathersJS) and Electron IPC.
* Data Layer runs in a WebWorker using Comlink + wa‑sqlite for local SQLite access.

### Directory Structure

* packages/frontend/
  * public/: static assets and PWA manifest
  * src/
    * components/: reusable UI elements (charts, tables, forms)
    * views/: page components (Portfolio, Transactions, Settings)
    * stores/: nanostores state and persistence logic
    * api/: REST/WebSocket client setup and hooks
    * hooks/: custom React hooks (data fetching, IPC)
    * styles/: theme and global styles
    * App.tsx, main.tsx: entry point and router
  * build/: compiled bundles and assets
  * vite.config.ts, tsconfig.json: build and compiler configuration
  * vercel.json: deployment settings for Vercel

### Core Components

* App Shell: routing with React Router Dom, layout and top‑level providers (`src/App.tsx`).
* Views & Pages: key user screens — Portfolio overview, Transaction history, Search/Command palette, Settings.
* UI Components: Material‑UI based library for charts (lightweight‑charts), tables, inputs and notifications.
* State Management: nanostores in `src/stores` for reactive global state, persistent settings via `@nanostores/persistent`.
* Service Layer: API modules in `src/api` using FeathersJS REST/WebSocket; Electron IPC exposed via preload for desktop.

### API Integration

* REST calls and real‑time RPC via FeathersJS clients configured at runtime with `VITE_APP_VERSION`, `VITE_GIT_HASH`, `VITE_GIT_DATE`.
* WebSocket subscriptions for live updates (balances, prices).
* Electron IPC (`window.electron.*`) for native features (notifications, file import/export).

### Configuration

* Environment Variables: VITE*APP\_VERSION, VITE\_GIT\_HASH, VITE\_GIT\_DATE, VITE\_PUBLIC*…
* Vite Config (`vite.config.ts`): aliasing, plugin setup (`@vitejs/plugin-react`, rollup visualizer).
* Vercel Settings (`vercel.json`) for static deployment and rewrites.

### Features

* Portfolio Analytics: real‑time balance charts and net worth tracking.
* Transaction Management: list, search (by hash), and tag transactions.
* Price History: interactive candlestick and line charts per asset.
* Command Palette: quick search and actions via `kbar`.
* Backup & Restore: import/export data as JSON or CSV.

### Development

* Prerequisites: Node.js v20+, Yarn 1.22+
* Install: `yarn`
* Dev Server: `cd packages/frontend && yarn dev` (runs on port 4000)
* Build: `yarn build`

### Testing

* Run Unit & Integration: `yarn test`
* Test Patterns: files matching `src/**/?(*.)+(test|spec).ts(x)?`
* CI: included in `yarn test:ci` via root Lerna workflow

### Deployment

* **Web Deployment**: Automatic deployment to Cloudflare Pages via GitHub Actions (see [web-deployment.mdx](./web-deployment.mdx)).
* **Static Site**: Serve `packages/frontend/build` on any web host or Vercel.
* **Electron**: Packaged into desktop app via `yarn bundle` in root (see ELECTRON\_SETUP.md).


## Testing Guide

### Testing Philosophy

Privatefolio's testing approach focuses on maintaining high code quality and reliability through comprehensive test coverage across the monorepo's packages. The project emphasizes functional correctness, particularly in the backend services that handle critical financial data processing. Tests are designed to validate functionality at multiple levels, from unit to integration tests, with a preference for snapshot testing to prevent regressions. The project aims to ensure that all core functionality remains stable across updates and that new features are thoroughly tested before integration.

### Testing Tools & Frameworks

#### Core Testing Stack

* **Vitest**: Primary testing framework used across the project, providing a Jest-compatible API with TypeScript support out of the box
* **Bun Test**: Used for specific SQLite compatibility tests that need to run in the Bun runtime
* **Snapshots**: Extensive use of inline snapshots for regression testing
* **CI Integration**: Tests run automatically as part of the GitHub Actions CI workflow

#### Package-specific Tools

* **Backend**:
  * Custom diff visualization configuration in `vitest.diff.ts`
  * Environment flags to enable/disable Bun SQLite testing (`BUN_SQL=true/false`)
* **Frontend**:
  * Utilizes Vitest within the context of the Vite build system
* **Electron**:
  * Limited direct testing, relies on the testing of its constituent parts in backend and frontend packages

### Test Types & Organization

#### Backend Package

##### Test Directory Structure

The backend package has a well-organized test directory structure:

```
/test
  /__snapshots__/     # Generated snapshot files
  /assets/            # Tests for asset-related functionality
  /backend-relayer/   # Tests for the backend relayer service
  /backup/            # Tests for backup/restore functionality
  /balances/          # Tests for balance tracking
  /bun/               # Bun-specific tests for SQLite compatibility
  /connections/       # Tests for external API connections
  /daily-prices/      # Tests for price history functionality
  /database/          # Database-related tests
  /file-imports/      # Tests for file import functionality
  /files/             # File handling tests
  /networth/          # Net worth calculation tests
  /server-tasks/      # Server task processing tests
  /tags/              # Tag management tests
  /trades/            # Trade tracking tests
  /utils/             # Utility function tests
```

Tests follow a clear naming convention with `.test.ts` suffix for each test file.

##### Test Categories

* **Unit Tests**: Focused on testing individual functions and modules in isolation
* **Integration Tests**: Test the interaction between multiple components
* **SQLite Compatibility Tests**: Special tests that run in the Bun environment to ensure SQLite compatibility
* **API Tests**: Test the backend API endpoints functionality

##### Key Test Fixtures & Mocks

* Random account names generated per test run to ensure test isolation
* Test-specific transaction and audit log IDs
* Snapshot-based assertions for complex data structures

#### Frontend Package

The frontend package uses Vitest for testing, though it has less extensive test coverage compared to the backend. Testing focuses primarily on utility functions and critical UI components.

#### Electron Package

The Electron package does not have dedicated tests in its own directory. Functionality is primarily tested through the backend and frontend packages that it integrates.

### Running Tests

#### Common Commands

To run all tests across the monorepo:

```sh
yarn test
```

For CI-specific test runs (including all test suites):

```sh
yarn test:ci
```

#### Package-specific Commands

Or navigate to the specific package directory:

```sh
# For backend tests
cd packages/backend
yarn test                # Run standard tests (without Bun SQLite)
yarn test:bun            # Run Bun-specific SQLite tests
yarn test <test-file>    # Run a specific test file, e.g., yarn test test/tags/tags-api.test.ts
```

#### Testing in Watch Mode

When developing, you can run tests in watch mode in the backend package:

```sh
cd packages/backend
yarn test --watch
```

This will rerun the tests automatically when files change.

#### Debugging Tests

If tests fail, the output includes detailed error messages and diff comparisons. For snapshot test failures, you can update snapshots with:

```sh
yarn test -u
```

For more complex debugging scenarios:

1. Add `console.log` statements or use the `debug` option in Vitest
2. Run a specific test file to isolate the issue
3. Use `it.only` to run just one test case within a file

### CI/CD Integration

Testing is integrated into the Continuous Integration pipeline via GitHub Actions in the `.github/workflows/continuous-integration.yml` file.

The CI process:

1. Checks out the code
2. Sets up Node.js and Bun
3. Installs dependencies
4. Builds the project
5. Runs linting checks
6. Checks TypeScript types
7. Runs all tests in CI mode

Tests are a critical gate for accepting pull requests and merging code into the main branch.

### Best Practices

#### Testing Patterns to Follow

1. **AAA Pattern**: Structure tests using the Arrange-Act-Assert pattern:
   ```typescript
   it("should create and retrieve tags", async () => {
     // arrange
     const tagNames = ["defi", "staking", "trading"]

     // act
     const tags = await upsertTags(accountName, tagNames)
     const allTags = await getTags(accountName)

     // assert
     expect(tags).toMatchInlineSnapshot(`...`)
     expect(allTags).toMatchInlineSnapshot(`...`)
   })
   ```

2. **Isolation**: Ensure tests are isolated by using random identifiers for account names and test data:
   ```typescript
   const accountName = Math.random().toString(36).substring(7)
   const transactionId = "test_transaction_" + Math.random().toString(36).substring(7)
   ```

3. **Descriptive Test Names**: Use descriptive `it()` statements that clearly indicate what's being tested

4. **Snapshots for Complex Data**: Use snapshots for testing complex data structures

#### Common Pitfalls to Avoid

1. **Hard-coded Data**: Avoid hard-coded account names or IDs that could lead to test interference
2. **Global State**: Beware of tests that change global state without restoring it
3. **Time Dependencies**: Tests that rely on specific timestamps may be fragile
4. **Incomplete Assertions**: Ensure you're asserting all relevant aspects of the test result

#### Guidelines for Writing New Tests

1. Place tests in the appropriate subdirectory based on functionality
2. Follow existing naming conventions: `feature-name.test.ts`
3. Use descriptive test names in the format "should do something"
4. Include tests for both success and failure cases
5. Use snapshots for complex data structures, but be careful not to overuse them
6. When adding new APIs, include tests for all endpoints and edge cases
7. Structure tests using the AAA pattern (Arrange-Act-Assert)
8. Add appropriate comments to explain test setup and assertions


## Guidelines for AI agents and LLMs

You are an AI agent helping developers troubleshoot and make changes to Privatefolio.

### General Guidelines

As an AI agent, follow these guidelines:

* **Ask clarifying questions** until you have high confidence in the task. Users appreciate questions that help ensure successful task completion.
* **Be specific** when something is unclear or inaccessible. Ask for file paths, URLs, or specific error messages.
* **Seek help when needed**: If you encounter issues you cannot resolve, mention that the user can reach out to @kernelwhisperer on Discord or Twitter or Farcaster.
* **Verify assumptions** before making changes. It's better to confirm than to proceed with uncertainty.

### Common LLM Pitfalls

When helping developers with Privatefolio:

* **DO NOT** ever run the `start` or `dev` scripts because these are long-lived processes that should already be running in the background
* **ALWAYS** use the `test` or `build` scripts when you want to test that something works


import ArchitectureDiagram from '../components/ArchitectureDiagram'

## Architecture

### Overview

The application has two main components: `@privatefolio/backend` and `@privatefolio/frontend`.
These two components are bundled together as a Docker image, or as a desktop app using Electron.

The frontend is a React application, and the backend is a Node.js/Bun server that uses REST and WebSocket APIs to communicate with the frontend.

<ArchitectureDiagram />

### Project structure

Privatefolio is structured as a monorepo, using Lerna for orchestration and Yarn for package management.

* **Root Config:** Yarn workspaces (v1.22.22) with nohoist, AGPL-3.0 license, Lerna (v8.1.3) for monorepo management, and TypeScript for type safety across all packages.

#### Directory Structure

```text
privatefolio/
├── packages/
│   ├── backend/            # Node.js/Bun server with REST & WebSocket APIs
│   │   ├── src/
│   │   │   ├── api/            # HTTP & WebSocket API definitions
│   │   │   ├── config/         # Environment and settings loaders
│   │   │   ├── sqlite/         # Schema and migration logic
│   │   │   ├── utils/          # Helper functions
│   │   │   ├── backend-server.ts  # HTTP/WebSocket server implementation
│   │   │   ├── backend-relayer.ts # Task scheduler and data aggregator
│   │   │   └── start.ts        # Entry point wiring server + relayer
│   │   ├── data/               # Runtime database and log files
│   │   ├── build/              # Compiled outputs for production
│   │   ├── test/               # Vitest test suites organized by feature
│   │   └── package.json        # Scripts, dependencies, and build setup
│   ├── frontend/           # React-based UI with Vite and TypeScript
│   │   ├── src/
│   │   │   ├── components/     # Reusable UI elements (charts, tables, forms)
│   │   │   ├── pages/          # Page components (Portfolio, Transactions, Settings)
│   │   │   ├── stores/         # Nanostores state and persistence logic
│   │   │   ├── api/            # REST/WebSocket client setup and hooks
│   │   │   ├── hooks/          # Custom React hooks (data fetching, IPC)
│   │   │   ├── utils/          # Utility functions and helpers
│   │   │   ├── workers/        # WebWorker-based SQLite integration
│   │   │   ├── App.tsx         # App shell and routing
│   │   │   └── main.tsx        # Entry point
│   │   ├── public/             # Static assets and PWA manifest
│   │   ├── build/              # Compiled bundles and assets
│   │   ├── vite.config.ts      # Vite build configuration
│   │   └── package.json        # Frontend dependencies and scripts
│   ├── electron/           # Desktop application wrapper
│   │   ├── src/
│   │   │   ├── backend-manager.ts  # Backend process manager
│   │   │   ├── ipc-main.ts     # IPC communication setup
│   │   │   ├── preload.ts      # Preload script for renderer
│   │   │   ├── start.ts        # Main entry point
│   │   │   └── auto-updater.ts # Auto-update functionality
│   │   ├── out/                # Packaged app output
│   │   └── package.json        # Electron configuration and scripts
│   ├── expo/               # Mobile app (React Native with Expo)
│   │   ├── app/                # App entry point and screens
│   │   ├── assets/             # Mobile app assets
│   │   ├── app.json            # Expo configuration
│   │   ├── eas.json            # EAS build/submit profiles
│   │   └── package.json        # Mobile app dependencies
│   ├── commons/            # Shared utilities and interfaces
│   │   ├── src/
│   │   │   └── utils.ts        # Common utility functions
│   │   └── package.json        # Shared dependencies
│   ├── commons-node/       # Node.js-specific shared utilities
│   └── docs/               # Documentation site (Vocs)
│       ├── pages/              # Documentation pages
│       ├── components/         # Doc-specific components
│       └── package.json        # Documentation dependencies
├── .github/
│   ├── workflows/          # GitHub Actions CI/CD
│   └── prompts/            # AI agent prompts and guidelines
├── lerna.json              # Lerna monorepo configuration
├── package.json            # Root workspace configuration
└── yarn.lock               # Dependency lock file
```

### Packages Summary

* **`packages/frontend`**
  * **Description & Key Tech:** React-based UI that provides the user interface using Material-UI, Vite, and TypeScript.
  * **Core Features & Tools:**
    * Interactive portfolio visualization with lightweight-charts
    * Command palette (`kbar`) and comprehensive search functionality
    * WebWorker-based SQLite integration for client-side data processing
    * State management with nanostores for reactive updates

* **`packages/backend`**
  * **Description & Key Tech:** Node.js/Bun server providing data processing, API integration, and SQLite database management.
  * **Core Features & Tools:**
    * Multi-chain cryptocurrency data aggregation and processing
    * SQLite database for persistent storage with cross-platform compatibility
    * Scheduled tasks with Croner for periodic data updates
    * Support for both Bun and Node.js SQLite implementations

* **`packages/electron`**
  * **Description & Key Tech:** Desktop application wrapper using Electron with platform-specific optimizations.
  * **Core Features & Tools:**
    * Cross-platform desktop integration (Windows, Linux, macOS)
    * Local file system access for database and configuration
    * Auto-launch capabilities and system tray integration
    * Inter-process communication between frontend and backend

### Workflow & Integration

* **Development:** `yarn dev` runs parallel development servers for frontend and backend, `yarn dev:electron` includes Electron.
* **Building:** `yarn build` for all packages, platform-specific binaries with `yarn bundle:[win|linux|mac]`.
* **Testing:** Comprehensive test suite with `yarn test` and `yarn test:bun` for Bun-specific tests, continuous integration with `yarn test:ci`.
* **Integration:** Packages share common TypeScript interfaces and utilities, with backend exposing APIs consumed by frontend.

### Deployment

* **Frontend:**
  * Compiled with Vite for optimal bundle size and performance
  * Can be deployed as a static site or packaged within Electron

* **Backend:**
  * Runs as a local service within the Electron app
  * Optimized for Bun runtime with fallbacks for Node.js compatibility

* **Electron:**
  * Windows builds with Nsis installer, Linux with DEB packages, macOS with DMG
  * Automated deployment process via GitHub Actions triggered by version changes (`yarn new-version`)
  * Binaries published to GitHub releases for user distribution


## Changelog

This file documents project changes that are of interest to users and developers.
Versioning is based on [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

### v2.0.0-beta.46 - 2025/09/09

#### 🐛 Bug Fixes

* Fix bug in desktop app deployment workflow
* Fix bug in mobile app deployment workflow

### v2.0.0-beta.45 - 2025/09/09

#### 💡 Feature updates

* Add a [new docs website](https://docs.privatefolio.app) for users & developers
* Deploy first version of the Android app

### v2.0.0-beta.44 - 2025/08/25

#### 💡 Feature updates

* Add support for PrivateCloud™ AI Gateway

#### 🐛 Bug Fixes

* Fix bug in coinstats file import

### v2.0.0-beta.43 - 2025/08/21

#### 🐛 Bug Fixes

* Fix bug in coinstats file import
* Fix UI bug with the app header

#### Other updates

* Improve error handling on the frontend

### v2.0.0-beta.42 - 2025/08/20

#### 💡 Feature updates

* Improve server status visibility

#### 🐛 Bug Fixes

* Fix issue in the Mac app for x64 architecture

### v2.0.0-beta.41 - 2025/08/14

#### 🐛 Bug Fixes

* Fix bug with service worker registration (push notifications)

### v2.0.0-beta.40 - 2025/08/14

#### 💡 Feature updates

* Add coinstats extensions
* Improve `Server logs` page
* Add `Server health` page

#### Other updates

* Track and report errors through telemetry
* Improve error logging
* Improve backend bundle
* Fix bug in help sections
* Improve number formatting
* Extract common logic in the `commons` and `commons-node` libraries (packages)

### v2.0.0-beta.37 - 2025/08/04

#### 🐛 Bug Fixes

* Fix bug with `AppLink`

### v2.0.0-beta.36 - 2025/08/04

#### 🐛 Bug Fixes

* Fix bug with `randomUUID()`

### v2.0.0-beta.35 - 2025/07/28

#### 🐛 Bug Fixes

* Fix bug in assets sql table

### v2.0.0-beta.34 - 2025/07/23

#### 💡 Feature updates

* Soft-launch the Binance connection

### v2.0.0-beta.33 - 2025/07/21

#### 💡 Feature updates

* Add Import data wizard
* Improve PlatformPage

### v2.0.0-beta.32 - 2025/07/17

#### 💡 Feature updates

* Improve experience for adding manual transactions

#### Other updates

* New `WalletInput`, `PlatformInput` and `AssetInput` components for extension developers

### v2.0.0-beta.31 - 2025/07/15

#### 🐛 Bug Fixes

* Fix window buttons in the Mac app
* Fix copy & paste in the Mac app
* Fix tray icon in the Mac app

### v2.0.0-beta.30 - 2025/07/13

#### 🐛 Bug Fixes

* Fix start-up issue in the Mac app

### v2.0.0-beta.29 - 2025/07/13

#### 🐛 Bug Fixes

* Fix an issue with Reset Account

### v2.0.0-beta.28 - 2025/07/13

#### 🐛 Bug Fixes

* Fix an issue with Delete Account

#### Other updates

* Improve documentation for developers and AI agents

### v2.0.0-beta.27 - 2025/07/12

#### 🐛 Bug Fixes

* Fix start-up issue in desktop apps

### v2.0.0-beta.25 - 2025/07/12

#### 💡 Feature updates

* Notarization for the macOS app
* Improve `fetchDailyPrices` to not go into the past further than needed
* Add support for snap packages on Linux

#### 🐛 Bug Fixes

* Fix binance file imports
* Fix trade calculation for binance data
* Fix bug with authorization in `/download` and `/upload` endpoints

### v2.0.0-beta.19 - 2025/07/09

#### 💡 Feature updates

* Code-signing for the macOS app

### v2.0.0-beta.18 - 2025/07/08

#### 💡 Feature updates

* Improve UI UX across the app, in particular for the desktop apps
* Add new chart intervals: 3D (3 days), M (1 month)
* Add new tooltip for candlestick charts
* Add support for Claude 4 Opus, Claude 4 Sonnet, Claude 3.7 Sonnet, Claude 3.5 Sonnet, Claude 3.5 Haiku, Claude 3 Haiku

### v2.0.0-beta.15 - 2025/07/06

#### 🐛 Bug Fixes

* Fix issue with `kioskMode` introduced in `v2.0.0-beta.14`

### v2.0.0-beta.14 - 2025/07/06

#### 💡 Feature updates

* Give tools (like reading user balances) to the AI Assistant, alongside Reasoning and Web search
* Add Anthropic and Perplexity as AI providers, alongside OpenAI

#### 🐛 Bug Fixes

* Fix bug in cursor invalidations
* Fix bug in self hosted deployments regarding the port

#### Other updates

* Better error message when the server is unreachable
* Add new `readSql` method, useful in kiosk mode

### v2.0.0-beta.11 - 2025/07/03

#### 💡 Feature updates

* Auto-updates for the Windows and Linux apps

### v2.0.0-beta.8 - 2025/07/01

#### 💡 Feature updates

* Add support for 26 more blockchains with the Etherscan extension
* Add a mini nav menu for tablets and laptops
* Improve user experience around connections: new `All platforms` option
* Add a new action `Verify balances` which checks if the on-chain data reflects the app data
* Allow adding of manual transactions
* Add `Recent` section in search bar
* Add a checkmark for the exchanges and blockchains supported by our extensions

#### 🐛 Bug Fixes

* Fix truncation on `AmountBlock`
* Fix refresh trades

#### Other updates

* Speed up daily price retrieval with database indexes
* Add platform categories to avoid conflicts on unique coingecko ids
* Add a new page to chat with OpenAI models (next step is to give them tools)

### v2.0.0-beta.7 - 2025/06/22

#### 🐛 Bug Fixes

* Fix a bug in telemetry

### v2.0.0-beta.6 - 2025/06/20

#### 💡 Feature updates

* Improve UI UX for mobile devices.

#### 🐛 Bug Fixes

* Fix bug when time traveling through trades

### v2.0.0-beta.5 - 2025/06/20

#### 💡 Feature updates

* Split app bundle into multiple files to improve loading performance.

#### 🐛 Bug Fixes

* Fix bug in `ExtensionPage` where the help (How to use) section was not rendering at all.

### v2.0.0-beta.4 - 2025/06/20

#### 💡 Feature updates

* New `Pro Chart` feature, allowing users to use advanced tradingview features like drawing tools, indicators, etc.
* New `Deposits` feature, allowing users to view their historical deposits and withdrawals.
* Improve search bar to highlight assets and platforms from the user's portfolio.
* Improve mobile UI/UX and responsiveness across the app.

### v2.0.0-beta.3 - 2025/06/18

#### 💡 Feature updates

* New `Kiosk` setting, to make your portfolio public in a read-only fashion.
* New `Trades` feature, allowing users to view their trades (including their cost basis, deposits, withdrawals, etc)
* New `PnL` (profit & loss) feature, allowing users to view historical PnL on trades and on their whole account.
* Shortcuts for navigating between pages

#### 🐛 Bug Fixes

* Fix app routing for accounts (local & cloud)

### v2.0.0-beta.2 - 2025/06/11

#### 💡 Feature updates

* Added Alchemy price API extension for better price data coverage
* Added kiosk mode for public portfolio displays
* Added support for searching assets by contract address
* Added a data source selector to the asset price history chart

#### 🐛 Bug Fixes

* Fixed critical bugs in Alchemy & Coinbase price APIs
* Fixed bug in refreshing prices
* Fixed bug reading non-existent files
* Fixed UI glitch when deleting the last account
* Fixed bug in asset table: changing the price api back to auto failed

### v2.0.0-beta.1 - 2025/06/10

This release has breaking changes and is not compatible with the previous `alpha` versions! 🚨🚨🚨

#### 💡 Feature updates

* New `Extensions` page, allowing developers and users to discover extensions.
* New `Platforms` page, allowing users to discover exchanges and blockchains.
* Rewritten Coingecko integration, supporting all their assets, exchanges and blockchains in a seamless way.

### v2.0.0-alpha.30 - 2025/05/23

This release concludes the alpha phase of the v2.0.0 release cycle, marking a significant milestone in the development of the application.

#### 💡 Feature updates

* You can now crete cloud account through PrivateCloud™.
* Payments are now live for the premium plan of the cloud service.
* New `Logs` tab in the Server page, allowing users to view server logs directly in the application.
* New `Settings` tab in the Server page, allowing users to configure server settings directly in the application.
* Automatic updates for the Windows app, allowing users to stay up-to-date without manually installing new versions.

#### 🐛 Bug Fixes

* Fix the start on login feature on Linux.
* Reading from the database happens on a separate thread now, improving performance and responsiveness when there is a write operation in the background.
* Backup & restore functionality been rewritten to be more robust and user-friendly.

#### Other updates

* Comprehensive project documentation for developers and AI agents.
* Improved developer experience for Linux and Windows developers.
* Using the app now requires a one-time password setup. This protects user data from unauthorized access, especially in cloud or self-hosting deployments.

### v2.0.0-alpha.0 - 2025/03/19

#### 💡 Feature updates

* Migrate database engine from no-sql (PouchDB) to sql (SQLite).
* Implement client-server architecture (prerequisite for Cloud deployments), unfortunately this breaks full in-browser support (for the time being).
* Package the app & server as a desktop application that can run in the background (Windows, Linux & macOS).

### v0.2.0 - 2024/03/10

#### 💡 Feature updates

* Better mobile support for Navigation and Settings.
* Improved UI/UX for data tables (especially loading)

***

### v0.1.0 - 2024/03/02

#### 💡 Feature updates

* Parallelize Price API requests in `daily-prices-api` to improve performance 4-6 times.
* Add a new historical prices provider: [Redstone](https://redstone.finance/).
* Show the USD value of amounts in `TransactionDrawer` and `AuditLogDrawer`.

#### 🐛 Bug Fixes

* Fix `TaskDetailsDialog` to show the previous progress percentage for updates that have the format
  `[undefined, string]`, indicating that the progress remained the same, but a new.


### Comparison table

| Feature          | Privatefolio         | Rotki                      | Ghostfolio                          | Midday                       | DeBank                 | CoinStats                  | Delta                       |
| ---------------- | -------------------- | -------------------------- | ----------------------------------- | ---------------------------- | ---------------------- | -------------------------- | --------------------------- |
| **Type**         | AI Wealth Manager    | Open-source crypto tracker | Open-source wealth manager          | Open-source business finance | DeFi portfolio tracker | Freemium crypto tracker    | Investment tracker          |
| **Hosting**      | Self-hosted, Cloud   | Self-hosted                | Self-hosted, Cloud                  | Self-hosted, Cloud           | Cloud                  | Cloud                      | Cloud                       |
| **License**      | AGPL-3.0             | AGPL-3.0                   | AGPL-3.0                            | AGPL-3.0                     | Proprietary            | Proprietary                | Proprietary                 |
| **AI assistant** | ✅ Tool-based         | 🟡                         | 🟡                                  | ✅ Yes                        | 🟡                     | 🟡                         | 🟡                          |
| **Desktop apps** | ✅ Yes                | ✅ Yes                      | 🟡                                  | 🟡 Mac                       | 🟡                     | 🟡 Mac                     | 🟡 Win, Mac                 |
| **Mobile apps**  | ✅ Web, Native (wip)  | 🟡                         | ✅ Web                               | 🟡                           | ✅ Native               | ✅ Native                   | ✅ Native                    |
| **Multi-chain**  | ✅ Multiple           | ✅ Multiple                 | ✅ Multiple (coins; not chain-level) | 🟡                           | ✅ EVM networks         | ✅ 100+ chains; 20k+ coins  | ✅ 10,000+ coins             |
| **Multi-chain**  | ✅ Multiple           | ✅ Multiple                 | 🟡                                  | 🟡                           | ✅ EVM networks only    | ✅ 20k+ coins, 120+ chains  | ✅ 10k+ crypto, 100k+ assets |
| **DeFi support** | 🟡 Limited (wip)     | ✅ Advanced protocols       | ✅ Basic                             | 🟡                           | ✅ Advanced             | ✅ Advanced (1k+ protocols) | ✅ Basic                     |
| **Extensions**   | ✅ Extensions         | ✅ Modules                  | 🟡                                  | 🟡                           | 🟡                     | 🟡                         | 🟡                          |
| **Privacy**      | ✅ Self-hosted option | ✅ Self-hosted option       | ✅ Self-hosted option                | ✅ Self-hosted option         | ⚠️ Cloud-dependent     | ⚠️ Cloud-dependent         | ⚠️ Cloud-dependent          |
| **Exploit-free** | ✅                    | ✅                          | ✅                                   | ✅ ☑                          | ✅                      | 🚨 1.6k wallets hacked     | ✅                           |
| **Pricing**      | Free, Premium        | Free, Premium              | Free, Premium                       | Free                         | Free                   | Free, Premium              | Free, Premium               |


## Create a release

```sh
yarn new-version <major|minor|patch>
```

Note: this will trigger the `publish-*.yml` workflows, which will:

* publish the frontend to Cloudflare Pages.
* publish the backend to GitHub Container Registry.
* build the native apps and attach them to the GitHub release.


## Docker deployment

Deploying Privatefolio via Docker requires us to build a Docker image that packages both `@privatefolio/backend` and `@privatefolio/frontend` alongside their dependencies.

Are you looking to self-host Privatefolio using the official Docker image? Go to [Self-hosting](./self-hosting-with-docker.md).

### Prerequisites

Before we get started you must have Docker installed:

```sh
docker --version
# Docker version 28.3.2, build 578ccf6
```

If you don't have it, get it from [docker.com](https://docs.docker.com/get-docker/).

### Building the image

```sh
yarn docker:build
```

### Running the container

```sh
yarn docker:run # start a container named privatefolio
yarn docker:remove # remove the container
```

### Building the image manually

To build the image without using the npm scripts:

```sh
docker build -t privatefolio -f packages/backend/Dockerfile .
```

To run the container:

```sh
docker run -d -p ${PORT:-5555}:${PORT:-5555} -v privatefolio-data:/app/data --name privatefolio privatefolio
```

### Accessing the app

The app will be available on the port you set in `docker run` (defaulting to `5555`):

Visit [`http://localhost:5555`](http://localhost:5555) in your browser.

### Dockerfile

The Docker image uses a multi-stage build process. It builds the frontend bundle and installs backend production dependencies.
The final image utilizes Bun to serve the compiled JavaScript build of the backend and the pre-built frontend bundle.

```yaml [packages/backend/Dockerfile]
// [!include ~/../../packages/backend/Dockerfile]
```

### Configuration

You can customize the `PORT` variable at runtime, by passing it to the `docker run` command with the `-e` flag:

```sh
docker run -d -p 5000:5000 -v privatefolio-data:/app/data -e PORT=5000 --name privatefolio privatefolio
```

### Data Persistence

All data is stored in the `/app/data` directory inside the container, which is mounted to a persistent volume called `privatefolio-data`. This ensures that your data is persisted even if the container is stopped or removed.

To backup your data, you can use the Docker volume commands:

```sh
docker volume inspect privatefolio-data # View volume info
```

### Logs

To view logs from the container:

```sh
docker logs privatefolio
```

To follow the logs in real-time:

```sh
docker logs -f privatefolio
```

### Official deployment

We are currently deploying to GitHub Container Registry (GHCR) through a GitHub Actions workflow.
This deployment system provides continuous deployment for all tagged releases and branches, with Discord notifications for deployment status updates.

```sh
docker pull ghcr.io/privatefolio/privatefolio:latest
```

See all versions at [ghcr.io/privatefolio/privatefolio](https://github.com/privatefolio/privatefolio/pkgs/container/privatefolio).

Available image tags:

* `latest`: Latest tagged release
* `v*.*.*`: Tagged releases (e.g., v2.0.0-beta.40)
* `******`: Git commit (e.g. 1da1a8f)

To run the official image:

```sh
docker run -d -p ${PORT:-5555}:${PORT:-5555} -v privatefolio-data:/app/data --name privatefolio ghcr.io/privatefolio/privatefolio:latest
```

Learn more on [self-hosting with Docker](./self-hosting-with-docker.md).

### Workflow file

```yaml [.github/workflows/publish-docker-image.yml]
// [!include ~/../../.github/workflows/publish-docker-image.yml]
```


## Frequently Asked Questions

### Is Privatefolio really free?

Yes! Privatefolio is completely free to use, free to modify and free to distribute, its source code is available under the **GNU AGPL-3.0** license.

However, since Privatefolio is extensible, just like in App Store or Google Play, you may encounter extensions that require a one-time fee or a paid subscription.

### Can I self-host Privatefolio?

Yes! The easiest way to self-host is to either install any of the [desktop apps](https://privatefolio.xyz/downloads) on your computer, or to [run the Docker image](./self-hosting-with-docker) on your server.

### Can I contribute to the project?

Absolutely! Open-source and collaboration are at the core of our mission. You can develop custom extensions and earn money doing so.

Extensions can range from support for new csv formats, new price providers, advanced analytics, AI features (like voice, or deep research agents) and much more.

You can provide suggestions on how we can improve the app, or help with documentation. Check out our [developer quickstart on GitHub](https://github.com/privatefolio/privatefolio?tab=readme-ov-file#for-developers) and make sure to join our [Discord server](https://discord.gg/YHHu9nK8VD).

### Is there a premium plan?

Yes! The app is free, but we offer a premium plan that includes a faster cloud machine, higher AI limits and priority support. This helps us maintain and improve the project.

### Is Privatefolio like WordPress?

Exactly! Like WordPress, Privatefolio is open-source, self-hostable, and highly extensible. Anyone can develop extensions (i.e. plugins) to add new features. Similarly to WordPress's business model, we offer a premium plan that includes a faster cloud machine, higher AI limits and priority support.

### What is the AGPL-3.0 license?

The AGPL-3.0 (GNU Affero General Public License) is a strong copyleft license that ensures the software remains free and open. Here are the key freedoms it provides:

* **Freedom to Use**: You can use the software for any purpose, including commercial use.
* **Freedom to Study and Modify**: You can study how the program works and modify it to suit your needs, including for commercial purposes.
* **Freedom to Distribute Copies**: You can redistribute copies of the original program.
* **Freedom to Distribute Modified Versions**: You are allowed to distribute your modified versions, including for profit. However, if you run a modified version of the software on a server and allow others to interact with it, you must provide the source code of the modified version to those users.

This helps maintain the open ecosystem while allowing commercial use through our premium offerings.

Learn more by reading our [license on GitHub](https://github.com/privatefolio/privatefolio/blob/main/LICENSE).


## Getting started \[How to build Privatefolio from source]

### Prerequisites

To build & run the project, you need to have the following build dependencies installed:

```sh
node -v
# v22.15.0
npm -v
# 11.3.0
yarn -v
# 1.22.22
bun -v
# 1.2.12
```

#### Node.js

It's recommended to install Node.js through NVM (Node Version Manager), and to install Yarn through NPM.

On Windows, get it from [coreybutler/nvm-windows](https://github.com/coreybutler/nvm-windows).
On Linux, get it from [nvm-sh/nvm](https://github.com/nvm-sh/nvm).

Afterwards, upgrade NPM and install Yarn:

```sh
npm install -g npm
npm install -g yarn
```

#### Windows

Install the latest version of [Python](https://www.python.org/downloads/) and add it to your PATH.

```ps
python --version
# 3.13.3
```

Afterwards, install Bun:

```ps
powershell -c "irm bun.sh/install.ps1|iex"
```

#### Ubuntu

Ensure these development dependencies are installed:

```sh
sudo apt update && sudo apt -y upgrade
sudo apt install libnss3-dev libatk1.0-0 libatk-bridge2.0-0 libgdk-pixbuf2.0-0 libgtk-3-0 -y
```

Afterwards, install Bun:

```sh
curl -fsSL https://bun.sh/install | bash
```

### Install

Before we can build the project from source, we also need to install the project dependencies:

```sh
yarn
yarn build
```

On Ubuntu, you need to install the set the permissions for the chrome-sandbox file:

```sh
sudo chown root:root packages/electron/node_modules/electron/dist/chrome-sandbox
sudo chmod 4755 packages/electron/node_modules/electron/dist/chrome-sandbox
```

### Development

Run the project in development mode, to see your code changes in real-time.

```sh
yarn dev
```

### Build native apps

To build the native apps, run any of the following commands:

```sh
# desktop apps
yarn bundle:win
yarn bundle:linux
yarn bundle:mac
yarn bundle:mac-x64
# mobile apps
yarn bundle:android
yarn bundle:ios
```

Now you can run the artifacts from these paths:

* Windows `./packages/electron/out/Privatefolio\ Setup\ 2.0.0-beta.44.exe`
* Linux `sudo dpkg -i ./packages/electron/out/privatefolio-electron_2.0.0-beta.44_amd64.deb`
* MacOS Arm64 `./packages/electron/out/Privatefolio-2.0.0-beta.44-arm64.dmg`
* MacOS Intel `./packages/electron/out/Privatefolio-2.0.0-beta.44.dmg`
* iOS `./packages/expo/out/ios/Privatefolio.ipa`
* Android `./packages/expo/out/android/app-release.apk`

### Build docker image

```sh
yarn docker:build
```

### Testing

After making changes to the code, you can run the tests to see if anything broke.

```sh
yarn test
yarn test:bun # special test that has to run separately to ensure sqlite3 is compatible with bun:sqlite
yarn test:ci # running all tests in CI mode
```

To run a single test file:

```sh
cd packages/backend
yarn test <test-file>
yarn test test/tags/tags-api.test.ts
```

### Tips & Know-how

#### Add a package as a dependency to another

Note: you need to specify a version due to [this bug](https://github.com/yarnpkg/yarn/issues/4878#issuecomment-386607832).

```sh
yarn workspace privatefolio-frontend add privatefolio-backend@0.2.0
yarn workspace privatefolio-frontend remove privatefolio-backend
yarn workspaces info
```

#### Add a dependency to a package

```sh
yarn workspace privatefolio-frontend add react
yarn workspace privatefolio-frontend remove react
```

#### NPM utils

```sh
npm list ms # List all packages that depend on ms
```

#### Yarn utils

```sh
yarn list ms # List all packages that depend on ms
yarn upgrade-interactive # Upgrade all packages to the latest version
yarn cache clean # Clean the cache
```

### Troubleshooting

#### Electron

Data is persisted in the following directories:

1. Windows:
   * Updater logs: `C:\Users\daniel\AppData\Local\privatefolio-electron-updater`
   * Electron logs: `C:\Users\daniel\AppData\Roaming\Privatefolio\logs`
   * User data: `C:\Users\daniel\AppData\Roaming\Privatefolio\data`
   * App config: `C:\Users\daniel\AppData\Roaming\Privatefolio\config.json`
   * App code: `C:\Users\daniel\AppData\Local\Programs\Privatefolio`

2. Linux:
   * Electron logs: `~/.config/Privatefolio/logs`
   * User data: `~/.config/Privatefolio/data`
   * App config: `~/.config/Privatefolio/config.json`

You can also package the app without building the binaries:

```sh
cd packages/electron
yarn package
```

And run the executable `./out/Privatefolio-win32-x64/Privatefolio.exe`.


import { Callout } from 'vocs/components'

## Installation

To install the Privatefolio desktop app, you can either download the apps from [privatefolio.xyz/downloads](https://privatefolio.xyz/downloads) or from [GitHub releases](https://github.com/privatefolio/privatefolio/releases).

Each release contains the binaries for Windows, Linux and Mac.

On Windows, you can run the `Privatefolio-<version>.Setup.exe` executable directly.

On Linux, you can run `sudo dpkg -i privatefolio_<version>_amd64.deb` to install the package.

On Mac, download the dmg for your platform and run the installer.

<Callout type="info">
  Privatefolio Desktop is a full standalone app with a built-in backend server, it has everything you need.
</Callout>

<Callout type="note">
  Using the PrivateCloud™ service is completely optional, but useful: for example using Privatefolio on mobile devices which 1) cannot run the backend module at the moment and 2) can run into battery restrictions leading to poor UX.
</Callout>


## Self-hosting with Docker

Deploying with Docker using the official deployment of Privatefolio which is available on GitHub Container Registry (GHCR).

### Prerequisites

Before we get started you must have Docker installed:

```sh
docker --version
# Docker version 28.3.2, build 578ccf6
```

If you don't have it, get it from [docker.com](https://docs.docker.com/get-docker/).

### 1. Pull the Image

```sh
docker pull ghcr.io/privatefolio/privatefolio:latest
```

This fetches the latest official release from GHCR.

:::tip
To install an older version, replace the `latest` tag with a version tag or git commit hash.

```sh
docker pull ghcr.io/privatefolio/privatefolio:v2.0.0-beta.40
docker pull ghcr.io/privatefolio/privatefolio:4a678c3
```

See all versions at [ghcr.io/privatefolio/privatefolio](https://github.com/privatefolio/privatefolio/pkgs/container/privatefolio).
:::

### 2. Run the Container

```sh
docker run -d \
  -p ${PORT:-5555}:5555 \
  -v privatefolio-data:/app/data \
  --name privatefolio \
  ghcr.io/privatefolio/privatefolio:latest
```

Explanation:

* `-d`: Run in detached mode.
* `-p ${PORT:-5555}:5555`: Map the host port (default 5555) to the container port 5555. Adjust the host port if needed.
* `-v privatefolio-data:/app/data`: Mount a named volume `privatefolio-data` to `/app/data` inside the container for persistent data storage.
* `--name privatefolio`: Assign a name to the container.

### 3. Access the app

The app will be available on the port you set in `docker run` (defaulting to `5555`):

Visit [`http://localhost:5555`](http://localhost:5555) in your browser.

### Data Persistence

All data is stored in the `/app/data` directory inside the container, which is mounted to a persistent volume called `privatefolio-data`. This ensures that your data is persisted even if the container is stopped or removed.

To backup your data, you can use the Docker volume commands:

```sh
docker volume inspect privatefolio-data # View volume info
```

### Logs

To view logs from the container:

```sh
docker logs privatefolio
```

To follow the logs in real-time:

```sh
docker logs -f privatefolio
```

### Upgrading

To upgrade to the latest version of Privatefolio, run:

```sh
docker pull ghcr.io/privatefolio/privatefolio:latest
docker rm -f privatefolio
docker run -d -p ${PORT:-5555}:${PORT:-5555} -v privatefolio-data:/app/data --name privatefolio ghcr.io/privatefolio/privatefolio:latest
```

Your data is safe even when you remove the container, because it is persisted in the `privatefolio-data` volume.

### Delete all personal data

To delete all personal data, run:

```sh
docker rm -f privatefolio
docker volume rm privatefolio-data
```


## Self-hosting with Fly.io

Deploying to Fly.io to self-host Privatefolio on the edge using the official Docker image from GitHub Container Registry (GHCR). Privatefolio includes a `fly.toml` configuration file for easy deployment on this cloud provider.

### Prerequisites

Before we get started you must have Fly.io CLI installed:

```sh
flyctl version
# v0.3.112
```

If you don't have it, get it from [Fly.io](https://fly.io/docs/hands-on/install-flyctl/).

You must also have a Fly.io account ([Sign up](https://fly.io/)).

### 1. Login to Fly.io

```sh
fly auth login
```

### 2. Create the app

Navigate to the root directory of the Privatefolio repository where `fly.toml` is located. Run:

```sh
fly launch --no-deploy
```

* You will be asked if you wish to copy this configuration file to the new app. Answer `y` (yes).
* This command reads the `fly.toml` file and sets up the application on Fly.io based on the configuration.
* `--no-deploy`: We skip the initial deploy because we want to ensure the volume is created first.

### 3. Create a persistent volume

The `fly.toml` specifies a volume mount for data persistence. Create the volume before the first deploy:

```sh
fly volumes create privatefolio-data --size 1
```

* `--size 1`: Specifies the volume size in GB (1 GB is usually sufficient to start).
* You will be prompted to choose a region for the volume. Select the same region as your app for optimal performance.

### 4. Deploy the app

```sh
fly deploy
```

* This command uses the pre-built image specified in `fly.toml` from GHCR and deploys it to the Fly.io platform.
* It respects the settings in `fly.toml`, including environment variables (`PORT=5555`), volume mounts (`privatefolio-data` to `/app/data`), and service configuration (HTTP service on the internal port).

### 5. Access the app

After deployment, `fly deploy` will output the public URL for your application (e.g., `https://privatefolio.fly.dev`). The app will be available at this URL.

Visit your Fly.io app URL in your browser to access Privatefolio.

### fly.toml

This is the configuration file for the Fly.io app.

```yaml [fly.toml]
// [!include ~/../../fly.toml]
```

### Data Persistence

All data is stored in the `/app/data` directory inside the container, which is mounted to a persistent volume called `privatefolio-data`. This ensures that your data is persisted even if the app is redeployed or restarted.

To backup your data, you can use Fly.io volume commands:

```sh
fly volumes list                    # List all volumes
fly volumes show privatefolio-data  # View volume details
```

### Logs

To view logs from your Fly.io app:

```sh
fly logs -a <your-app-name>
```

To follow the logs in real-time:

```sh
fly logs -f -a <your-app-name>
```

### Upgrading

To upgrade to the latest version of Privatefolio, run:

```sh
fly deploy
```

Fly.io will pull the latest image from GHCR and deploy the new version.

### Monitoring and Management

Use `flyctl` to manage your deployed app:

* App status: `fly status -a <your-app-name>`
* Machine status: `fly machine list -a <your-app-name>`
* Logs: `fly logs -a <your-app-name>`
* SSH access: `fly ssh console -a <your-app-name>`
* Scale: `fly scale count 2 -a <your-app-name>` (increase instances)

### Delete all personal data

To delete all personal data and remove your Fly.io deployment:

```sh
# Delete the app (this also removes associated volumes)
fly apps destroy <your-app-name>

# Or manually delete volume first, then app
fly volumes destroy privatefolio-data -a <your-app-name>
fly apps destroy <your-app-name>
```


## Vision

Privatefolio was born out of necessity, after growing frustrated with the limitations of existing investment portfolio trackers.

SaaS products offer great user experience & analytics, but you cannot extend these apps. The only thing you can do is to "upvote the next broker to be supported".

There are open-source alternatives, but they do not come close to their SaaS counterparts in terms of UX.

**What if we could change that?** What if we could do for investing and personal finance what WordPress did for blogging?

## Meet Privatefolio \[The AI Wealth Manager - A free\* and open-source toolkit for financial empowerment]

**Privatefolio is a tool you own**. It allows you to collect, analyze and visualize your financial data.

You can use it in conjunction with LLMs and AI agents to gain a deeper understanding of where you are at, and to plan for the future.

Privatefolio is for: 1) Investment portfolios, 2) Accounting, 3) Tax reporting & planning, 4) Financial intelligence, 5) Privacy, 6) AI workflows, 7) Expense tracking, 8) Budgeting, 9) Cashflow predictions, 10) Retirement planning, 11) FIRE, 12) Volatility simulations, 13) Risk management and much more.

Due to its open-source nature and its *GNU AGPL-3.0* license, it has the necessary properties to be used as an operating system for one's finances (individual or business).
This is achievable if we create a thriving ecosystem of extensions (paid and free), just like WordPress has.

Come say Hello 👋 on [Discord](https://discord.gg/YHHu9nK8VD), where we build in public.


import { Callout } from 'vocs/components'

## Web deployment

Deploying Privatefolio on the web involves hosting the build output of the `@privatefolio/frontend` package.

<Callout type="info">
  Just like Privatefolio v1, in the future, you will be able to run the `@privatefolio/backend` package inside the browser using web workers. Web deployments will then encompass both. Help us make it a reality with
  [#27](https://github.com/privatefolio/privatefolio/issues/27).
</Callout>

### Build

Once you setup the project and [its prerequisites](./getting-started.md), you can build the frontend.

```bash
yarn build
# output dir: packages/frontend/build

```

### Deploy

#### with `serve`

```bash
npx serve -p 8080 -C packages/frontend/build
```

#### with Cloudflare Pages

```bash
yarn wrangler pages deploy packages/frontend/build --project-name=privatefolio
```

### Official deployment

We are currently deploying to Cloudflare Pages through a GitHub Actions workflow.
This deployment system provides continuous deployment for all branches and pull requests, with Discord notifications for deployment status updates.

Production deployment URL: [`https://privatefolio.app`](https://privatefolio.app) <br />
Preview deployments URLs: `https://<deployment-id>.privatefolio-com.pages.dev` <br />
See latest deployments at:
[github.com/privatefolio/privatefolio/deployments](https://github.com/privatefolio/privatefolio/deployments)

<Callout type="note">
  Unlike other production deployments, the latest web deployment corresponds to the latest commit on the `main` branch, not the latest tagged release.
</Callout>

### Workflow file

```yaml [.github/workflows/publish-web-app.yml]
// [!include ~/../../.github/workflows/publish-web-app.yml] 
```


## Blog

::blog-posts


## Privatefolio v2 is here!

![Cover photo](https://paragraph.com/_next/image?q=75\&url=https%3A%2F%2Fstorage.googleapis.com%2Fpapyrus_images%2F0f15504d2b8e5dbe72abd2ba31fb5771.jpg\&w=3840)

I’m happy to announce that Privatefolio v2 is available as a public beta. This release is a meaningful step towards achieving a local-first and privacy focused portfolio manager that is on par with popular SaaS alternatives.

### What’s new?

* Desktop apps – they are [available to download](https://privatefolio.xyz/downloads) for Windows, Linux, and Mac. You can install it and let it run in the background – no need to keep a browser tab open anymore.
* Cloud service – PrivateCloud™️ offers a free & [premium tier](https://privatefolio.xyz/pricing) and it's ideal for users that wish to access the app from their smartphone or do not wish to use the desktop apps.
* Self-hosting – for the self sovereign individual, deploying a self-hosted instance of Privatefolio can be done in \<5 minutes, using Docker. Make use of the extensive [documentation](https://github.com/privatefolio/privatefolio/blob/main/docs/DOCKER_DEPLOY.md) in our GitHub repository and make sure to read the [fly.io](https://fly.io) deployment example.
* SQL – the core of Privatefolio has changed, while you can still access v1 which is powered by PouchDB, a no-sql database available in the browser, in v2 we leverage the very familiar SQL language with its most popular implementation: SQLite. Developers and power users can make use of it in building powerful analytics for investment portfolios.
* Trades – a new primitive. Alongside audit logs and transactions, users can now inspect all their historical trades, including data like cost basis and profit & loss.
* Time travel – inspect your portfolio and your trades at any given time in the past. [See it on the live demo](https://1.privatefolio.app/l/0/?tab=pnl) (don't forget to select the Inspect cursor in the chart toolbar).
* Pro chart – did you ever want to use indicators and drawing tools on your own data? [Now you can](https://1.privatefolio.app/l/0/pro-chart).
* Extensions – the best time to extend Privatefolio is now! [Extensions have their own page](https://1.privatefolio.app/l/0/extensions), clear documentation, and plenty of examples. Developers are invited to create & publish their own extensions and earn a share of the revenue (from the cloud subscriptions). In the future they will be able to sell extensions to other users for a flat fee or a recurring subscription.

### A picture is worth a thousand words

*Time travel feature (inspecting trades on Dec 07, 2024)*\
![Time travel](https://paragraph.com/_next/image?q=75\&url=https%3A%2F%2Fstorage.googleapis.com%2Fpapyrus_images%2F6f7356d6894963f0070d810ceae1f0da.png\&w=3840)

*Pro chart (using the drawing tools on your networth data)*\
![Pro chart](https://paragraph.com/_next/image?q=75\&url=https%3A%2F%2Fstorage.googleapis.com%2Fpapyrus_images%2F10ca74cfd739b50cd681b02d229fa134.png\&w=3840)

*Extensions*\
![Extensions](https://paragraph.com/_next/image?q=75\&url=https%3A%2F%2Fstorage.googleapis.com%2Fpapyrus_images%2Fa6061ddadadb2bf570843a293fae2538.png\&w=3840)

### We ❤️ open-source and privacy

Privatefolio is built for developers! From the choice of license to the choice of technologies. You can think of it as a Wordpress-like platform. Are you familiar with TypeScript, React, Bun, and Electron? Then check out our [developer guide on GitHub](https://github.com/privatefolio/privatefolio?tab=readme-ov-file).

Key Points of the GNU AGPLv3 License:

* Freedom to Use: You can use the software for any purpose, including commercial use.
* Freedom to Study and Modify: You can study how the program works and modify it to suit your needs, including for commercial purposes.
* Freedom to Distribute Copies: You can redistribute copies of the original program, helping others benefit from it.
* Freedom to Distribute Modified Versions: You are allowed to distribute your modified versions, including for profit. However, if you run a modified version of the software on a server and allow others to interact with it, you must provide the source code of the modified version to those users.

### What’s next?

In the next few versions expect features like Push notifications, Reports (weekly or monthly reports containing a summary of what has changed in your portfolio in terms of value, volatility, risk, etc.), Cloud syncing and, of course, more extensions (depending on what users find most valuable).

Help shape the future of this project by joining the discussion on [Discord](https://discord.gg/YHHu9nK8VD) and [Twitter](https://x.com/PrivatefolioApp).\
Try it now at [privatefolio.app](https://privatefolio.app) or [privatefolio.xyz/downloads](https://privatefolio.xyz/downloads).

***

*This post was originally published on [Paragraph](https://paragraph.com/@privatefolio/privatefolio-v2-is-here).*


## What is Privatefolio? \[The Free\* and Open-source Portfolio Tracker — All your crypto assets in one place]

::authors

![Blog post cover](https://paragraph.com/_next/image?url=https%3A%2F%2Fstorage.googleapis.com%2Fpapyrus_images%2F7de6f9ee678322de019bebee54ce0f03.jpg\&w=1080\&q=75)

Privatefolio lets you track your assets across blockchains and exchanges.

Import your data and let the app do the rest — calculate your historical net worth, profits, losses, taxes and more.

### How?

Privatefolio is a local-first app, there is no server your data needs to travel to; it all happens right in your browser.

It leverages three kinds of public APIs:

1. APIs for asset prices: Binance, Coinbase & DeFi-Llama — Redstone, Pyth coming soon.
2. APIs for asset metadata: Coingecko (such as logo images, websites, descriptions).
3. APIs for user data: Etherscan, Binance Account API.

It also makes use of [IndexedDB](https://developer.mozilla.org), which allows for high amounts of data to be stored in the browser. How much? Chrome and Chromium-based browsers allow up to 80% of disk space, i.e. on a 500 GB laptop a web app can use a maximum of 400 GB.

### Does it scale?

Using public APIs can be challenging; for example Coingecko’s stingy free tier. Nonetheless, with the use of a local cache (which works ok for metadata) we can get good user experience.

Fetching historical asset prices using Coinbase & Binance scales even if you have transacted hundreds of assets — for example, if you fetch the daily candles of 100 assets for the past 6 years within the same minute, you would only use 10% of Binance’s rate limit.

Fetching user data using Etherscan works great even for users with millions of transactions. Their public API allows up to 5 calls per second and 1 call can retrieve up to 10,000 records. Binance on the other hand is quite limiting and syncing an account can take many hours, but this is a challenge shared by all the portfolio trackers on the market.

Read more about rate limits on [GitHub](https://github.com).

The answer is yes.

### Why?

Back in November 2023 I was looking for other options beyond [delta.app](https://delta.app) to use as a portfolio tracker, because:

1. I have to check 3 different apps to get an overview of my assets.
2. Delta reports my Binance balances inaccurately (it ignores Futures data).
3. I cannot create a pull request and extend Delta.
4. Other open-source alternatives like [rotki.com](https://rotki.com) lack good UI/UX.

In October 2023, the TradingView team released a plugin system for their amazing open-source charting library called [lightweight-charts](https://github.com), and this library is what powers Privatefolio today and what made features like measuring an arbitrary net worth change possible:

*Demo of the Measure cursor*
![Measure cursor demo](https://paragraph.com/_next/image?url=https%3A%2F%2Fstorage.googleapis.com%2Fpapyrus_images%2Fcff98241525c00af2469014a9753a356.png\&w=1080\&q=75)

### What’s next?

If there is enough interest from people to use this product I will continue hacking on it.

You can reach out via email at **[hello@danielconstantin.net](mailto\:hello@danielconstantin.net)**, start a discussion on [Discord](https://paragraph.xyz), or message me on [Twitter](https://twitter.com).

Please share any positive feedback, negative feedback, thoughts or ideas.

### Consider donating through Gitcoin

Privatefolio is participating in **GG20**. Donations will be matched using a quadratic funding mechanism, hence, small donations can have a big impact.

GG20 takes place from **April 26 - May 7, 2024**.

***

*This post was originally published on [Paragraph](https://paragraph.com/@privatefolio/what-is-privatefolio).*