SMB — Sutady Moneybook

SMB (Sutady Moneybook) 2.4.1 is a full-stack personal bookkeeping system based on SQLite and MCP (Model Context Protocol). It natively supports local standalone operation and offline storage, and can also achieve secure cross-network access through Cloudflare Tunnel; the sole data source for the ledger is the local SQLite database, with no dependency on external cloud databases, giving you full control over your data.

Implemented

• Quick income/expense entry, recording only the date of occurrence, with amounts stored as integer "cents".

• Fully customizable categories, deactivation, migration or permanent deletion of categories, monthly/yearly bills, search and filtering, a global 30-day recycle bin, and CSV/JSON export.

• Weekly, monthly, and yearly trends, category breakdowns, category composition, and same-period progress comparison against the previous cycle.

• DeepSeek spending overview, abnormal growth, savings suggestions, category structure, and custom questions; the program handles the numbers and the model only handles interpretation, and no ledger notes are currently sent to external models.

• Standard Streamable HTTP MCP; can be switched by the web page between "confirmation mode" and "direct takeover mode". Direct mode can manage accounts, categories, loans, subscriptions, AI, backups, and time zones, and retains a 30-day undoable operation history.

• SQLite WAL plus synchronous=FULL, pre-migration snapshots, daily integrity/foreign key backups, age public key encryption, and Google Drive uploads.

• Cloudflare Access dual-layer protection, PWA installation, Windows login auto-start, and failure restart helper scripts.

• Four themes, four built-in page backgrounds, and personal background images stored only on the current device. Personal images are compressed in the browser and stripped of metadata, and you can temporarily switch back to built-in backgrounds without deletion.

• A query-first insights home page: period and income/expense type are stored in the URL, so your previous viewing position is preserved after refreshing or returning from category bills.

• Mobile side features a compact summary, detail/composition toggle, bottom navigation bar, and a bill filter drawer; the old list is kept during searches to avoid content flicker.

• All dates across the site follow the ledger time zone in settings; when the computer and Android device are in different time zones, "today", the default month, and the AI analysis period remain consistent.

• A standalone "Matters" module tracks money others owe you, partial repayments, and CNY/USD subscriptions. Matters do not enter spending statistics by default; only ordinary bills that are actively linked or created at the same time affect charts.

• Loans support borrower deactivation, partial repayment, automatic settlement, and a 30-day recycle bin; subscriptions support first-period discounts, monthly/yearly/custom periods, renewal confirmation, payment history, and in-app reminders.

• A monthly total budget in CNY and per-category budgets can be set; budgets do not carry over and do not block entry, and the insights page shows used, remaining, forecast, and category risk.

• "Ledger health check" uses deterministic rules to flag suspected duplicates, large expenses, budget risks, pending renewals, and association anomalies; the check does not automatically modify accounts, and AI only explains facts discovered by the program.

• The app menu after Android/Windows installation provides a "Quick Entry" shortcut; OpenClaw supports atomic writes of up to 20 bills at once with batch undo.

• Loan entry uses a searchable single borrower selector; new borrowers are saved in the same transaction as the loan. Active records with the same name are reused, and deactivated records must be restored first.

• OpenClaw proposal retries do not create duplicate pending items; the action center lets you view field changes and failure status on demand. The ledger health check can also be queried read-only via MCP and does not return notes.

• An optional "Funds" module records CNY accounts, balance transactions, transfers between accounts, fees, balance calibration, and full refunds; total funds do not include outstanding loans, investments, or future income.

• Historical bills before fund tracking is enabled are not retroactively traced; after enabling, ordinary income/expense entries are bound to accounts, and balances are calculated from the initial balance plus incremental fund transactions, without maintaining a second source of truth for balances.

• OpenClaw can precisely query and manage accounts, transfers, calibrations, and refunds; all direct writes continue to use idempotent requestId, and ambiguous account names are rejected.

For the actual operations of "Matters", the linkage rules before and after enabling funds, and OpenClaw permissions, see Loan and Subscription Usage Guide. For account enabling, fund impact, refunds, and health check hints, see Fund Tracking Usage and Maintenance Guide.

Related MCP server: ExpenseTracker MCP Server

Insights and Bills

• "Category breakdown" in insights is used to compare category rankings, amounts, and changes relative to the previous period; "category composition" is used to view the donut chart, amounts, and proportions, and the two are never shown at the same time.

• Category composition fully displays all categories with amounts in the current period, no longer merging them into "Other"; every sector and legend entry can drill down to the corresponding bills.

