ShekelSync

March 12, 2026 ยท View on GitHub

ShekelSync logo

Latest Release CI Security Audit Secret Scan GitHub Stars

Personal finance tracker for Israeli banks and credit cards, built as an Electron desktop app with a local API and a Vite-powered renderer.

Repo Layout

  • electron/ Electron main process, preload, and security wiring.
  • app/ Local API server, database services, and shared libraries.
  • renderer/ React UI (Vite).
  • scripts/ Utilities for database setup, migrations, and tooling.
  • docs/ Internal documentation and migration notes.

Requirements

  • Node.js >= 22.12.0 (see app/package.json)

Setup

npm install
npm --prefix app install
npm --prefix renderer install

Development

# Start Electron + Vite renderer
npm run dev:electron

# Or run the embedded API only
npm run dev:api

On Linux, npm run dev:electron automatically falls back to app/.env.local for SHEKELSYNC_ENCRYPTION_KEY when no OS keychain service is available (for example in WSL/headless sessions).

Performance note: when the app window is minimized/hidden, renderer polling and ambient UI animation are paused and resume on focus to reduce idle CPU usage.

Tests

npm test

Build

npm --prefix app run dist

Releases

  • Cross-platform packaging is manual via workflow dispatch (.github/workflows/package.yml).
  • The package workflow builds distributables for Linux, macOS, and Windows.
  • When signing/notarization secrets are configured, the workflow applies platform signing.
  • Build artifacts are uploaded for each workflow run (unsigned when signing secrets are not provided).
  • Before tagging a release, run migration review: npm run release:migrations:check.
  • Published releases: https://github.com/AvnerAdda/shekelsync/releases

Database

# Initialize local SQLite database
npm run init:sqlite

Configuration

Local desktop runs use app/.env.local. For production, set a strong SHEKELSYNC_ENCRYPTION_KEY and keep ALLOW_DEV_NO_ENCRYPTION=false. For safety, existing SQLite files are not auto-reinitialized when schema validation fails (to avoid accidental data loss). To force reinitialization, set SQLITE_AUTO_REINIT_ON_SCHEMA_MISMATCH=true.

Scraping and Compliance

This project uses israeli-bank-scrapers to connect to financial institutions. Before using scraping features, make sure you:

  • Have authorization to access the target account.
  • Comply with the institution terms of service and local law.
  • Understand that site/API changes can break scrapers without notice.

You are responsible for lawful and compliant use in your jurisdiction.

Security

  • Report vulnerabilities privately; see SECURITY.md.
  • Security audit workflow runs on push/PR/manual dispatch (.github/workflows/security-audit.yml).
  • Secret scanning runs with gitleaks on push/PR/manual dispatch (.github/workflows/secret-scan.yml).
  • CI gates tests and quality checks on push/PR (.github/workflows/ci.yml).
  • Never commit credentials, private keys, or production .env files.
  • Enable local secret scanning hooks: npm run hooks:install
  • Run a manual full secret scan: npm run secrets:scan

Community

  • Contribution guide: CONTRIBUTING.md
  • Code of conduct: CODE_OF_CONDUCT.md

License

This project uses an open + commercial licensing model:

  • Open-source license: AGPL-3.0-or-later (see LICENSE)
  • Commercial license: available for proprietary/commercial usage without AGPL obligations (see LICENSE-COMMERCIAL.md)
  • Trademarks/branding: see TRADEMARKS.md