# patan4ik/kraken-portfolio-tracker architecture

> Architecture diagram of the GitHub repository patan4ik/kraken-portfolio-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/patan4ik/kraken-portfolio-tracker
- Repository: https://github.com/patan4ik/kraken-portfolio-tracker

## Overview

#### Purpose and Entrypoints
Kraken Portfolio Tracker is a Python 3.11+ CLI application for fetching Kraken account data, persisting it locally, and generating offline portfolio and ledger analysis. Primary entrypoints are `start.py` for setup/basic refresh and `update.py` for validated incremental ledger updates plus downstream recomputation. Report modules can also be invoked directly under `src/`.

#### Kraken Access and Credential Boundary
`src/api.py` encapsulates interaction with the external Kraken API for live balances, prices, and ledger retrieval. Credentials are resolved separately by `src/keys.py`, supporting system keyring, local key file, or environment variables. `src/config.py` centralizes runtime locations/settings, keeping API secrets and provider access outside analytical modules.

#### Ledger Ingestion and Durable Cache
`src/ledger_loader.py` incrementally downloads Kraken ledger pages/date ranges and maintains the raw local ledger cache. `src/storage.py` is the persistence boundary: SQLite holds normalized/full ledger payloads in `balances_history/ledger.db`, while JSON and CSV files support caching and exports. The intended steady-state reporting path is SQLite, not live API calls.

#### Balance Snapshot Pipeline
`src/balances.py` obtains current balances and prices, aggregates available and staked holdings, and writes daily portfolio snapshots/history. This live-data path feeds reconciliation and complements the historical ledger database; it is distinct from ledger-derived cost-basis calculation.

#### Update Orchestration and Validation
`update.py` plans missing ledger date ranges, supports dry runs and paging/rate-delay controls, then coordinates ingestion, balance refresh, summary generation, and reconciliation. `src/validators.py` performs preflight validation of database/schema/API-key conditions before mutation. `start.py` provides the simpler initial workflow, key setup, snapshot refresh, and optional ledger update.

#### Portfolio Analytics and Reconciliation
`src/portfolio_summary.py` recomputes FIFO/average cost basis from the complete stored ledger each run, normalizing Kraken wallet suffixes and excluding internal transfers. It also derives EMA/trend-based forecasts. `src/balance_reconciliation.py` compares ledger-derived holdings with the current balance snapshot and writes tolerance-based mismatch results. Core outputs are materialized as local CSV artifacts rather than served over a network.

#### Report Generation
SQLite-backed reporting is partitioned by analysis use case: EUR spend aggregation in `src/ledger_eur_report.py`, acquisitions in `src/ledger_asset_report.py`, and disposals/proceeds/fees in `src/ledger_sell_report.py`. `src/portfolio_summary_report.py` converts computed portfolio metrics into enriched sell-target, trend, risk, and signal CSV output.

#### Runtime and Delivery
The runtime is local Python with SQLite, filesystem CSV/JSON caches, optional OS credential keyring, and the Kraken API as the sole stated external service. GitHub Actions workflows under `.github/workflows/` provide CI. Windows distribution packages `start.py` and `update.py` as PyInstaller executables; no web server or hosted application infrastructure is indicated.

Main entry points: [`update.py`](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/update.py) (Incremental update CLI), [`start.py`](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/start.py) (Initial setup CLI), [`src/balances.py`](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/balances.py) (Balance snapshot pipeline), [`src/storage.py`](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/storage.py) (Persistence boundary)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["CLI Workflows"]
  node_start["Initial setup CLI<br/>Python entrypoint<br/>[start.py]"]
  node_update["Incremental update CLI<br/>Python entrypoint<br/>[update.py]"]
end

subgraph group_access["Access &amp; Validation"]
  node_validators["Preflight validation<br/>[validators.py]"]
  node_config["Runtime configuration<br/>settings<br/>[config.py]"]
  node_keys{{"Credential resolver<br/>credential boundary<br/>[keys.py]"}}
  node_kraken_api{{"Kraken API client<br/>external API adapter<br/>[api.py]"}}
end

