rikdom

rikdom

Portable, local-first wealth portfolio schema + storage toolkit.

rikdom is designed so your portfolio data can last for years as plain JSON files, independent of any broker app or SaaS dashboard.

Why The Name "rikdom"

rikdom is a Norwegian word meaning "wealth" (or "riches"). The name reflects the project goal: treat wealth data as durable, long-lived information, not a locked product database.

Why Now

With coding agents and LLMs, it is much easier to build your own asset management software and adapt it to your needs over time. rikdom focuses on the durable layer beneath that iteration: a solid foundation for storing and evolving financial data, plus a plugin system you can extend with coding agents and enrich with reusable open-source plugins.

What It Solves

• Define a portfolio for a person or company.
• Track holdings across stocks, REITs, funds, real estate, cash equivalents, digital assets and cryptocurrencies.
• Model recurring operations (monthly/yearly tasks) and keep an auditable "last done" history.
• Extend asset types with country-specific classes, metadata, and typed instrument attributes.
• Persist data in simple disk files (JSON + JSONL).
• Archive or transfer data with checksum-verified rikdom-export bundles.
• Generate static dashboard and deep-dive reports for allocation and progress over time.
• Ingest provider statements through community plugins.
• Query external market data through optional connector plugins, with provider rules and authentication handled by each adapter.

Core Principles

• Local-first: data stays in your folder.
• Durable formats: JSON schema and line-delimited snapshots.
• Extensible by design: metadata and extensions fields.
• Agent-friendly: explicit schema + instructions for Codex/Claude.

How rikdom differs from Ghostfolio and Wealthfolio

rikdom is not trying to be another full investment app. It is a schema + CLI + plugin foundation focused on durability, portability, and auditable local files.

Practical difference:

• Choose rikdom when you want open contracts and file-level control first.
• Choose Ghostfolio/Wealthfolio when you want a ready-made end-user app experience first.
• Combine them when needed: keep rikdom as your canonical data layer and export/sync to other tools via plugins.

Information Flow

flowchart TD
  U["User input"] --> C["CLI commands"]
  S["Provider statements"] --> P["Plugins"]
  P --> C

  D["External data services"] --> DC["Connector plugins"]
  C -->|Explicit connector query| DC
  DC --> Q["JSON with acquisition provenance"]

  C --> V["Schema validation"]
  V --> E["Event ledger activities"]
  E --> T["Current state portfolio"]
  E --> R["Projections"]
  T --> R

  R --> Z["Visualization dashboard"]
  E --> L["LLM reasoning"]
  R --> L
  T --> L
  Q -->|User or agent supplies external context| L

  L --> A["Insights planning and next actions"]

Connector JSON gives users, scripts, and coding agents external evidence with the connector plugin identity and retrieval time. The LLM reasoning step represents analysis performed by an external agent; Rikdom does not invoke an LLM or feed query results into portfolio calculations automatically.

Repository Structure

• schema/ JSON schemas and default asset types
• data/ local workspace files (portfolio.json, snapshots.jsonl, fx_rates.jsonl, import_log.jsonl), gitignored
• data/portfolio_registry.json optional multi-portfolio registry (main, paper, retirement, etc.)
• data/portfolios/<name>/ per-portfolio isolated data files when registry mode is used
• data-sample/ tracked starter templates for workspace bootstrapping (see storage layout)
• src/rikdom/ Python package (CLI, validation, import pipeline, visualization)
• docs/ schema, storage, plugin docs, and execution plans
• plugins/ local plugin implementations and manifests
• scripts/ helper automation scripts (e.g., GitHub issue publishing)
• tests/ unit and integration tests
• out/ generated artifacts (e.g., dashboard/report output)
• .codex/ Codex instruction files
• .claude/ Claude instruction files
• ROADMAP.md phased roadmap and execution priorities

Quick Start

1. Install uv.

2. Sync dependencies and bootstrap a sample workspace:

   make sync
   make bootstrap
   

3. Validate, snapshot, and visualize:

   make validate
   make snapshot
   make viz
   

   Open out/dashboard.html in a browser.

For a guided walkthrough see the first portfolio tutorial.

External data connectors

Use an external/connector plugin to query market data independently of your portfolio files. Each plugin owns its provider operations, authentication, and REST or Model Context Protocol (MCP) client. Queries return JSON with acquisition provenance without importing transactions or updating holdings. The brapi plugin is one example; its capabilities, configuration, and usage are documented in its own directory.

See query external data for the workflow and connector architecture for the boundary between acquisition and planned normalized enrichment.

Documentation

Full documentation is organized along the Diataxis framework at docs/index.md:

• Tutorials — your first portfolio, author your first plugin.
• How-to guides — import a statement, query external data, run a migration, compute performance, and more.
• Reference — CLI, schemas, plugin manifest & hooks, export bundle format.
• Explanation — schema design, plugin architecture, calculation trust, storage durability.

Common Dev Tasks

make lint
uv run python -m unittest tests.test_cli_reconcile -v

Run focused tests locally and use the pull request's CI run for the full suite. See Contributing for testing guidance.

Community plugin showcase

Plugin quick commands:

make plugins-list
make import-sample
make viz
make storage-sync

Portfolio view plugin (quarto-portfolio-report) preview:

Trust, source boundaries, and manual corrections

Imports preview changes, history coverage, and quality findings before writing. Add --reconcile to a successful import for JSON/Markdown trust artifacts. Manual events and immutable corrections work through validated local JSON. Correction-bearing portfolios use schema 2.0.0; uncorrected 1.x remains readable. Older raw-ledger calculators are not supported for corrected data.

Core calculations require an explicit reporting currency and consume normalized source facts. Plugins own provider operations, regional identifiers and catalog rules, parsing conventions, and report presentation. Cached FX is the default; acquisition requires an explicitly selected connector, for example rikdom snapshot --fx-provider frankfurter.

AI Agent Skills

• .codex/SKILL.md
• .codex/skills/rikdom-portfolio-analyst/SKILL.md
• .codex/skills/rikdom-extensibility-engineer/SKILL.md
• .claude/CLAUDE.md

These files guide coding agents to safely analyze and evolve your data model.

Contributing

See CONTRIBUTING.md for development setup, testing expectations, and pull request guidelines.

Project roadmap: ROADMAP.md

License

MIT (see LICENSE).