From 9f60e82d2b11193b6034c38129c47abd0eb4898e Mon Sep 17 00:00:00 2001 From: nemsys Date: Wed, 30 Sep 2026 03:44:55 +0300 Subject: [PATCH 1/3] docs: bring README up to date and drop the project structure tree Assisted-by: claude-opus-5-5 --- README.md | 336 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 203 insertions(+), 133 deletions(-) diff --git a/README.md b/README.md index c9299ac..53fd36d 100644 --- a/README.md +++ b/README.md @@ -6,23 +6,33 @@ A clean, cloud-synced web app for cataloguing your physical storage boxes and th ## ✨ Features -- **Box & Item Catalog** — Create named boxes, add items to them with descriptions and photos -- **Multi-image Support** — Attach multiple photos to any box or item; browse them with a built-in image slider -- **Fuzzy Search** — Instantly find items by name, description, or tag across your entire collection, powered by [Fuse.js](https://www.fusejs.io/) -- **Tagging System** — Tag items freely; bulk-rename or delete tags from a central manager -- **Sort & Filter** — Sort by newest, oldest, or name (A–Z / Z–A); filter any view by tag -- **"All Items" View** — Browse every item across all boxes in one unified list, with box attribution -- **Unassigned Items** — Items can exist without a box; assign or reassign them at any time -- **Dark & Light Theme** — Toggle between themes; preference is saved per browser -- **Import / Export** — Back up your data as a JSON file and restore it with a progress modal -- **Browser History** — Deep-linkable views via URL hashes (`#box/`, `#all-items`) -- **Invite-only** — Anyone can create an account, but nothing is readable until the owner approves it; data is then scoped per user, enforced by Firestore rules +- **Box & Item Catalog** - Create boxes with a name, location, description, tags and photos, and add items to them +- **Photos** - Attach several photos to any box or item, taken with the in-app camera or picked from the gallery; open them fullscreen with pinch and double-tap zoom +- **Box Locations** - Record where each box physically is ("attic, shelf 2"); earlier locations are offered as you type +- **Fuzzy Search** - Find items by name, description or tag, powered by [Fuse.js](https://www.fusejs.io/). Searching the box list also looks at locations and inside the boxes, and says which item matched +- **Tagging System** - Boxes and items share one tag vocabulary; rename, merge or delete a tag everywhere from a central manager +- **Sort & Filter** - Sort by newest, oldest or name; the box list adds recently changed, by location and fullest first. Filter any view by tag +- **"Items" View** - Browse every item across all boxes in one list, with the box each one is in +- **Unassigned Items** - Items can exist without a box; assign or reassign them at any time +- **Bulk Actions** - Select several items to move them to a box, add tags or delete them in one go +- **Printable Box Labels** - Print a QR label for each box; scanning it with the phone camera opens that box in the app +- **Inventory Check** - Lists what needs attention: items in no box, boxes with no location, untagged items, empty boxes and anything without a photo +- **Undo** - Deleting an item or a box, or removing an item from its box, can be undone from the notification for a few seconds +- **English & Bulgarian** - The first launch follows the browser language; switch any time in Settings +- **Dark & Light Theme** - Toggle between themes; preference is saved per browser +- **Works Offline** - Firestore's local cache keeps the inventory available without a connection, and changes sync when it returns +- **Import / Export** - Back up your data, photos included, as a JSON file and restore it with a progress modal +- **Browser History** - Deep-linkable views via URL hashes (`#box/`, `#all-items`) +- **Invite-only** - Anyone can create an account, but nothing is readable until the owner approves it; data is then scoped per user, enforced by Firestore rules --- ## 🖥️ Live App -The app is deployed on Firebase Hosting. Sign in with your Google account or email to get started. +The app is deployed on Firebase Hosting at +. Create an account with an email +address and a password; it can see nothing until the owner approves it (see +[Access control](#access-control)). **New here?** The [landing page](https://sciscend.github.io/StorageBoxOrganizer/) (Bulgarian, with English) explains what the app does, how to install it and how @@ -45,10 +55,11 @@ visit. Nothing to download, works on both platforms. **From the APK (Android only).** Grab `storage-box-organizer-.apk` from the [Releases page](https://github.com/SciScend/StorageBoxOrganizer/releases) and open it on the phone; Android will ask you to allow installing from that source -once. The APK adds what the browser cannot give a web page: the device camera -with its own capture UI, the hardware back button wired into navigation, and a -native splash screen. It is signed with the project's release key, so a later -release installs straight over it. +once. The APK adds what the browser cannot give a web page: the hardware back +button wired into navigation, a native splash screen and a status bar styled to +match the app. Photos are taken with the same in-app camera in both. It is +signed with the project's release key, so a later release installs straight +over it. --- @@ -56,37 +67,85 @@ release installs straight over it. ### Getting started -1. Open the app and sign in (Google or email/password). -2. On the **Your Boxes** tab, click **+ New Box** to create your first box. -3. Give it a name, description, and optionally one or more photos. -4. Click into a box, then **+ Add Item** to start cataloguing its contents. +1. Open the app and create an account (email and password). Until the owner + approves it you will see an "Access not approved yet" screen; tap + **Check again** once they confirm. +2. On the **Boxes** tab, tap the round **+** button at the bottom to create your + first box. +3. Give it a name and, optionally, a location, a description, tags and photos. +4. Open the box and tap **+** again to start cataloguing its contents. ### Navigating | View | How to reach it | |---|---| -| All boxes | Click the logo or **Your Boxes** tab | -| Inside a box | Click any box card | -| All items | Click the **Your Items** tab | +| All boxes | Tap the logo or the **Boxes** tab | +| Inside a box | Tap any box card, or scan the QR code on its printed label | +| All items | Tap the **Items** tab | + +The browser's Back button, and the hardware Back button on Android, step back +through these views. + +### Working with boxes + +The box menu (the three dots in the box's header) has: + +- **Edit Box** - name, location, description, photos and tags. +- **Remove (keep items)** - deletes the box; its items stay, unassigned. +- **Delete Box & Items** - deletes the box and everything in it. The confirmation + says how many items go with it, and the notification offers Undo for a few + seconds. ### Working with items -- **Assign / move** — When editing an item, choose a different box from the dropdown, or leave it blank to keep it unassigned. -- **Remove from box** — Clicking the remove button inside a box view unassigns the item but keeps it in "Your Items". -- **Delete permanently** — Deleting from the "Your Items" view removes the item and its data entirely. -- **Reassign an existing item to a box** — From inside a box, use **Add Item → Select Existing** to pick an already-catalogued item. +- **Assign / move** - In the item's edit form, type in the **Box** field to find + a box by name or location, or choose **Unassigned (no box)**. +- **Remove from box** - The item's menu (the three dots on its card) has + **Remove from Box**, which unassigns the item but keeps it in **Items**. +- **Delete** - **Delete Item** in the same menu removes the item and its photos. + The notification offers Undo for a few seconds. +- **Add an existing item to a box** - Inside a box, tap **+** and switch to + **Select Existing**. Items in no box are listed first. +- **Several at once** - In an item list, tap the select button in the search bar, + tap the items you want, then choose **Move to box**, **Add tags** or + **Delete selected**. **Select all shown** takes what the current search and + filter show. ### Tags -- Add tags to any item when creating or editing it. -- Tags are **case-insensitive** and stored in lowercase — `Books` and `books` are the same tag. -- Use **Settings → Manage Tags** to rename a tag across all items at once, or delete it entirely. Renaming a tag to one that already exists merges the two. -- Filter any view by tag using the **Filter** dropdown in the controls bar. +- Add tags to any box or item when creating or editing it. The suggested tags + start with the ones you used most recently. +- Tags are **case-insensitive** and stored in lowercase: `Books` and `books` are + the same tag. +- Use **Settings > Manage Tags** to rename a tag across all boxes and items at + once, or delete it entirely. Renaming a tag to one that already exists merges + the two. +- Filter any view by tag with the tag button in the search bar. In the box list, + a box matches if it carries the tag or holds an item that does. + +### Settings + +- **Language** (English / Bulgarian) and **light / dark theme**. +- **Sync data** reloads your data, for example after a change made on another + device. +- **Manage Tags** - see above. +- **Optimize Images** converts photos stored by older versions to the current, + lighter format. Safe to run again. +- **Inventory check** lists what needs attention, and each row opens the thing to + fix. +- **Print labels** makes a printable sheet of QR labels, one per box. +- **Check for Updates** offers to reload when a newer version has been deployed. +- **About** shows the version, the author, a contact address and a link to the + user guide. ### Backup & restore -- **Export** — Settings → Export. Downloads a `.json` file with all boxes and items. -- **Import** — Settings → Import. Select your `.json` backup; a progress modal tracks the restore. Fresh copies are created, so re-importing won't duplicate data. +- **Export** - **Settings > Export Data** downloads a `.json` file with all boxes, + items and their photos. +- **Import** - **Settings > Import Data**. Select your `.json` backup; a progress + modal tracks the restore. Importing your own backup again updates the existing + entries instead of adding copies; importing it into another account creates + new ones there. --- @@ -98,44 +157,52 @@ release installs straight over it. |---|---| | UI framework | React 19 | | Build tool | Vite 7 | -| Styling | Custom CSS (CSS variables, Tailwind-style utility classes) | +| Styling | Tailwind CSS v4, with theme-aware colour tokens (`bg-surface`, `text-muted`, ...) defined in `src/index.css` | | Animations | Framer Motion | | Icons | Lucide React | | Fuzzy search | Fuse.js | -| Backend / Auth | Firebase (Firestore + Authentication) | -| Image processing | Browser Canvas API (base64, max 800 × 800 @ 0.7 quality) | +| QR codes (box labels) | qrcode | +| Translations | Own small i18n layer in `src/translations/` (English, Bulgarian) | +| Backend / Auth | Firebase (Firestore with an offline cache + email/password Authentication) | +| Image processing | Browser Canvas API: a ~256 px thumbnail and a ~1024 px full image per photo, WebP (JPEG fallback) | | ID generation | uuid v4 | -| Hosting | Firebase Hosting | +| Hosting | Firebase Hosting, installable as a PWA (service worker from `src/sw.js`) | +| Android app | Capacitor 7 | | Admin scripts | Node.js + Firebase Admin SDK | ### Prerequisites -- **Node.js** ≥ 18 -- **npm** ≥ 9 -- A **Firebase project** with Firestore, Authentication, and Hosting enabled -- Firebase CLI: `npm install -g firebase-tools` +- **Node.js 24**, the version in `.nvmrc` and the one CI uses (Vite 7 needs at + least 20.19), with the npm that comes with it +- A **JDK** (21) for `npm run test:rules` (the Firestore emulator) and for APK + builds, which also need the **Android SDK** +- The **Firebase CLI** is a dev dependency, so `npm install` brings it; run it as + `npx firebase` +- Your own **Firebase project** with Firestore, Authentication and Hosting + enabled - only if you deploy a copy of the app elsewhere ### Local setup ```bash -# 1. Clone the repository -git clone -cd storage-box-organizer - -# 2. Install dependencies +git clone https://github.com/SciScend/StorageBoxOrganizer.git +cd StorageBoxOrganizer npm install - -# 3. Configure Firebase (see section below) - -# 4. Start the dev server npm run dev ``` -The app will be available at `http://localhost:5173`. +The app will be available at `http://localhost:5173`, talking to the live +Firebase project, so you need an approved account to see data. + +To look at the UI without one, open `http://localhost:5173/?mock-auth=true`: the +dev server then skips sign-in and loads sample boxes and items. It is read-only - +any save fails with "User not authenticated" - and the flag does nothing in a +production build. ### Firebase configuration -The Firebase config is in `src/firebase.js`. For your own deployment, replace the values with those from your Firebase project's settings: +The Firebase config is in `src/firebase.js`. For your own deployment, replace the +values with those from your Firebase project's settings, and change the project +ID in `.firebaserc` and the hosted URL in `capacitor.config.json` (`server.url`): ```js // src/firebase.js @@ -153,7 +220,7 @@ const firebaseConfig = { #### Firestore Security Rules -The live ruleset lives in [`firestore.rules`](firestore.rules) and is deployed with `firebase deploy --only firestore:rules` (or as part of `npm run deploy`). It enforces two independent gates: +The live ruleset lives in [`firestore.rules`](firestore.rules) and is deployed with `npx firebase deploy --only firestore:rules` (or as part of `npm run deploy`). It covers the `boxes`, `items` and `images` collections and enforces two independent gates: 1. **Approval** — the account must carry the `approved` custom claim (see [Access control](#access-control) below). 2. **Ownership** — every document carries a `userId`, and an approved account may only touch its own. @@ -166,7 +233,7 @@ npm run test:rules # spins up the Firestore emulator, needs Java #### Firebase Authentication -Only **email/password** is enabled — `AuthModal` has no other provider wired up. Turn it on in Firebase Console → Authentication → Sign-in method. +Only **email/password** is enabled — `AuthModal` has no other provider wired up. Turn it on in Firebase Console → Authentication → Sign-in method. Password reset uses Firebase's own reset email ("Forgot your password?" on the sign-in form). ### Access control @@ -180,13 +247,13 @@ npm run access grant you@example.com # let someone in npm run access revoke them@example.com # lock someone out ``` -An unapproved account gets a "waiting for approval" screen showing its email and account ID, plus a **Check again** button that forces a token refresh. Granting takes effect on the next refresh — that button, or signing out and back in. +An unapproved account gets an "Access not approved yet" screen showing its email and account ID, plus a **Check again** button that forces a token refresh. Granting takes effect on the next refresh — that button, or signing out and back in. > **Before you deploy these rules for the first time**, approve yourself. A ruleset that nobody is approved for locks everyone out, including you: > > ```bash -> npm run access grant you@example.com # first -> firebase deploy --only firestore:rules # then +> npm run access grant you@example.com # first +> npx firebase deploy --only firestore:rules # then > ``` #### Further hardening (optional, both free) @@ -201,72 +268,24 @@ An unapproved account gets a "waiting for approval" screen showing its email and | `npm run dev` | Start the Vite dev server with HMR | | `npm run build` | Production build into `dist/` | | `npm run preview` | Preview the production build locally | -| `npm run deploy` | Build and deploy to Firebase Hosting | +| `npm run deploy` | Build and deploy to Firebase Hosting, together with `firestore.rules` | | `npm run lint` | Run ESLint | | `npm run translations:check` | Verify `en`/`bg` string files agree with each other and with the code | | `npm run test:rules` | Run the Firestore security-rules tests against the emulator (needs Java) | | `npm run access` | List / grant / revoke account approval (requires service account) | -| `npm run backup` | Dump all Firestore collections to `.backups/` (requires service account) | -| `npm run import` | Import a backup JSON into Firestore (requires service account) | +| `npm run backup` | Dump the `boxes` and `items` collections to `.backups/` (requires service account) | +| `npm run import -- [uid]` | Import a backup JSON into Firestore, optionally under another user (requires service account) | | `npm run cap:sync` | Build the web app and copy it into the Android project | +| `npm run android:open` | Open the Android project in Android Studio | +| `npm run android:run` | Run the app on a connected device or emulator | | `npm run android:apk` | Build a **debug** APK (`android/app/build/outputs/apk/debug/`) | | `npm run android:release` | Build a **signed release** APK (`android/app/build/outputs/apk/release/`) | -### Project structure - -``` -storage-box-organizer/ -├── public/ # Static assets (SVG icons) -├── scripts/ # Node.js admin scripts (Firebase Admin SDK) -│ ├── lib/admin.js # Shared Admin SDK bootstrap + key lookup -│ ├── grant-access.js # List / grant / revoke the `approved` claim -│ ├── backup-firestore.js # Dump Firestore → .backups/*.json -│ ├── import-firestore.js # Restore from backup JSON -│ ├── delete-user-data.js # Remove all data for a given UID -│ └── verify-firestore.js # Sanity-check documents in Firestore -├── src/ -│ ├── components/ # All React UI components -│ │ ├── AddBoxModal.jsx -│ │ ├── AddItemModal.jsx -│ │ ├── AuthModal.jsx -│ │ ├── BoxCard.jsx -│ │ ├── BoxList.jsx -│ │ ├── ConfirmationDialog.jsx -│ │ ├── EditBoxModal.jsx -│ │ ├── EditItemModal.jsx -│ │ ├── FullscreenImageModal.jsx -│ │ ├── ImageSlider.jsx -│ │ ├── ImportProgressModal.jsx -│ │ ├── ItemCard.jsx -│ │ ├── ItemList.jsx -│ │ ├── Modal.jsx -│ │ ├── SearchBar.jsx -│ │ ├── SettingsMenu.jsx -│ │ ├── TagManagementModal.jsx -│ │ └── Toast.jsx -│ ├── services/ -│ │ ├── firebaseStorage.js # All Firestore CRUD operations -│ │ └── storage.js # LocalStorage + IndexedDB fallback -│ ├── utils/ -│ │ ├── dateUtils.js # Date formatting helpers -│ │ └── imageUtils.js # Image resize / base64 conversion -│ ├── App.jsx # Root component — all state and view logic -│ ├── firebase.js # Firebase app initialisation and exports -│ ├── index.css # Global styles and CSS custom properties -│ └── main.jsx # React entry point -├── firebase.json # Firebase Hosting config -├── firestore.rules # Firestore Security Rules (deployed from here) -├── firestore.rules.test.mjs # Emulator tests for the rules -├── .firebaserc # Firebase project alias -├── vite.config.js -└── package.json -``` - ### Data model All documents in Firestore are scoped by `userId` so that queries never leak between accounts. -#### Box +#### Box (`boxes`) ```ts { @@ -274,13 +293,16 @@ All documents in Firestore are scoped by `userId` so that queries never leak bet userId: string // Firebase Auth UID name: string description: string - images: string[] // base64 data URLs (resized to max 800×800) - image: string // First image — kept for backward compatibility + location: string // where the box physically is; '' or absent if not set + tags: string[] // lowercase, de-duplicated; shared vocabulary with items + images: { id: string, thumb: string }[] // id -> doc in `images`, thumb inline + image: string | null // thumb of the first image, kept for backward compatibility createdAt: number // Unix timestamp (ms) + updatedAt?: number // set when the box's contents change (item added, moved, removed) } ``` -#### Item +#### Item (`items`) ```ts { @@ -289,17 +311,44 @@ All documents in Firestore are scoped by `userId` so that queries never leak bet boxId: string // UUID of parent box, or '' if unassigned name: string description: string - images: string[] // base64 data URLs (resized to max 800×800) - image: string // First image — kept for backward compatibility - tags: string[] + tags: string[] // lowercase, de-duplicated + images: { id: string, thumb: string }[] + image: string | null // thumb of the first image, kept for backward compatibility createdAt: number // Unix timestamp (ms) modifiedAt: number // Unix timestamp (ms), set on updates } ``` +#### Full-size image (`images`) + +```ts +{ + id: string // UUID v4, referenced from an entity's images[].id + userId: string // Firebase Auth UID + ownerType: 'box' | 'item' + ownerId: string // deleting the box or item deletes its images too + full: string // base64 data URL, ~1024 px + createdAt: number // Unix timestamp (ms) +} +``` + +An in-app import keeps a document's original ID where it is safe to, and +otherwise uses `_`, so an import never duplicates what is +already there. + ### Image storage -Images are resized client-side (max **800 × 800 px**, JPEG quality **0.7**) using the browser Canvas API, then stored as **base64 data URLs** directly in Firestore documents. No Firebase Storage bucket is used. This keeps the architecture simple but does mean large document sizes for image-heavy collections; keep this in mind when planning Firestore read costs. +The project stays on Firebase's free Spark plan, so there is no Cloud Storage +bucket: photos live in Firestore, split into two sizes. Each photo is processed +in the browser (`src/utils/imageUtils.js`) into a **thumbnail** (~256 px, WebP +quality 0.6, a few KB), stored inline on the box or item so lists render with no +extra reads, and a **full image** (~1024 px, WebP quality 0.78), stored as its +own document in `images` and fetched only when opened fullscreen. Full images are +then cached in IndexedDB (`src/utils/imageCache.js`), so each one is downloaded +at most once per device. Browsers that cannot encode WebP get JPEG. + +Older data stored full-size base64 strings directly in `images`; the app still +reads that shape, and **Settings > Optimize Images** converts it in place. ### Admin scripts setup @@ -309,30 +358,34 @@ The scripts in `scripts/` use the **Firebase Admin SDK** and require a service a 2. Save the JSON file to `.secrets/`. That is all — `scripts/lib/admin.js` picks up the first `*.json` it finds there, or the file `$GOOGLE_APPLICATION_CREDENTIALS` points at. ```bash -# Backup all data +# Back up the boxes and items of every account npm run backup -# Import from a specific backup file -node scripts/import-firestore.js .backups/firestore-backup-.json +# Import from a specific backup file (optionally re-owned by another UID) +npm run import -- .backups/firestore-backup-.json [uid] ``` +`npm run backup` dumps the `boxes` and `items` collections only, not `images`, +so it keeps the thumbnails but none of the full-size photos. For a backup with +full photos, use **Settings > Export Data** in the app. + > `.secrets/` and `.backups/` are git-ignored. Never commit service account keys — unlike the web config above, these *are* real credentials, and they grant full admin access to the project. ### Deploying ```bash # Authenticate once -firebase login +npx firebase login -# Deploy (builds first, then deploys to Firebase Hosting) +# Build, then deploy Hosting and the Firestore rules npm run deploy ``` -Or deploy separately: +Or deploy only the site: ```bash npm run build -firebase deploy --only hosting +npx firebase deploy --only hosting ``` ### Building the Android APK @@ -346,7 +399,9 @@ changes — a plugin, a permission, the splash screen. npm run android:release # → android/app/build/outputs/apk/release/app-release.apk ``` -Needs the Android SDK (`android/local.properties` → `sdk.dir`) and a JDK. +Needs the Android SDK (`android/local.properties` → `sdk.dir`) and a JDK 21. +CI builds the signed APK on every release by itself (see *Releases and +versioning*); build one locally to try a native change on a phone first. **Versioning is automatic.** `android/app/build.gradle` reads `package.json` at build time, so `versionName` is the released semver and `versionCode` is it @@ -446,6 +501,12 @@ that need a human, collected in one place so none of them is discovered late. known to work before a release depends on it. The [Releases page](https://github.com/SciScend/StorageBoxOrganizer/releases) has the file; Android asks once for permission to install from that source. +- [ ] **GitHub settings, again after moving the repository.** "Allow GitHub + Actions to create and approve pull requests" must be on in both the + organisation's and the repository's Actions settings, or release-please + cannot open its release PR; and the four signing secrets (*APK signing in + CI* above) must exist, or the APK job fails. Both are in place for + `SciScend/StorageBoxOrganizer`. ### After every merge to `main` @@ -462,18 +523,27 @@ A plugin, a permission, the splash screen, `capacitor.config.json` — anything under `android/`. A change confined to the web app needs none of this; it reaches installed phones through the deploy above. -- [ ] **Build and publish a new APK** — see - [Building the Android APK](#building-the-android-apk) and *Publishing the - APK* above. +- [ ] **Make sure the change is released.** CI builds and attaches the APK only + when a release PR is merged, and only a user-facing PR title (`feat`, + `fix`, ...) opens one - see *Releases and versioning*. To try the change on + a phone before that, see + [Building the Android APK](#building-the-android-apk). +- [ ] **Tell Android users to install the new APK** from the + [Releases page](https://github.com/SciScend/StorageBoxOrganizer/releases). + An installed APK picks up web changes by itself, but not a new native + shell, and the app does not announce one. --- ## 🗺️ Architecture notes -- **Optimistic UI** — State updates happen immediately on the client; if the Firebase write fails, the state reverts and a toast error is shown. -- **Browser history** — `window.history.pushState` is used to make views deep-linkable. The back button navigates between box list → box contents → all items without a full page reload. -- **Dual storage layer** — `src/services/firebaseStorage.js` is the active backend. `src/storage.js` is a self-contained LocalStorage + IndexedDB implementation kept as a local fallback / reference (not wired into the app by default). -- **Tag operations** — Renaming or deleting a tag triggers a Firestore query for all items carrying that tag and batch-updates them. +- **Optimistic UI** - State updates happen immediately on the client; if the Firebase write fails, the state reverts and a toast error is shown. Deletes are held back for a few seconds so the notification can offer Undo, and any still pending are written when the page is hidden. +- **Browser history** - `window.history.pushState` is used to make views deep-linkable. The back button navigates between the box list, a box's contents and all items without a full page reload; on Android the hardware Back button is routed through the same history (`src/native/backHandler.js`). +- **Storage layer** - `src/services/firebaseStorage.js` is the only backend. `src/storage.js` (LocalStorage + IndexedDB) and `src/services/storage.js` (LocalStorage) are older local implementations kept for reference; nothing imports them. +- **Offline** - Firestore runs with a persistent IndexedDB cache (`src/firebase.js`). Writes are not awaited on the server, so an offline save still closes its form, and the SDK sends the queued writes when the connection returns. +- **Tag operations** - Renaming or deleting a tag queries every box and item carrying any spelling of that tag and batch-updates them. +- **Native code** - The app's Android-specific JavaScript is in `src/native/`, guarded by `Capacitor.isNativePlatform()`, so it does nothing in a browser. +- **Translations** - UI strings are in `src/translations/en.json` and `bg.json`; the domain nouns (box, item, tag, photo) are defined once in `terms.*.json`. `src/translations/README.md` (in Bulgarian) explains how to change a word everywhere. --- From 1f9a5d47e47aef0e02eec443681c13503794a716 Mon Sep 17 00:00:00 2001 From: nemsys Date: Wed, 30 Sep 2026 03:51:44 +0300 Subject: [PATCH 2/3] fix: make the box delete and import prompts say what actually happens Assisted-by: claude-opus-5-5 --- src/translations/bg.json | 6 +++--- src/translations/en.json | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/translations/bg.json b/src/translations/bg.json index e299e96..b5b6704 100644 --- a/src/translations/bg.json +++ b/src/translations/bg.json @@ -86,8 +86,8 @@ "box.createdOn": "{{^box.created}} на {{date}}", "box.updatedOn": "{{^box.updated}} на {{date}}", "box.deleteTitle": "Да се изтрие ли {{box.theSubj}}?", - "box.deleteMessageCount_one": "Това изтрива {{box.the}} {{name}} и {{count}} {{item.one}} {{box.in}}. Действието е необратимо.", - "box.deleteMessageCount_other": "Това изтрива {{box.the}} {{name}} и всички {{count}} {{item.counted}} {{box.in}}. Действието е необратимо.", + "box.deleteMessageCount_one": "Това изтрива {{box.the}} {{name}} и {{count}} {{item.one}} {{box.in}}.", + "box.deleteMessageCount_other": "Това изтрива {{box.the}} {{name}} и всички {{count}} {{item.counted}} {{box.in}}.", "box.deleteMessageEmpty": "Това изтрива {{box.the}} {{name}}. Празна е, така че нищо друго не се губи.", "box.emptyTitle": "Още нямаш {{box.many}}", "box.emptyHint": "{{^box.one}} е мястото, където снимаш и описваш какво си опаковал — за да го намериш после, без да разопаковаш.", @@ -305,7 +305,7 @@ "import.phase.optimizingBox": "Оптимизиране на {{box.one}}: {{name}}", "import.phase.optimizingItem": "Оптимизиране на {{item.one}}: {{name}}", "import.confirmTitle": "Да се внесе ли резервното копие?", - "import.confirmMessage": "Данните от резервното копие ще бъдат внесени. В профила ти ще се създадат нови копия на всички {{item.many}} и {{box.many}}. Да продължим ли?", + "import.confirmMessage": "Това внася {{box.theMany}} и {{item.theMany}} от резервното копие. Онези, които вече са в профила ти, се заменят с версията им от копието, а останалите се добавят. Да продължим ли?", "import.success": "Данните са внесени успешно!", "import.failed": "Неуспешно внасяне на данните: {{error}}", "import.invalidFormat": "Невалиден формат на резервното копие", diff --git a/src/translations/en.json b/src/translations/en.json index 8ff65d3..2df1faa 100644 --- a/src/translations/en.json +++ b/src/translations/en.json @@ -86,8 +86,8 @@ "box.createdOn": "{{^box.created}}: {{date}}", "box.updatedOn": "{{^box.updated}}: {{date}}", "box.deleteTitle": "Delete {{^box.one}}?", - "box.deleteMessageCount_one": "This deletes {{box.the}} {{name}} and the {{count}} {{item.one}} {{box.in}}. This cannot be undone.", - "box.deleteMessageCount_other": "This deletes {{box.the}} {{name}} and all {{count}} {{item.counted}} {{box.in}}. This cannot be undone.", + "box.deleteMessageCount_one": "This deletes {{box.the}} {{name}} and the {{count}} {{item.one}} {{box.in}}.", + "box.deleteMessageCount_other": "This deletes {{box.the}} {{name}} and all {{count}} {{item.counted}} {{box.in}}.", "box.deleteMessageEmpty": "This deletes {{box.the}} {{name}}. It is empty, so nothing else is lost.", "box.emptyTitle": "No {{box.many}} yet", "box.emptyHint": "A {{box.one}} is where you photograph and list what you packed, so you can find it later without unpacking.", @@ -305,7 +305,7 @@ "import.phase.optimizingBox": "Optimizing {{box.one}}: {{name}}", "import.phase.optimizingItem": "Optimizing {{item.one}}: {{name}}", "import.confirmTitle": "Import Backup?", - "import.confirmMessage": "This will import data from the backup. Fresh copies of all {{item.many}} and {{box.many}} will be created in your account. Proceed?", + "import.confirmMessage": "This imports {{box.theMany}} and {{item.theMany}} from the backup. Any that are already in your account are replaced by their version in the backup; the rest are added. Proceed?", "import.success": "Data imported successfully!", "import.failed": "Could not import data: {{error}}", "import.invalidFormat": "Invalid backup format", From 5bbfa504da4036ed8a2d57be353a9cfb3ac7c8fe Mon Sep 17 00:00:00 2001 From: nemsys Date: Wed, 30 Sep 2026 03:51:44 +0300 Subject: [PATCH 3/3] fix: include full-size photos in admin backup and user-data deletion Assisted-by: claude-opus-5-5 --- README.md | 14 +++++--------- scripts/backup-firestore.js | 3 ++- scripts/delete-user-data.js | 18 ++++++++++-------- 3 files changed, 17 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 53fd36d..e5b7bb5 100644 --- a/README.md +++ b/README.md @@ -143,9 +143,9 @@ The box menu (the three dots in the box's header) has: - **Export** - **Settings > Export Data** downloads a `.json` file with all boxes, items and their photos. - **Import** - **Settings > Import Data**. Select your `.json` backup; a progress - modal tracks the restore. Importing your own backup again updates the existing - entries instead of adding copies; importing it into another account creates - new ones there. + modal tracks the restore. Boxes and items already in your account are replaced + by their version in the backup and the rest are added, so importing the same + backup twice never creates copies. --- @@ -273,7 +273,7 @@ An unapproved account gets an "Access not approved yet" screen showing its email | `npm run translations:check` | Verify `en`/`bg` string files agree with each other and with the code | | `npm run test:rules` | Run the Firestore security-rules tests against the emulator (needs Java) | | `npm run access` | List / grant / revoke account approval (requires service account) | -| `npm run backup` | Dump the `boxes` and `items` collections to `.backups/` (requires service account) | +| `npm run backup` | Dump the `boxes`, `items` and `images` collections to `.backups/` (requires service account) | | `npm run import -- [uid]` | Import a backup JSON into Firestore, optionally under another user (requires service account) | | `npm run cap:sync` | Build the web app and copy it into the Android project | | `npm run android:open` | Open the Android project in Android Studio | @@ -358,17 +358,13 @@ The scripts in `scripts/` use the **Firebase Admin SDK** and require a service a 2. Save the JSON file to `.secrets/`. That is all — `scripts/lib/admin.js` picks up the first `*.json` it finds there, or the file `$GOOGLE_APPLICATION_CREDENTIALS` points at. ```bash -# Back up the boxes and items of every account +# Back up the boxes, items and photos of every account npm run backup # Import from a specific backup file (optionally re-owned by another UID) npm run import -- .backups/firestore-backup-.json [uid] ``` -`npm run backup` dumps the `boxes` and `items` collections only, not `images`, -so it keeps the thumbnails but none of the full-size photos. For a backup with -full photos, use **Settings > Export Data** in the app. - > `.secrets/` and `.backups/` are git-ignored. Never commit service account keys — unlike the web config above, these *are* real credentials, and they grant full admin access to the project. ### Deploying diff --git a/scripts/backup-firestore.js b/scripts/backup-firestore.js index a25dd2e..87b6510 100644 --- a/scripts/backup-firestore.js +++ b/scripts/backup-firestore.js @@ -17,7 +17,8 @@ async function runBackup() { console.log('Starting Firestore backup using Firebase Admin SDK...'); try { - const collections = ['boxes', 'items']; + // `images` holds the full-size photos; boxes and items carry only thumbnails. + const collections = ['boxes', 'items', 'images']; const backupData = {}; for (const collectionName of collections) { diff --git a/scripts/delete-user-data.js b/scripts/delete-user-data.js index b698e7e..c213881 100644 --- a/scripts/delete-user-data.js +++ b/scripts/delete-user-data.js @@ -66,7 +66,7 @@ async function deleteUserData() { console.log(`****************************************************`); console.log(`* Target User: ${targetEmail}`); console.log(`* Target UID: ${targetUid}`); - console.log(`* Collections: boxes, items`); + console.log(`* Collections: boxes, items, images`); console.log(`****************************************************`); const confirm = await question(`\nTo confirm deletion of ALL data for this user, type "DELETE": `); @@ -78,7 +78,8 @@ async function deleteUserData() { console.log('\nStarting deletion process...'); - const collections = ['boxes', 'items']; + // `images` holds the full-size photos; leaving it out orphans them. + const collections = ['boxes', 'items', 'images']; for (const collectionName of collections) { const snapshot = await db.collection(collectionName).where('userId', '==', targetUid).get(); @@ -90,12 +91,13 @@ async function deleteUserData() { console.log(`- ${collectionName.padEnd(6)}: Deleting ${snapshot.size} documents...`); - const batch = db.batch(); - snapshot.forEach(doc => { - batch.delete(doc.ref); - }); - - await batch.commit(); + // A batch takes at most 500 writes, and a user can have more photos than that. + const docs = snapshot.docs; + for (let i = 0; i < docs.length; i += 400) { + const batch = db.batch(); + docs.slice(i, i + 400).forEach(doc => batch.delete(doc.ref)); + await batch.commit(); + } console.log(` Done.`); }