The code, interface, old-engine integration, account API, migration SQL, tests, installable web-app files and Windows helper scripts are included. The published frontend can be explored with **Explore sandbox**. Nothing is connected to your old live database.
What still needs your account access: creating a new Supabase project, authorizing its backend deployment, setting its two application secrets, creating your private owner password, and choosing your final domain/hosting account. Do not send any password, service-role key or access token in chat.
1. Open the provided private website link while signed into the ChatGPT account that owns it.
2. Click **Explore sandbox**. The yellow banner always identifies local test mode.
3. Test the dashboard, zones, search, repeated pallets, loading, driver lists, CSV and reports.
4. Use the sandbox role selector to inspect the included role experiences. It changes only
local test identity; it grants no access to an online warehouse.
5. Test team-account forms. Sandbox identities do not accept real passwords.
6. Changes remain in this browser's isolated sandbox dataset, separate from production.
The private preview is a convenient review host. Its owner-private access is an additional outer gate, so it is not the final staff-wide hosting arrangement. For ordinary workers, use Cloudflare Pages (below) and the app's own accounts. No paid hosting is needed to inspect this frontend; Supabase free-tier limits still apply when you connect a free project.
1. Visit https://supabase.com/dashboard and sign into your own account.
2. Create a NEW project, named for example `aram-warehouse-test`. Start on the free tier.
Keep your old warehouse project untouched.
3. Choose a region appropriate to your users. Compare connection time from the warehouse
before committing; geographic proximity alone does not prove the fastest route.
4. Create and save the database password privately. Wait until the project is ready.
5. In project settings/API settings, copy the project URL and the publishable key (or legacy
anon key). These two are public frontend values. Do NOT copy service-role/secret credentials.
6. In Auth settings, disable public signups for the warehouse. Accounts are provisioned by
the application administrator. Password signup must not automatically create an account.
7. Supabase Auth stores the passwords. Usernames are mapped by the backend to internal
confirmed Auth identifiers; workers do not need to receive an email to use this setup.
1. Download the source ZIP and extract it to a simple path such as `C:\ARAM-Warehouse`.
2. Install Node.js LTS from https://nodejs.org if Node is not already installed. Python,
XAMPP, PHP and Docker are not required for the frontend or API-based function deployment.
3. Double-click `scripts\deploy-backend.cmd`.
4. When asked for the project reference, enter the ID portion of your NEW project URL:
for `https://abcdefghijkl.supabase.co`, the reference is `abcdefghijkl`.
5. The Supabase CLI login will open a browser. Complete the sign-in/verification yourself.
6. If prompted, enter the NEW project's database password in that local CLI prompt.
7. `db push` installs `supabase/migrations/001_accounts.sql`. Review its proposed migration
before confirming. It creates only the new `aram_*` tables/functions.
8. The helper deploys `warehouse-api` with `--use-api --no-verify-jwt`. This does NOT make
warehouse data public: the handler explicitly validates each session with Supabase Auth, then checks the provisioned account, active session and action permissions. Public routes are limited to setup status, login, refresh and secret-protected one-time bootstrap.
9. If any step fails, the helper stops. Fix that error before continuing.
Manual equivalent, from the extracted project folder:
npx --yes supabase@latest login npx --yes supabase@latest link --project-ref YOUR_NEW_PROJECT_REF npx --yes supabase@latest db push npx --yes supabase@latest functions deploy warehouse-api --use-api --no-verify-jwt
Never run the OLD project's SUPABASE_SETUP_COMPLETE.sql, legacy save functions or anonymous write grants on this new system. Only this package's migration belongs to this backend.
1. Open Supabase → Edge Functions → Secrets (the exact menu title can vary).
2. Add `WAREHOUSE_ALLOWED_ORIGINS`: the exact frontend origin, e.g.
`https://your-warehouse.pages.dev`, without a path or trailing slash. For several frontends, provide comma-separated origins. Add the private preview origin only if using it to test.
3. Add `WAREHOUSE_BOOTSTRAP_SECRET`: a new random secret of at least 32 characters.
You can generate 48 random bytes on your PC with:
node -e "console.log(require('node:crypto').randomBytes(48).toString('hex'))"
4. Keep the bootstrap secret privately until the owner is created. Do not commit it into Git.
5. Supabase normally supplies SUPABASE_URL, SUPABASE_ANON_KEY and SUPABASE_SERVICE_ROLE_KEY
inside Edge Functions. If they are absent, set them privately in the backend environment; the service-role key must never be put in the website or shared in chat.
6. Remove `WAREHOUSE_BOOTSTRAP_SECRET` after the first owner has been created. The database
also prevents creating a second initial owner through bootstrap.
1. Double-click `scripts\configure-and-build.cmd`.
2. Enter the NEW project URL and its publishable/anon key when asked. The script rejects
obvious secret/service-role keys. These public values go into `public/runtime-config.js`.
3. The script runs checks/tests and produces the `dist` folder. No service credentials go there.
4. Sign into your Cloudflare account. Open Workers & Pages and create a Pages project with
a direct-upload/static deployment. Upload the CONTENTS of `dist`, or the zipped dist folder if that upload interface requests a ZIP. Your website root must contain index.html.
5. Open the resulting HTTPS pages.dev address. Copy its origin into WAREHOUSE_ALLOWED_ORIGINS
in Supabase, as described above. A static frontend alone is not a deployed backend.
6. Open **Connect workspace** if public connection values were not baked into the deployment.
Enter the same project URL and publishable key, then select Save & check connection.
7. A configured response confirms only reachability/initialization; it is not a full acceptance test.
8. For Git deployment, push this repository to your own private repository, use build command
`npm run build` and output directory `dist`. Do not commit `.env` files or secrets.
1. On the new app, open Connect workspace → Create first superadmin.
2. Enter the bootstrap secret from Part D, a unique username, your display name and a NEW
password of at least 8 characters. A username uses 3–40 English letters/numbers plus dot, dash or underscore. Your display name may use Sorani Kurdish or Arabic.
3. Submit. After creation, sign in with the username and password. Remove the bootstrap secret
from the server's secrets, and keep a second trusted superadmin account for recovery.
4. There are no default live passwords. Old role codes no longer authenticate accounts.
5. If you lose every superadmin password, recovery requires your Supabase owner access;
the website has no public password-reset loophole. This first version uses admin-assisted resets rather than email reset delivery for internal username identities.
1. Open Team accounts → Add account.
2. Enter username, display name, role and initial password.
3. For a Driver account, choose an existing driver. Create drivers in Drivers & dispatch first.
4. Save. Give the initial password to that worker through a private channel.
5. The first real login requires a password change before warehouse API operations are allowed.
6. Superadmin can manage all roles/permission overrides. Admin may manage lower worker roles,
but cannot grant admin/superadmin or permission overrides.
7. Disabling an account prevents API access. Role/account changes and password resets revoke
sessions as documented in the account UI. Session revocation is enforced server-side.
8. The last active superadmin cannot be disabled/demoted by normal account operations.
1. In the old V96.2 app, let all pending sync finish. Export a JSON backup with needed sections.
2. Keep that original backup unchanged and retain your OLD deployment as a rollback option.
3. Sign into the new app as superadmin. Open Import & recovery and choose the JSON file.
4. Review the preview counts. This import route accepts up to 12 MiB; for larger backups,
use section-by-section imports through the inherited scoped backup tools.
5. Choose Merge warehouse data. A pre-import recovery JSON downloads before the operation.
Save it. Download initiation does not prove you have saved the recovery file successfully.
6. The importer merges placements, driver lists, CSV lists, markets, loading, products,
recycle records and history. It deliberately does not import legacy device privileges, role password codes or UI/account permission sections through this simple route.
7. Create real worker accounts. Use Historical ownership mapping to map old device IDs to
new account IDs for active placements and restorable/loading metadata. Historical event logs retain original attribution.
8. Verify counts, several repeated-pallet examples, loaded undo and driver lists before workers
switch. Do not let the old and new systems both be authoritative for the same work.
9. To restore product photos, copy your original `images` folder into `public/engine/images`
and rebuild/redeploy. This source attachment did not contain those original photos.
1. Open the HTTPS app in Chrome/Edge on Windows, or Chrome on Android.
2. Use the browser's Install app / Add to Home Screen option. The Settings screen may also
show Install on this device when the browser provides the install prompt.
3. Sign into a real account ONLINE first. Open the main workflows and catalogs once.
4. The service worker caches core static files. Operational changes are queued separately
per account on that browser, then validated again by the server on reconnect.
5. Do not clear browser/app storage while changes are pending. Logging out retains that
account's queue; another account's queue is not replayed as the current account.
6. Offline cached sessions cannot learn about account disabling/permission changes until
reconnect. The server rejects any subsequently unauthorized operation. Local visibility on a trusted device is not equivalent to live server authorization.
7. Background synchronization while the app is closed is not guaranteed by this first web
release. Reopen it to flush pending work. Excel generation still needs its inherited CDN engine to have loaded; PDFs use bundled assets. Original product images need separate storage.
Run these on a new test project with at least two devices, then repeat with a copied dataset:
- Sign in with all seven roles; test wrong passwords, disabled accounts and revoked sessions.
- Confirm a worker cannot change their role through the UI or a direct API request.
- Place the same market twice, in the same and different zones; verify IDs, positions and names.
- Check empty slots, insert-before, reindex, own-placement removal, recycle/restore and undo.
- Let two assigners add different records at the same time; ensure both survive.
- Add selected/all search results to a driver; transfer, sort/reorder and remove selected items.
- Load/undo with different drivers and multiple panes; verify every restored pallet.
- Mark done/missing, verify quantities and reports, and reset checking.
- Import directory and invoice CSVs, including duplicate headings and ambiguous names.
- Generate/share CSV/PDF/Excel, test custom column/layout settings and inspect Sorani text.
- Backup selected sections, restore into test data and verify checksums/recovery.
- Disconnect the network, make changes, close/reopen, reconnect and verify server confirmation.
- Disable a worker from another session and verify that further server writes fail.
- Test password reset, first-login change and last-superadmin protection on the REAL database.
- Compare database projected placements/drivers/checks/loads with the compatibility document.
The included 38 automated tests and browser sandbox checks do not replace PostgreSQL, real Auth, device testing or full workflow acceptance. Do not use a free development project as a promise of uninterrupted production service. Upgrade the database plan when staff begin depending on it, and configure external backups/monitoring and restore drills.
**Origin not allowed:** add the exact HTTPS origin to WAREHOUSE_ALLOWED_ORIGINS. A pages.dev preview subdomain and a custom domain are different origins.
**Backend unavailable / migration missing:** finish db push, inspect Edge Function logs and verify server secrets. The UI retains queued operations; do not clear its storage.
**Invalid JWT at the platform before handler runs:** redeploy warehouse-api with `--no-verify-jwt`. Application JWT/account/session checks must remain enabled in api.mjs.
**Initial password change required:** Settings → Change password, then reload the workspace.
**A change remains pending:** inspect the displayed reason. Access may have changed, the project may be paused/at quota, or a submitted record may need correction. Do not label it server-saved until acknowledged. This first release retains failed batches for diagnosis; ask for help rather than deleting the queue.
**Photos missing:** original images were excluded. Copy the real folder; metadata alone cannot recreate the original photos.
**Owner-private preview blocks workers:** deploy dist/ to your own Cloudflare Pages site. The app's account login then governs staff access without the preview host's outer gate.
- https://supabase.com/docs/guides/functions/quickstart
- https://supabase.com/docs/guides/functions/secrets
- https://supabase.com/docs/reference/javascript/auth-admin-createuser
- https://developers.cloudflare.com/pages/get-started/direct-upload/