Mahmood Shah Auto Recycler

Shared parts inventory, sales, and profit reporting for a Vancouver auto recycler. Four partners, one shelf, four phones.

The problem it solves: when a customer messages one partner asking "do you have a front bumper for a 2016 Civic", that partner can now answer in seconds — and cannot promise a part another partner sold an hour ago.

---

Stack

Framework	Next.js 16 (App Router, TypeScript, Turbopack)
Database, auth, storage, realtime	Supabase (Postgres 15+)
Styling	Tailwind CSS v4, Radix primitives
Install	PWA — home screen, no app store
Deploy	Vercel
Currency	CAD, stored as integer cents everywhere
Time	Stored UTC, displayed America/Vancouver

---

Getting it running

1. Create a Supabase project

At supabase.com. The free tier is enough to start.

2. Environment

cp .env.example .env.local

Fill in, from Project Settings → API and → Database:

Variable	Where
NEXT_PUBLIC_SUPABASE_URL	Settings → API → Project URL
NEXT_PUBLIC_SUPABASE_ANON_KEY	Settings → API → publishable / anon key
SUPABASE_DB_URL	Settings → Database → Connection string (URI)

SUPABASE_DB_URL carries the database password, so URL-encode any special characters in it — @ becomes %40. It is used only by the scripts below, never by the app.

SUPABASE_SERVICE_ROLE_KEY is optional and currently unused: migrating, seeding, and creating accounts all run over the database connection.

3. Apply the migrations

npm run db:migrate

Applies every file in supabase/migrations/ in order, each in its own transaction, and records what it ran in app_migrations.schema_migrations so re-running is safe. npm run db:status shows what is applied.

4. Load the parts catalog

npm run seed:catalog    # catalog only -- this is what production wants
npm run seed            # catalog + a demo yard to look around

The catalog is reference data: vehicles cannot generate a parts list without it. The demo yard is demo data, tagged [demo] on every row and removable with npm run seed:clear-demo.

5. Create the accounts

Fill the SEED_* variables in .env.local with the four partners (one as owner), then:

npm run seed:users      # create them
npm run team            # list who exists

Everyone should change their password after their first sign-in. Accounts can equally be added from the Supabase dashboard under Authentication → Users; the profile row and role are created automatically by a trigger either way.

6. Check it

npm run verify          # typecheck, unit tests, migration harness
npm run verify:live     # the same guarantees against the real project

verify:live is worth running after any schema change. It exercises the guarantees as the real roles through the real auth trigger, inside a transaction that is always rolled back, and then again over HTTP through PostgREST with a real JWT.

7. Go

npm run dev

Commands

Command	What it does
npm run dev	Development server
npm run build	Production build
npm run verify	Typecheck + unit tests + migration harness (offline)
npm run verify:live	Guarantee check + API smoke test against the real project
npm run typecheck	tsc --noEmit
npm test	Unit and architectural tests
npm run lint	ESLint
npm run db:verify	Applies every migration to a throwaway Postgres and asserts the guarantees
npm run db:migrate	Apply pending migrations to the live project
npm run db:status	Which migrations have been applied
npm run db:check	Guarantees, live, in a rolled-back transaction
npm run db:smoke	Guarantees, live, over HTTP with a real JWT
npm run db:inspect	Read-only look at extensions, roles, tables, buckets
npm run seed	Catalog + demo yard
npm run seed:catalog	Catalog only (production)
npm run seed:clear-demo	Remove every demo row
npm run seed:users	Create the partner accounts from .env.local
npm run team	List the accounts that exist
npm run icons:generate	Re-render the PWA icons from the app mark

---

Deploying to Vercel

1. Push to a Git repository and import it at vercel.com.
2. Add the three Supabase variables plus NEXT_PUBLIC_ENABLE_STOREFRONT=false under Settings → Environment Variables.
3. In Supabase, add your Vercel URL under Authentication → URL Configuration → Site URL and Redirect URLs.
4. Deploy. Open it on a phone and use Add to Home Screen.

---

The guarantees, and how they are held

These are enforced in the database, not the interface. npm run db:verify applies every migration to a real Postgres (via PGlite) and asserts each one.

A part can never be sold twice

sell_part() carries its own status guard:

update public.parts set status = 'sold'
 where id = p_part_id and status in ('available', 'reserved')

If that affects zero rows, the caller gets a payload naming who won, when, and for how much — "Already sold by Ahmad for $180.00, 4 minutes ago." Never a silent failure. sales.part_id also carries a unique constraint, so even a bug in the function cannot produce two sales. The status flip and the sales row share one transaction.

A staff account can never see costs or profit

Three independent layers, because one is not enough:

1. REVOKE SELECT on the five cost columns of vehicles from authenticated. No query — not even select * — can return them.
2. Costs are readable only through vehicle_finance, a security-definer view whose WHERE clause calls has_finance_access(). It returns zero rows to staff.
3. Every reporting function re-checks the role on entry and raises insufficient_privilege. dashboard_stats() omits the money keys entirely rather than sending nulls.

Catalog edits never rewrite history

parts snapshots name, category, and icon_key at creation. Renaming a catalog entry changes what future vehicles generate and nothing else.

Money is integer cents, everywhere

Every currency column is bigint. parseMoneyToCents() reads the digits out of the string rather than multiplying a float — Math.round(1.005 * 100) is 100, not 101, because the nearest double to 1.005 is 1.00499999999999989. Covered by tests/money.test.ts.

Destructive actions are confirmed and logged

Deleting a vehicle or part requires confirmation and writes to activity_log before the row disappears. Deleting a vehicle that has recorded sales is refused outright, not confirmed — it would erase that revenue from every report.

