Documentation

Zupu Docs

Everything you need to install the app, keep your family data safe, and work the tree. The app interface is currently in Traditional Chinese; UI labels below are quoted with translations.

Install

Download the installer for your platform from the download page. Requirements: macOS 12+ (Apple Silicon) or Windows 10+ (x64).

The installers are currently unsigned, so the OS will warn on first launch:

  • macOS: if Gatekeeper blocks the app, right-click (or Control-click) Zupu.app in Applications and choose Open, then confirm. You only need to do this once.
  • Windows: if SmartScreen shows "Windows protected your PC", click More info → Run anyway.

First launch

On first launch the app asks for your clan name and an optional sidebar icon (an emoji or a single character). You can change both at any time by clicking the clan name at the top of the sidebar.

The workspace

The sidebar switches between four views:

  • 族譜總覽 (Family tree) — the interactive tree plus a detail panel for the selected person. This is the main working screen.
  • 族員名錄 (Members) — a filterable directory of everyone in the database, connected to the tree or not.
  • 補助管理 (Subsidies) — all subsidy records with totals and status filters.
  • 操作紀錄 (Audit log) — a timeline of every change made in the app.

Press ⌘K (macOS) or Ctrl K (Windows) anywhere to search members and subsidies.

Where your data lives

All data is stored locally in a single SQLite database named family.db. Nothing is uploaded anywhere.

  • macOS: ~/Library/Application Support/com.mason.family-manager/family.db
  • Windows: C:\Users\<you>\AppData\Roaming\com.mason.family-manager\family.db

The database runs in WAL mode, so you may also see family.db-wal and family.db-shm next to it. If you copy the database manually, copy all three files while the app is closed — or simply use the JSON export below, which is the supported way to back up.

Backup & restore

In the sidebar footer, 匯出 (Export) writes the entire database — people, relationships, marriages, subsidies, custom fields, app settings, and the full audit log history — to a JSON file named zupu-YYYY-MM-DD.json.

匯入 (Import) replaces everything. Restoring a backup overwrites the current database completely and cannot be undone. The app asks for confirmation and shows the selected file name; export a fresh backup first if the current data matters. Imported backups are validated (duplicate or cyclic relationships are rejected) before any existing data is touched.

Moving to a new computer: export on the old machine, install Zupu on the new one, then import the JSON file. The audit log history travels with the backup; only backups created by older versions leave it on the old machine.

Building the tree

  • 新增人員 (Add person) opens a wizard that can set parents, a spouse, subsidies, and custom fields (世代 / 排行 / 房支) in one pass.
  • Parent-child links are checked for duplicates and ancestry cycles; marriages are checked for duplicates. Invalid input is rejected with a message rather than stored.
  • Click any node to select that person and load their details in the right panel. Click empty canvas to deselect.
  • The bottom-right controls zoom in/out, center the focused person, and fit the whole tree. Fitting stops at 50% scale — on very large trees the view centers the selected person instead of shrinking text past readability, and you pan from there.
  • People not connected to the current tree appear in the 未連結 (Unlinked) chips at the top left; click one to view that person's tree.
  • From the detail panel you can export a person's offspring list as CSV or a printable PDF.

Subsidies

Subsidy records belong to one person and carry a type, an integer amount (NT$), an optional date, and a status — 待審核 (pending), 已核准 (approved), or 已拒絕 (rejected). The 補助管理 view shows totals and lets you filter by status; pending counts appear as a badge in the sidebar.

Audit log

Every create, edit, delete, import, and export is recorded with a timestamp, a summary, and field-level before/after values. The view loads 200 entries at a time — use 載入更早的紀錄 (Load older) to page further back. 匯出稽核報告 (Export report) always covers the full history that matches your current filters, regardless of how many pages are loaded.

Limits & FAQ

Is anything synced or uploaded?

No. Zupu is local-first: one database on one machine. If several family members maintain the records, designate one editing machine and share JSON exports as read-only copies.

Can I undo a delete?

Yes. Deleting a person also removes their relationships, marriages, and subsidy records after confirmation, but the success toast offers 復原 (Undo) to restore the person and those records. It's still a good idea to export a JSON backup regularly.

Can I import a GEDCOM file from other software?

Not yet — JSON backup is currently the only interchange format. GEDCOM support is on the roadmap.

What languages are the app and this site available in?

The site is available in English and Traditional Chinese — switch anytime with the language button in the navigation. The app interface is currently Traditional Chinese; app internationalization is planned.

I found a bug.

Email clan@masonhuang.com with steps to reproduce and your app version (shown in the installer file name).