מבט כלכלי · Financial Overview

---

בעברית

מה זה?

מבט כלכלי הוא כלי שרץ אצלך במחשב או בשרת הביתי (ולא בענן של חברה אחרת), ועוזר לך לאסוף את התנועות מהבנקים ובכרטיסי האשראי בישראל, לראות אותן במקום אחד, ולהבין איך נראים ההכנסות וההוצאות שלך לאורך זמן.

המטרה היא פשוטה: פחות להתעסק עם קבצים ואקסלים מפוזרים, ויותר תמונה ברורה של הכסף שלך — עם אפשרות לסווג, לייצא, ולקבל עדכונים כשאתה רוצה.

קישורים: דמו — ממשק לדוגמה בדפדפן (נתונים לדוגמה בלבד, בלי חיבור לבנק) · מדריך התקנה — Windows

מה אפשר לעשות איתו (בקצרה)

• למשוך נתונים מהבנק והאשראי — הרצה מתוזמנת או ידנית, עם מעקב אחרי ההתקדמות במסך.
• לוח בקרה — סיכומים חודשיים, הכנסות והוצאות, מנויים חוזרים, ותצוגות שמסייעות לראות דפוסים.
• לחקור ולסווג — עבודה עם תוצאות מרובות, סינונים, וסיוע בקטגוריזציה (כולל אפשרות לעבוד עם בינה מלאכותית לניתוח ושיחה, לפי הגדרותיך).
• ייצוא — ל־CSV, JSON או לגיליונות Google, כדי שתוכל להמשיך לעבוד איפה שמתאים לך.
• שפות — ממשק בעברית ובאנגלית, כולל תמיכה בכיוון כתיבה (ימין־שמאל / שמאל־ימין).
• התראות בטלגרם — אופציונלי, כדי לקבל עדכונים או לבצע פעולות דרך הבוט (לפי ההגדרות שבחרת).
• נעילת אפליקציה — סיסמה שמגנה על הסשן ומסייעת להצפין את פרטי ההתחברות לבנקים שנשמרים אצלך במכשיר (ראו מדריך והערות אבטחה למטה).
• תיק השקעות (אופציונלי) — מעקב אחרי מניות/קרנות עם שערים; אפשר לחבר מפתח API של EODHD (הסבר באנגלית ב־README: מפתח EODHD, או הגדרות → השקעות באפליקציה).

כל זה מיועד לשימוש אישי וביתי — אתה שולט איפה הנתונים נשמרים ואיך ניגשים אליהם.

---

In English

What is it?

Financial Overview is a self-hosted tool: it runs on your computer or home server, not on someone else’s cloud. It helps you pull transactions from Israeli banks and credit cards, see them in one place, and understand your income and spending over time.

The idea is straightforward: less juggling spreadsheets and scattered exports, and a clearer picture of your money — with optional categorization, export, and notifications when you want them.

Links: Live demo (sample data in the browser — not connected to your bank) · Installation guide — Windows

Main features (at a glance)