subgraph group_ingestion["Data Ingestion &amp; Storage"]
  node_ledger_loader["Incremental ledger loader<br/>ingestion<br/>[ledger_loader.py]"]
  node_balances["Balance snapshot pipeline<br/>[balances.py]"]
  node_storage["Persistence boundary<br/>storage adapter<br/>[storage.py]"]
  node_ledger_db[("Ledger database<br/>SQLite")]
  node_snapshot_history["Snapshot history<br/>local CSV/JSON"]
end

subgraph group_analytics["Analytics &amp; Reports"]
  node_portfolio_summary["Portfolio recomputation<br/>analytics pipeline"]
  node_reconciliation["Balance reconciliation<br/>analytics"]
  node_eur_report["EUR spend report<br/>SQLite report"]
  node_asset_report["Acquisitions report<br/>SQLite report"]
  node_sell_report["Disposals report<br/>SQLite report"]
  node_summary_report["Portfolio signals report<br/>report generator"]
  node_csv_outputs["Offline CSV outputs<br/>materialized artifacts"]
end

subgraph group_delivery["Delivery"]
  node_ci["GitHub Actions CI<br/>CI workflows"]
  node_windows_packages["Windows executables<br/>PyInstaller distribution"]
end

node_start -->|"sets up credentials"| node_keys
node_start -->|"refreshes"| node_balances
node_start -.->|"optionally invokes"| node_update
node_update -->|"preflight"| node_validators
node_update -->|"plans and runs"| node_ledger_loader
node_update -->|"refreshes"| node_balances
node_update -->|"recomputes"| node_portfolio_summary
node_update -->|"runs"| node_reconciliation
node_config -.->|"configures locations"| node_keys
node_keys -->|"supplies credentials"| node_kraken_api
node_ledger_loader -->|"fetches ledger pages"| node_kraken_api
node_ledger_loader -->|"persists"| node_storage
node_balances -->|"fetches balances and prices"| node_kraken_api
node_balances -->|"writes snapshots"| node_storage
node_storage -->|"stores ledger"| node_ledger_db
node_storage -->|"writes cache/history"| node_snapshot_history
node_ledger_db -->|"complete ledger"| node_portfolio_summary
node_ledger_db -->|"query source"| node_eur_report
node_ledger_db -->|"query source"| node_asset_report
node_ledger_db -->|"query source"| node_sell_report
node_portfolio_summary -->|"ledger-derived holdings"| node_reconciliation
node_snapshot_history -->|"current snapshot"| node_reconciliation
node_portfolio_summary -->|"portfolio metrics"| node_summary_report
node_reconciliation -->|"mismatches"| node_csv_outputs
node_eur_report -->|"exports"| node_csv_outputs
node_asset_report -->|"exports"| node_csv_outputs
node_sell_report -->|"exports"| node_csv_outputs
node_summary_report -->|"exports"| node_csv_outputs
node_windows_packages -.->|"packages"| node_start
node_windows_packages -.->|"packages"| node_update