Reservations cannot become ghost holds

A hold sets reserved_until 48 hours out. expire_reservations() returns expired parts to the shelf and logs a notice against the partner who placed the hold. It reads the holds before clearing them, because UPDATE ... RETURNING hands back the new row where reserved_by is already null. FOR UPDATE SKIP LOCKED keeps four phones sweeping at once from piling up.

---

Architecture notes

Search

One RPC, one trigram index. parts.search_text denormalises the part name, side, category, and its vehicle's year/make/model/trim/stock number, so "civic mirror" matches across the join in a single pass and "bumpr" still finds a front bumper cover. Every whitespace token must match, either as a substring or by trigram word similarity.

The search screen queries Supabase directly from the browser rather than through a Next.js route, so results land while the partner is still mid-sentence. A request-id guard stops a slow early response overwriting a fresher one.

Realtime

parts is in the supabase_realtime publication with REPLICA IDENTITY FULL. A status change patches the matching row on the other three phones — greys it out, flashes it, and says what happened. Your own actions don't toast: the optimistic update already set that status, so the equality check short-circuits.

Cost allocation

Stated once, in 0006_reporting.sql, and used consistently: a sold part is charged a share of its vehicle's total invested cost, proportional to its asking price against the sum of asking prices of every non-scrapped part on that vehicle. Where a vehicle has no asking prices at all, cost is split evenly by part count. The monthly report says this on screen.

The two profit figures

The monthly report shows net profit (cash basis) and gross profit on parts sold (allocated cost basis) side by side, each labelled with its basis. Cash basis alone makes any month with three cars bought in it look like a disaster; the allocated figure says whether the business is actually working. Neither is presented as "the" profit.

Storefront isolation

src/lib/data/public-shop.ts builds its own anonymous Supabase client and touches only public_parts and search_public_parts — the only two objects granted to anon. The view carries no cost, shelf, VIN, note, or internal asking-price column, so there is nothing there to leak. tests/isolation.test.ts fails if a future edit imports an authenticated client into that layer or a /shop route.

Part slugs (2016-honda-civic-front-bumper-cover-v0147-1) are generated at creation, so public URLs are correct from day one and never change.

Service worker

Caches the app shell only: hashed build output, icons, and one static /offline page. No HTML page is ever cached — every screen is a signed-in view of shared data, and a cached page could show a stale shelf or appear on a different account after a sign-out. Navigations always hit the network and fall back to /offline.

---

Roles

	Add a car	Search & sell	Edit parts	Vehicle costs	Reports	Expenses	Edit / delete a car	Team
owner	✅	✅	✅	✅	✅	✅	✅	✅
partner	✅	✅	✅	—	—	—	—	—
staff	✅	✅	✅	—	—	—	—	—

Partners and staff run the yard: they book cars in, trim the parts list, price parts, and sell them. What a car cost, what it made, and whether it stays are the owner's. A partner adding a car simply gets no cost fields — and the RLS policy refuses a priced insert from them regardless, so the form is a convenience, not the control.

---

Two ways a car makes money

Every vehicle carries a plan, chosen when it is booked in.

Part it out — the default, and what most ICBC salvage is for. Saving the car generates the full parts list; you trim it down on the next screen and sell from the shelf.

Repair and sell whole — bought at auction or off Facebook Marketplace, fixed, inspected, and sold as a car. No parts list is generated. Repair, inspection, transport and anything else spent on it goes in under Expenses, against that vehicle, because those costs arrive over weeks rather than at the auction. What it sold for is recorded on the edit screen, and vehicle_pnl() counts it as revenue next to parts and scrap.

The title field decides what is even possible. A car branded non_repairable or write_off can never be road-legal again in BC, so it is locked to the part-out path in the form and in the server action — neither trusts the other.

---

Turning the storefront on

The plumbing is live from day one; the shop is not.

1. Publish parts: open a vehicle → Select → choose parts → Publish. Public prices default to the asking price so nothing lists without a number on it.
2. Set NEXT_PUBLIC_ENABLE_STOREFRONT=true and redeploy.

/shop returns 404 until that flag flips. There is no cart — prices are shown in full and buyers are asked to get in touch.

---

Design decisions worth knowing

• Light theme is the default. This app is used outdoors in Vancouver daylight. Dark mode is a toggle in More.
• The accent is steel blue, not amber. Amber is spent entirely on the reserved status, so it cannot also be the brand colour.
• Status is always a filled pill carrying the word. Colour alone is not a signal you can rely on in bright light or if you are colour blind.
• Primary actions sit at the bottom of every sheet, never the top. That is where the thumb is.
• The trim screen leads with bulk actions. The catalog in this build generates 268 parts per vehicle, not the ~150 the original spec estimated — so whole-category toggles and a "high value only" button are the primary interaction, not a secondary one.

---

Why the app is pinned to pdx1

Every screen reads live data, so each page render makes several sequential round trips to Supabase. Where those two run matters more than anything else in the request.

Vercel places functions in iad1 (Virginia) by default. This project's database answers a TCP connect from Vancouver in about 16 ms, which puts it in US West. Left on the default, every query would cross the continent and back — roughly 130 ms each, several times per page.

vercel.json therefore pins functions to pdx1 (Portland), alongside the database.

If the Supabase project is ever moved, change that one line to match. Vercel's region codes are in the deployment's X-Vercel-Id header: the second segment is where the function actually ran.

curl -sI https://your-app.vercel.app/login | grep -i x-vercel-id
# x-vercel-id: pdx1::pdx1::...
#              ^edge  ^function -- these two should match your database

Hobby plans allow one region, which is all this needs.