• Fetch bank & card data — run on a schedule or on demand, with live progress in the UI.
• Dashboard — monthly summaries, income and expenses, recurring charges, and views that help spot patterns.
• Explore & categorize — work across multiple result sets, filter, and optional AI-assisted workflows (categorization and chat), according to your settings.
• Export — to CSV, JSON, or Google Sheets so you can keep working where you prefer.
• Languages — English and Hebrew with proper LTR/RTL layout.
• Telegram (optional) — updates and bot commands, depending on how you configure it.
• MQTT & Home Assistant (optional) - automate scrapes, reports, and notifications via Mosquitto; MQTT Discovery entities, custom integration, and blueprints are hosted in the dedicated israeli-financial-overview-ha repository (see docs/HOME_ASSISTANT.md).
• App lock — a password that protects your session and helps encrypt saved bank profile credentials on disk (see the user guide and security notes below).
• Investments / portfolio (optional) — track tickers and holdings; connect an EODHD API token under Configuration → Investments (see #eodhd-api-token below).

This is aimed at personal / home use: you choose where data lives and how it is accessed.

---

התקנה ב־Windows (בלי מומחי מחשבים)

אם אתם משתמשים ב־Windows, הדרך הפשוטה ביותר היא להוריד את קובץ ההתקנה (סיומת .exe) מדף ה־Releases בפרויקט ב־GitHub, ולהפעיל אותו כמו כל תוכנה רגילה.

• אין צורך להתקין Node.js או Docker — ההתקנה מכילה את כל מה שהאפליקציה צריכה כדי לרוץ במחשב שלכם.
• אחרי ההתקנה תמצאו את מבט כלכלי בתפריט התחל; בפתיחה נפתח חלון של האפליקציה עם המסכים — בדרך כלל לא צריך לפתוח דפדפן בנפרד.
• ליד השעון (מגש המערכת) מופיעה אייקון קטן. אם סוגרים את החלון והאפליקציה נשארת ברקע — זה נורמלי: כך פעולות מתוזמנות (למשל משיכת נתונים) והתראות בטלגרם יכולות להמשיך לעבוד. כדי לסגור לגמרי, השתמשו באפשרות יציאה מהתפריט של האייקון (למשל "יציאה" / עצירת השרת).
• אם Windows מציג אזהרה בזמן ההתקנה (למשל SmartScreen) — זה קורה לעיתים בתוכנות שלא חתומות בידי חברות גדולות; עקבו אחרי ההוראות במדריך או בדף ההתקנה הרשמי.
• למשיכת נתונים מהבנק נדרש דפדפן כרום או אדג' מותקן במחשב (Chrome או Edge) — בלי זה החיבור לבנק עלול לא לעבוד.

מדריך מפורט עם צילומי מסך (עברית / אנגלית):
מדריך התקנה — GitHub Pages

---

Installing on Windows (no tech background needed)

On Windows, the straightforward path is to download the installer (a file ending in .exe) from the project’s Releases page on GitHub, then run it like any normal desktop program.

• You do not need to install Node.js or Docker — the installer bundles what the app needs to run on your PC.
• After setup, open Financial Overview from the Start menu. The app opens in its own window — you usually do not need a separate browser tab.
• Look for a small icon near the clock (the system tray). If closing the window leaves the app running in the background, that is intentional: scheduled tasks (for example automatic bank updates) and Telegram notifications can keep working. To fully quit, use the tray menu (for example Quit / stop server).
• If Windows shows a security warning during install (for example SmartScreen), that can happen with apps not signed like big commercial vendors; follow the steps in the official install guide if you trust this software.
• Google Chrome or Microsoft Edge must be installed on the PC for bank login flows — the app relies on a Chromium-based browser that is typically provided by Chrome or Edge on Windows.

Step-by-step guide with screenshots (English / Hebrew):
Installation guide — GitHub Pages

---

Technical overview & setup

Preferred setup: use the in-app setup wizard (onboarding) to configure Telegram, Gemini, Google OAuth/Drive, and app lock — the same password derives the key that encrypts saved bank profiles.

What you get (detail)

Area	Highlights
Web UI	Dashboard (monthly income/expenses, subscriptions, analytics), Scrape with live progress, Results explorer (multi-file, filters, AI categorization), structured Logs (server/client/AI/scrape), Configuration (AI with persona alignment and AI memory — stored facts, insights, alerts; super privacy analyst mode runs SQL locally so Gemini sees schema + question only; scheduler, scrape/fraud, Google, Telegram, Investments with optional EODHD token, maintenance). AI analyst chat opens from the floating indigo button on any main tab when Gemini is configured. Insight rules include import review (tune categories/amounts before apply), optional share to community catalog, and browse/import from the catalog using the same editor as creating a rule.
Languages	English and Hebrew with LTR/RTL.
App lock & profiles	App lock (min. 8 characters) protects the session and encrypts stored profile credentials. You can use most of the app (dashboard, logs, configuration, exploring results) without unlocking; running scrapes and creating/editing saved bank profiles require the app to be unlocked when app lock is enabled. Forgot password: encrypted profiles cannot be recovered — you must delete those profiles and re-enter bank credentials after resetting lock (see GUIDE.html).
Integrations	Google OAuth → Drive/Sheets; Gemini for categorization and analyst chat; Telegram bot — see docs/TELEGRAM_BOT_GUIDE.md (commands, notifications, optional /unlock when the UI is locked); MQTT / Home Assistant — scrape, insights, and alerts via Mosquitto — see docs/HOME_ASSISTANT.md.
Deployment	Docker / Compose, Home Assistant add-on, Windows installer (see below), local Node monorepo for development.

Repository layout

This repo is an npm workspace monorepo:

• shared/ — Shared TypeScript (financial metrics, digest logic aligned with the dashboard).
• server/ — API, scraping orchestration, persistence.
• client/ — Vite + React UI (also buildable as a static demo with mocked APIs).

Quick start (local development)

From the repository root:

npm run setup
npm run dev

This runs the API and the Vite dev client together (see root package.json). The UI is typically served on http://127.0.0.1:5173 with the API proxied; for normal Docker/Compose the app is often on port 3000; the Home Assistant add-on uses 9203 internally to match ingress_port in ha-addon/config.yaml (see DEPLOYMENT.md).

Docker

docker-compose up --build

Then open the Web UI at http://localhost:3000 (or the port mapped in your compose file).

Feedback form: The Google Form link is set in client/src/config/feedbackGoogleForm.ts. The in-app dialog opens that URL (no URL prefill); it shows installation and version for reference and can fetch optional server/client log excerpts for copy-paste with explicit consent.

At image build time you can bake identity strings into the static client (see ARG / ENV before npm run build -w client in Dockerfile.app):

docker build \
  -f Dockerfile.app \
  --build-arg VITE_APP_BUILD_VERSION="$(git rev-parse HEAD)" \
  --build-arg VITE_INSTALL_KIND=docker \
  -t financial-overview .

CI workflows set VITE_APP_BUILD_VERSION and VITE_INSTALL_KIND automatically where applicable.

Home Assistant add-on

The Home Assistant Add-on, Custom Component, and Blueprints are hosted in a dedicated repository: israeli-financial-overview-ha.

1. Add the dedicated repository URL https://github.com/yohaybn/israeli-financial-overview-ha in Settings → Add-ons → Add-on Store → Repositories.
2. Install the Financial Overview add-on and configure OAuth/Drive (and other options) in the add-on Configuration tab.
3. Start the add-on and open the Web UI from the sidebar (Ingress uses mdi:finance in the sidebar).

MQTT automations: Install the Mosquitto broker add-on, then configure Configuration → MQTT in the app (or use mqtt_* options in the add-on Configuration tab). Enable Home Assistant MQTT Discovery for buttons and sensors, or use the automation blueprints and the custom component from the israeli-financial-overview-ha repository. See docs/HOME_ASSISTANT.md for details.

Port / Ingress: Home Assistant’s sidebar proxy (Ingress) always uses the internal port defined in the addon configuration (ingress_port, currently 9203). There is no separate port option in the UI — changing it would break Ingress. To use another internal port, fork and change ingress_port and PORT in the root Dockerfile, and publish new images.

Details: DEPLOYMENT.md.

Windows installer (maintainers — build from source)

End-user steps are in the Windows install section above; this block is for packaging the .exe.

The Windows build produces a single installer that bundles the production server, the built web UI, pruned npm dependencies, and a portable Node.js — end users do not install Node separately.

1. On Windows x64, from the repo root: npm run windows:package (or packaging/windows/package.ps1) → dist/windows-package/.
2. Build the Electron shell: npm run electron:dist, or npm run windows:electron for both steps → dist/electron-win/FinancialOverview-Windows-Setup-<version>.exe (NSIS; installs FinancialOverview.exe + server under resources/). Optional legacy Inno Setup: packaging/windows/FinancialOverview.iss (not used in CI).
3. GitHub Releases: on release: published, windows-package workflow uploads windows-package.zip and FinancialOverview-Windows-Setup-<version>.exe (or run manually via Actions → workflow_dispatch).

Advanced (optional): default app URL is http://127.0.0.1:3000. To change port or data folder, edit financial-overview.json in the install directory (see financial-overview.json.example); PORT / DATA_DIR env vars override the file. See DEPLOYMENT.md. Packaging skips bundling Puppeteer’s Chromium — Chrome or Edge on the machine is expected (or customize the build — packaging/windows/README.md).

GitHub Pages (demo UI + installation guide)

The workflow in .github/workflows/pages.yml publishes:

• A static demo (VITE_DEMO=true, in-browser API mocks, sample data). It does not connect to banks or your server. Full functionality requires the server stack above.
• A bilingual installation guide (English / Hebrew) for the Windows installer: /install/ on your GitHub Pages site (e.g. https://yohaybn.github.io/Israeli-Financial-Overview/install/ after Pages is enabled). It covers the Electron desktop app, system tray, close-to-tray / background (scheduler & Telegram), and the legacy console workflow. Screenshots live under client/public/install/screenshots/ and are copied into the Pages build with the rest of client/public/.

Dashboard behavior (recent logic)

For the current calendar month, positive completed transactions whose posting date is after today are treated as expected inflow (not yet received), together with pending income and detected recurring income. The same rules feed Telegram digests via shared code so server and UI stay consistent.

On narrow viewports (below Tailwind sm, 640px), main dashboard sections start collapsed; on wider screens they start expanded.

EODHD API token (optional — Investments / market data)

The optional Investments feature can use EOD Historical Data (EODHD) for delayed quotes, historical prices, and symbol search (US, Tel Aviv, and more). In the app: Configuration → Investments — turn the feature on, paste your token, and Save.

How to get an API key

1. Register for a free account at eodhd.com/register.
2. After you sign in, open your user dashboard and copy the API token (API key) shown there.
3. In Financial Overview: Configuration → Investments → enable Investments & portfolio if you want the dashboard card → paste the token → Save.

Notes

• If you set the server environment variable EODHD_API_TOKEN, it overrides the value stored in the app database (useful for Docker or shared hosting).
• API overview and endpoints: EODHD quick start and pricing.

Documentation in this repo

Doc	Purpose
Installation guide (GitHub Pages)	Windows install, desktop app + tray, background operation, first run, Telegram, Gemini (EN/HE); source: client/public/install/index.html.
client/public/GUIDE.html	Full user guide (EN/HE toggle) — same file the app opens from Help. Covers AI memory, AI persona, onboarding extraction, manual import (Results explorer), custom tabular import formats (?view=importProfile), export to other applications (CSV/JSON, API, Telegram, Google Sheets, Firefly III, Lunch Money, YNAB, Actual Budget), and a warning to verify AI-parsed imports before saving.
server/src/assets/help/user_manual.md	Source text for the documentation-grounded Help Assistant; includes import / import-profile / AI-import caution and export to other applications in Markdown.
docs/VIDEO_GUIDE.md	Scene-by-scene video/storyboard guide; PNG/PDF assets under docs/video-guide-screenshots/ and docs/video-guide-pdfs/.
docs/TELEGRAM_BOT_GUIDE.md	Telegram bot setup, commands, and behavior (English).
docs/HOME_ASSISTANT.md	MQTT & Home Assistant — Mosquitto setup, command topics, MQTT Discovery, automation examples, blueprints, optional custom component.
client/public/guides/TELEGRAM_BOT_GUIDE.he.md	Hebrew Telegram guide — embedded in עברית in client/public/GUIDE.html; regenerate with npm run guide:embed-telegram.
DEPLOYMENT.md	Environment variables and deployment (Docker, HA, Windows).
This README → #eodhd-api-token	Step-by-step: obtain an EODHD API token for optional Investments / portfolio (also configurable in-app under Configuration → Investments).
docs/THREAT_MODEL.md	Who can obtain bank credentials vs. transaction data; shared PC and remote attacker paths.
packaging/windows/README.md	Building the Windows installer and dist/windows-package.
financial-overview.json.example	Optional install-local JSON (port, dataDir) read by the server (copy to financial-overview.json).
server/src/index.ts	Mounts REST routes under /api/* (see server/src/routes/). Health: GET /api/health.

API

REST JSON under /api/* (Express). Route modules live in server/src/routes/; server/src/index.ts shows how they are mounted. GET /api/health returns { status, version }.

Security & encryption (at rest)

What	How
Saved bank profile credentials	AES-256-GCM on disk under data/profiles/ (each profile’s credentials field). The key is derived from your app lock password with scrypt (salt stored in data/security/app-lock.json). The password itself is not stored — only a scrypt hash for verification.
In memory	While the app is unlocked, the derived AES key exists only in server memory; it is not written to disk.
Not encrypted by the application	Gemini / OAuth / Telegram secrets in runtime-settings.json and config JSON; SQLite (app.db) for transactions and AI memory; scrape results and other files under DATA_DIR. Treat the whole data directory as sensitive and use OS permissions and optional full-disk encryption.
Backups	Local/Drive snapshots copy the same on-disk representation (encrypted profile blobs stay encrypted; plaintext config stays plaintext).

Default deployment uses HTTP to localhost; use a reverse proxy with TLS if you expose the UI beyond trusted networks.

Threat model (credentials vs. local access)

• Best practice: Unlock only to run a scrape or add/edit a saved profile, then lock again — this keeps the derived encryption key in memory for the shortest time. See docs/THREAT_MODEL.md for when locking does and does not stop credential access.
• Bank logins (saved profiles): Meaningful protection requires app lock with a strong password. If you never enable app lock, the app may use a fixed fallback key published in source — anyone who can read data/profiles/ can recover credentials. With app lock, an attacker needs your password, an unlocked session, or offline cracking of the lock file (e.g. after stolen disk), not just a folder copy alone.
• Transaction history & scrape data: Stored in SQLite (app.db) and data/results/ — not app-encrypted. Anyone with read access to DATA_DIR can read transactions and config secrets (Gemini, Telegram, OAuth) even without the app lock password. App lock does not hide the database from someone who can open files.
• Remote “hackers” need a path to your machine (malware, exposed port, stolen backup, etc.) — they do not magically read localhost. Full detail: docs/THREAT_MODEL.md.

---

Credits

Bank and credit-card scraping is powered by the open-source israeli-bank-scrapers project — a community-maintained library that connects to Israeli financial institutions. This app builds on top of that work; thank you to the maintainers and contributors of israeli-bank-scrapers.

Scraping does not use AI. Optional Gemini features (categorization, chat, etc.) do not receive your encrypted profile credentials or bank login secrets — only the transaction text and context you choose to send for those features. For analyst chat, enable Super privacy mode (Configuration → AI → Advanced) to avoid sending transaction rows: the model proposes read-only SQL and a reply template; your server runs the queries locally. See GUIDE.html (AI section) or server/src/assets/help/user_manual.md §4.1.