click node_start "https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/start.py"
click node_update "https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/update.py"
click node_validators "https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/validators.py"
click node_config "https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/config.py"
click node_keys "https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/keys.py"
click node_kraken_api "https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/api.py"
click node_ledger_loader "https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/ledger_loader.py"
click node_balances "https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/balances.py"
click node_storage "https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/storage.py"
click node_portfolio_summary "https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/portfolio_summary.py"
click node_reconciliation "https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/balance_reconciliation.py"
click node_eur_report "https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/ledger_eur_report.py"
click node_asset_report "https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/ledger_asset_report.py"
click node_sell_report "https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/ledger_sell_report.py"
click node_summary_report "https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/portfolio_summary_report.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_start,node_update toneBlue
class node_validators,node_config,node_keys,node_kraken_api toneAmber
class node_ledger_loader,node_balances,node_storage,node_ledger_db,node_snapshot_history toneMint
class node_portfolio_summary,node_reconciliation,node_eur_report,node_asset_report,node_sell_report,node_summary_report,node_csv_outputs toneRose
class node_ci,node_windows_packages toneIndigo
```

## Components

### CLI Workflows

- [Initial setup CLI](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/start.py): Python entrypoint · Sets up keys, refreshes snapshots, and can start a ledger update. · `start.py`
- [Incremental update CLI](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/update.py): Python entrypoint · Validates, plans ledger gaps, and runs downstream recomputation. · `update.py`

### Access & Validation

- [Preflight validation](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/validators.py): validation · Checks database, schema, and API-key conditions before mutation. · `src/validators.py`
- [Runtime configuration](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/config.py): settings · Centralizes local locations and runtime settings. · `src/config.py`
- [Credential resolver](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/keys.py): credential boundary · Loads Kraken credentials from keyring, file, or environment. · `src/keys.py`
- [Kraken API client](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/api.py): external API adapter · Retrieves live balances, prices, and ledger data. · `src/api.py`

### Data Ingestion & Storage

- [Incremental ledger loader](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/ledger_loader.py): ingestion · Downloads paged ledger ranges into the local cache. · `src/ledger_loader.py`
- [Balance snapshot pipeline](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/balances.py): snapshot pipeline · Aggregates available and staked holdings with current prices. · `src/balances.py`
- [Persistence boundary](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/storage.py): storage adapter · Manages SQLite ledger data plus JSON and CSV caches. · `src/storage.py`
- **Ledger database**: SQLite · Durable normalized and full Kraken ledger payloads.
- **Snapshot history**: local CSV/JSON · Daily portfolio snapshots and cache artifacts.

### Analytics & Reports

- [Portfolio recomputation](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/portfolio_summary.py): analytics pipeline · Calculates cost basis, holdings, and EMA/trend forecasts from stored ledger data. · `src/portfolio_summary.py`
- [Balance reconciliation](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/balance_reconciliation.py): analytics · Compares ledger-derived holdings against current snapshots. · `src/balance_reconciliation.py`
- [EUR spend report](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/ledger_eur_report.py): SQLite report · `src/ledger_eur_report.py`
- [Acquisitions report](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/ledger_asset_report.py): SQLite report · `src/ledger_asset_report.py`
- [Disposals report](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/ledger_sell_report.py): SQLite report · `src/ledger_sell_report.py`
- [Portfolio signals report](https://github.com/patan4ik/kraken-portfolio-tracker/blob/main/src/portfolio_summary_report.py): report generator · Produces enriched sell-target, trend, risk, and signal CSVs. · `src/portfolio_summary_report.py`
- **Offline CSV outputs**: materialized artifacts · Local analysis, report, and reconciliation outputs.

### Delivery

- **GitHub Actions CI**: CI workflows
- **Windows executables**: PyInstaller distribution · Packages the two CLI entrypoints for Windows.

## Connections

- Initial setup CLI → Credential resolver: sets up credentials
- Initial setup CLI → Balance snapshot pipeline: refreshes
- Initial setup CLI → Incremental update CLI: optionally invokes
- Incremental update CLI → Preflight validation: preflight
- Incremental update CLI → Incremental ledger loader: plans and runs
- Incremental update CLI → Balance snapshot pipeline: refreshes
- Incremental update CLI → Portfolio recomputation: recomputes
- Incremental update CLI → Balance reconciliation: runs
- Runtime configuration → Credential resolver: configures locations
- Credential resolver → Kraken API client: supplies credentials
- Incremental ledger loader → Kraken API client: fetches ledger pages
- Incremental ledger loader → Persistence boundary: persists
- Balance snapshot pipeline → Kraken API client: fetches balances and prices
- Balance snapshot pipeline → Persistence boundary: writes snapshots
- Persistence boundary → Ledger database: stores ledger
- Persistence boundary → Snapshot history: writes cache/history
- Ledger database → Portfolio recomputation: complete ledger
- Ledger database → EUR spend report: query source
- Ledger database → Acquisitions report: query source
- Ledger database → Disposals report: query source
- Portfolio recomputation → Balance reconciliation: ledger-derived holdings
- Snapshot history → Balance reconciliation: current snapshot
- Portfolio recomputation → Portfolio signals report: portfolio metrics
- Balance reconciliation → Offline CSV outputs: mismatches
- EUR spend report → Offline CSV outputs: exports
- Acquisitions report → Offline CSV outputs: exports
- Disposals report → Offline CSV outputs: exports
- Portfolio signals report → Offline CSV outputs: exports
- Windows executables → Initial setup CLI: packages
- Windows executables → Incremental update CLI: packages