KontoPulse

Personal Unified Ledger & Savings Engine

A privacy-focused, local-first personal finance application designed for automated transaction management and comprehensive financial analytics.

📌 Overview

KontoPulse (or simply Pulse) is a modern financial tool built to bridge the gap between bank exports and actionable insights. Unlike cloud-based aggregators that require your credentials, Pulse runs entirely on your machine, ingesting standard CSV exports (currently optimized for mBank) to provide a unified view of your finances.

It solves the common problem of "fragmented money" by treating multiple physical bank accounts as a single logical cash pool, automatically detecting and filtering internal transfers so your analytics remain accurate.

Current Status

The v0.1.0 MVP and frontend refactor milestones are complete. Ongoing work focuses on stabilization, test coverage, and incremental UX improvements. See CHANGELOG.md for the latest shipped features and docs/DECISIONS.md for architectural context.

✨ Current Capabilities

• Privacy First: Your financial data never leaves your machine. Powered by a local SQLite database.
• Smart Import: Idempotent CSV ingestion with archived uploads, handling duplicates and overlaps safely.
• Unified Ledger: Owned accounts are grouped into a cash pool with internal transfers detected and linked.
• Categorization & Review:
  • Rule-based categorization with priority ordering.
  • Review queue for uncategorized or incomplete items.
  • Manual overrides recorded in an audit change log.
• Split Transactions: Splits replace parent reporting while keeping immutable import truth.
• Investments & Taxes:
  • Investment buckets with market value tracking and optional tax basis settings.
  • Tax reserve accounting for monthly KPI accuracy.
• Internationalization: Fully localized interface available in English and Polish.
• Modern UX: Glassmorphism-driven UI with responsive layouts and loading states.

🛠️ Technology Stack

Built with performance and maintainability in mind:

Backend (Rust)

• Framework: Axum - High-performance async web framework.
• Database: SQLx with SQLite - Type-safe, compile-time checked SQL queries.
• Architecture: Modular service-oriented design with strict domain boundaries.

Frontend (React)

• Core: Vite, React, TypeScript.
• State/Data: TanStack Query for robust server-state management.
• Styling: TailwindCSS with a custom bespoke design system.
• Testing: Playwright for End-to-End verification.

🚀 Getting Started

Prerequisites

• Rust (latest stable)
• Node.js & pnpm
• Just command runner (for workflow automation)

Installation

1. Clone the repository:

   git clone https://github.com/ernest-gonzales/pulse.git
   cd pulse

2. Install frontend dependencies:

   just frontend-install

   Backend dependencies are fetched automatically by Cargo on build/run.

3. Start the development environment:

   just dev

   Starts the backend on http://127.0.0.1:3000 and frontend on http://127.0.0.1:5175.

macOS App Build (local)

1. Build the production assets:

   just macos-package

2. Install locally:
   • Open dist/macos/KontoPulse-macos-<version>.zip
   • Drag KontoPulse.app into /Applications
   • Launch KontoPulse.app (opens http://127.0.0.1:3000 in your browser)

Release (GitHub)

• Run the Release macOS workflow and select the version bump.
• The workflow bumps versions, updates CHANGELOG.md, builds the macOS bundle, tags the commit, and creates a GitHub Release with the zip asset.

📖 Documentation

For developers and contributors, documentation is available:

• Architecture & Decisions: Architectural Decision Records (ADR).
• Changelog: Version history and updates.
• Agent Rules: Guidelines for AI assistant interactions.

🤝 Contributing

Contributions are welcome! Please ensure you:

1. Follow the established code style (checked via just lint).
2. Add tests for new functionality.
3. Update documentation where appropriate.

📄 License

This project is licensed under the Apache License 2.0.