• The bills page has four equal-level entries: "Recent Entries", "Monthly Bills", "Yearly Bills", and "Recycle Bin". The recycle bin spans all dates and is sorted by deletion time, without inheriting the previously viewed month.

• Old URLs remain compatible: /bills opens recent entries; /bills?view=ledger&period=month&anchor=... opens monthly bills; changing period to year opens yearly bills; /bills?view=trash opens the global recycle bin.

• Normal deletion retains items for 30 days and allows restoration. Bills in the recycle bin can be permanently deleted; category management in settings can also permanently delete a category and all its bills after showing the scope of impact and confirming the name. Permanent deletion is irreversible, but linked loan or subscription matters are retained and automatically unlinked from the ledger.

Page Updates and Personal Background

• While a page is open, ledger data for the current page syncs every 30 seconds; it also syncs immediately when the window regains focus or the network recovers.

• The PWA checks for a new version every minute, and when a new version is found, it auto-updates when there is no form being edited. You can also click "Check and Refresh" under "Settings → Runtime Status".

• When the Cloudflare login expires, use "Log In Again" on the page; do not delete site cookies or clear site data. "Log In Again" and "Check and Refresh" only replace the PWA program cache, preserving login cookies, appearance preferences, and personal backgrounds in IndexedDB; only clearing the entire site data will delete personal images on the current device.

• Selecting "Pure, Paper, Texture, Mist" temporarily disables personal images, but the images remain on the current device and can be restored at any time by clicking "Use Image".

• The first cold start of each browsing session briefly shows the SMB brand splash screen once; refreshing data or switching pages does not replay it, and it is skipped entirely when the system has "Reduce Motion" enabled.

Quick Start and Local Running

Requires Node.js 22 or higher.

Option 1: One-Click Start on Windows (Most Recommended)

Simply double-click 打开 SMB.cmd in the project root directory.

• The first run automatically checks dependencies, generates the .env default configuration from the template, and completes the build and packaging;

• It then automatically starts the service and opens the bookkeeping home page in the default browser (default access at http://127.0.0.1:8788, no-login standalone mode).

Option 2: Manual Command-Line Start (Cross-Platform: Windows / Linux / macOS)

Open a terminal in the project root directory:

# 1. 安装项目依赖
npm install

# 2. 初始化本地配置（默认开启免登录单机模式）
cp .env.example .env

# 3. 运行开发模式（推荐本地体验，支持代码热重载）
npm run dev
# 浏览器访问 http://127.0.0.1:5173

# 或者编译并启动正式生产服务：
npm run build
npm start
# 浏览器访问 http://127.0.0.1:8788

Quality Check

npm test
npm run typecheck
npm run build

Before an official update, you can additionally create a snapshot that has passed an integrity check:

npm.cmd run backup:snapshot -- manual-update
npm.cmd run backup:verify-restore

Advanced Features and Deployment Guide

If you only keep books on a personal computer in standalone mode, no external services need to be configured — it works out of the box.

If you need the following advanced capabilities, refer to the corresponding guides and configure as needed:

• Remote bookkeeping from your phone across networks: Use Cloudflare Tunnel for public-IP-free tunneling and Access identity verification; see the Deployment Guide.

• AI-powered smart spending analysis: Double-click 配置DeepSeek密钥.cmd in the root directory or fill in the DeepSeek API Key in .env to enable spending insights and savings suggestions.

• Encrypted automatic cloud backup from anywhere: Configure Google Drive and the age encryption key for daily automatic snapshot uploads; see the Recovery Guide.

• Fund and account management: Multi-account asset transactions, transfers, and balance calibration; see the Fund Tracking Guide.

• Loan and subscription management: Track external debts, partial repayments, and recurring subscription charges; see the Matters Usage Guide.

Directory

• src/: React PWA shared by mobile and desktop.

• server/: Node API, MCP, DeepSeek, funds, financial matters, and backup services.

• db/: SQLite schema and migrations.

• tests/: Amount, date, matters, UI, AI, and MCP tests.

• scripts/: Initialization, auto-start, backup key, and recovery scripts.

• deploy/: Keyless configuration templates for Cloudflare and OpenClaw.

The private file .env, the production database, backups, logs, and build artifacts are all excluded from version control.

The version number is maintained only in package.json. Fixes and visual refinements increment the patch version, backward-compatible new capabilities increment the minor version, and product identity or incompatible contract changes increment the major version; release notes are in CHANGELOG.md. Logo specifications and editable source files are in the Brand Guide.

Features that have been explicitly deferred — bill import, third-party balance sync, and more complex account capabilities — are listed in ROADMAP.md.