Admin & Database Operations Guide

How to administer Trackmint’s users and data. The tool is agent-tool/trackmint-admin.js (Node + firebase-admin, same service-account key as the agent CLI). These are the standard operating workflows — modeled on how ops teams run comparable SaaS backends (user lifecycle, surgical record edits, backup-before-destructive, audit trail).

The data model in one paragraph

One Firebase Auth user per account; one Firestore document per account at workspaces/{uid} holding the entire workspace: setup (company), members[], projects[], payments, currency, reminders, colNames/startCol per pack, and data.{dev|legal|trade|general} each with items[], budgets, invoices[], expenses[], timeEntries[]. The app defensively normalizes whatever it loads (repo.ts), so a hand-edited doc with a missing field self-heals — but stick to the workflows below anyway.

Workflow 1 — User lifecycle

Add a user (e.g. onboarding a beta tester): users:add tester@firm.com <temp-password> → send them the password → their first login runs the setup wizard and creates their workspace doc automatically. Reset a password: users:reset-password <uid> <new> (find the uid with users:list). Suspend / restore: users:disable <uid> blocks sign-in without touching data; users:enable restores. Delete a user (GDPR/offboarding): users:delete <uid> --with-data — deletes the Auth account AND the workspace doc, writing a JSON backup first automatically. Without --with-data the workspace doc is kept (e.g. company account transfers).

Workflow 2 — Inspect and edit any record or field

Find the workspace: ws:list (shows company, pack, member/item counts) → ws:get <uid> for the whole doc, or ws:get <uid> members / ws:get <uid> data.dev.items.3 for one branch. Change a specific field on a specific record — the dot-path addresses anything, numeric segments index arrays:

ws:set <uid> currency '"EUR"'                       # workspace field
ws:set <uid> members.1.rate 150                     # 2nd member's hourly rate
ws:set <uid> members.1.role '"manager"'             # promote to manager
ws:set <uid> data.dev.items.3.completed true        # complete a task
ws:set <uid> data.dev.items.3.title '"New title"'   # rename a record
ws:set <uid> projects.0.budget 12000                # fix a project budget
ws:delete-field <uid> data.dev.items.3.assignStatus # clear a field

Every ws:set runs in a transaction (re-read → modify → write) because the workspace is a single document — the same safety rule agents follow (AGENT_SOP.md).

Workflow 3 — Backup, restore, disaster recovery

Before any bulk or destructive edit: ws:backup <uid> → timestamped JSON on disk. Restore: ws:restore <uid> backup-….json (full overwrite). Destructive commands (ws:delete, users:delete --with-data) auto-backup first — a delete is always reversible from the snapshot. For fleet-wide backups, loop ws:list output through ws:backup on a nightly cron.

Workflow 4 — Support playbooks (the requests you’ll actually get)

“I renamed my company wrong” → ws:set <uid> setup.companyName '"Right Name LLC"'. “My worker left, remove them” → check nothing open: ws:get <uid> data.dev.items, reassign via ws:set … assigneeId, then remove the roster entry by writing the filtered array: ws:get <uid> members → edit → ws:set <uid> members <json>. “An invoice was marked paid by mistake” → ws:set <uid> data.dev.invoices.2.status '"Sent"' and ws:delete-field <uid> data.dev.invoices.2.paidVia. “Wipe my demo data but keep my account” → ws:backup then ws:delete <uid>; next app launch reseeds a clean workspace through the wizard.

Workflow 5 — Governance & safety rules

The Admin SDK bypasses Firestore security rules entirely: the service-account key IS root. Keep it off shared machines, never commit it (gitignored), rotate it from Firebase Console if exposure is suspected. One operator at a time for writes on the same workspace (single-doc model). Log what you change: each command’s stdout line into an ops journal is the audit trail until a proper audit log ships. Agents never get this tool — they use trackmint-agent.js, which can only touch task-level fields under the SOP.

What’s intentionally NOT here (roadmap)

A web admin panel (this CLI is the v1 admin UI), automated nightly backups, an immutable audit log, and bulk anonymization for GDPR export requests. All straightforward extensions of the same key + Admin SDK foundation.