Firestruct is a native Firebase workspace for macOS. It connects to Firebase projects and emulators, lets users inspect and manage Firestore/Auth/Storage data, and adds guarded workflows for tasks such as imports, exports, transfers, push testing, seeding, migrations, and point-in-time recovery.
Implementation completion is evidence-based: Firebase behavior must be proven with emulator runs or approved live Firebase verification. Mock-only proof is not enough for user-facing workflows.
Start Here
- Foundation and App Shell: workspace layout, collapsible sidebar trees, tabs, split view, output modes, feature flags, and command palette.
- Project Registry: linking projects, selecting environments, emulator setup, read-only mode, and local project state.
- Firestore: queries, JS scripts, table/tree/json/log views, emulator-proven CRUD/import/export/transfer/backups, live request-shape guardrails, and schema tools.
- Auth: user search, filtering, editing, custom claims, bulk actions, import/export/transfer, scripts, and Auth-to-Firestore linking.
- Storage: emulator-proven bucket browsing, upload/download/delete, folder and multi-selection workflows, ZIP and URL actions, thumbnails, guarded production controls, and Auth photo URL handoff.
- Push: FCM payload validation, token resolution, simulated sends, and guarded send attempts.
- PITR Recovery: point-in-time request shape, current vs historical diff output, and guarded restore prep while live proof remains open.
- Index Advisor: deterministic query/index comparison, local index checks, and captured backend-link parsing while live missing-index UI proof remains open.
- Seed Studio: deterministic fixture generation, emulator seed snapshots, and drift comparison against current emulator data.
- Tasks: queue, progress, counters, errors, and retry visibility for long-running work.
- Migrations: Fireway file and Firestore migration status inspection.
- Workspace Link: local Firebase workspace link, rules/index viewing, diffing, and guarded deploy prep.
- Support: in-app Chatwoot support.
- Purchases and Pro Access: entitlement model and gated actions.
Operator and maintainer references:
- Verification Contract: required emulator, live-project, PR, and release-candidate evidence.
- Live Verification Template: evidence format for approved live Firebase runs.
- Open Verification Backlog: remaining live, StoreKit, UI-runner, and release proof that must not be marked complete from mocks or request-shape tests.
Every module also has a cli.md page. CLI support includes project/module and Firestore-database selection; Firestore querying, backups, import/export/transfer, scripts, embeddings, schema, and writes; Auth administration, per-project tenant discovery/selection, and Auth-to-Firestore route management/resolution; Storage object/folder/bulk workflows; Tasks history; Index Advisor; Seed Studio; Workspace Link; PITR; Push; Migrations; and release-evidence preflight.
Basic Concepts
Project: a local link to a Firebase or emulator target. Firestruct stores display name, Firebase project ID, environment, read-only status, emulator endpoints, selected Firestore database, color tag, and module settings.
Environment: the target type: emulator, development, or production. Production mutations and deploys require explicit confirmation.
Module: a workspace area such as Firestore, Auth, Storage, Tasks, or Index Advisor. GUI modules open in tabs and may expose output modes.
Output mode: a result view such as TABLE, TREE, JSON, LOGS, or Storage BROWSER.
Task: a queued long-running operation with status, progress, counters, duration, errors, and retry controls.
Read-only project: a project guardrail that blocks writes and destructive actions.
Pro-gated action: a paid capability such as writes, deletes, imports, exports, uploads, deploys, scripts, transfers, and saved local workflows.
Simple query: a Firestore query built from path, filters, ordering, and limit.
JS Query / script: a local JavaScript run() workflow with Firestruct's Admin SDK-style local shim, structured results, and captured logs.
Workspace link: a local Firebase repo association using files such as firebase.json and .firebaserc.
Safety Defaults
- Show target project and environment before every mutation.
- Require explicit confirmation for production writes, destructive operations, deploys, seed applies, migration applies, and push sends.
- Validate same-project move and rename paths before running.
- Make overwrite behavior visible before confirmation.
- Run long imports, exports, transfers, deploys, seeds, migrations, and recursive mutations through Tasks.
- Keep credentials and Firebase data local to the user's machine.