Relay · FIG

Every order and every return, from checkout to cash, in one place. Relay listens to every FIG storefront (FIG website and app, Women'secret Egypt and Kuwait, Labesny website and app, and figeg.com until the Shopify store launches) and moves each order through the departments that touch it. Every team sees where each order is and who has it right now.

New → Confirming → Finance check → Ready to pick → Picking → Packed → Shipped → Out for delivery → Delivered → Settled
       Customer care   Finance        └──────── Fulfilment ────────┘   └──────── Shipping ────────┘   Finance (courier cash)
Off-track: Cancelled · Returning to origin (refused) → RTO closed
Returns:   Requested → Approved → Pickup → In transit → Received → Inspected → Refund pending → Refunded

Built as a web dashboard first. Every screen works at phone width, and /api/* is the base for the mobile app.

Run it

npm install
npm run seed      # a month of demo trading (stop `npm run dev` first; the embedded DB is single-process)
npm run dev       # http://localhost:3400

Signed out, / is the landing page; staff sign in from its header (password, or Google when GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET are set). Locally, GOOGLE_MOCK=1 puts a stand-in account chooser behind "Continue with Google": pick any seeded teammate (*@relay.local) to see exactly what that job sees. An admin can rebuild the demo floor from Rules & SLAs.

Going live: see deploy/README.md (one server: the console, Postgres, HTTPS, nightly backups).

No database to install: locally Relay runs an embedded Postgres (PGlite) in .data/. In production, set DATABASE_URL to a real Postgres. The same migrations (drizzle/) run on start in both cases.

What's smart about it

• Autopilot clears hand-offs that need no judgement and writes why on the timeline. Paid online orders skip the confirmation call. Trusted cash customers skip it too. Low-risk cash orders under a value limit clear finance, and prepaid deliveries close themselves. Tune or switch off in Rules & SLAs.
• Delivery-risk score (0–100) on every order, with named reasons. It counts past refusals across every store (customers are matched by phone), invalid phones, thin addresses, duplicate orders, unusual basket size, and size bracketing (one piece in three sizes). It also learns the refusal rate for each governorate from this floor's own history.
• Relay noticed: plain-language findings, each computed by a query and linked to where you act on it:
  • the stage that's the bottleneck
  • parcels the courier has gone quiet on
  • refusal hotspots
  • a product that keeps coming back "too small"
  • a short Aramex remittance
  • cash still with the courier
  • try-on baskets to call about
  • how much Autopilot saved
• SLA clocks on every stage, paused by holds, with live countdowns and late flags everywhere.
• Ask Relay (⌘J): questions in plain words, answered by Claude from live data through tools that run with the asker's own access. Without an API key it still answers with the computed findings.
• Live floor: every hand-off streams to every open screen (server-sent events), with presence.

Access

A job preset plus a level per area, and an optional store scope. For example, the Kuwait team only ever sees Kuwait.

Area	Levels
Orders, Confirmation, Finance, Pick & pack, Shipping, Returns desk	hidden · view · act · manage
Customer data	masked · name & city · full contact
Money	hidden · totals · payments · refunds
Insights, Channels, Team, Rules	hidden · view · edit · manage
Command centre (the whole floor: Command centre + Pipeline)	hidden · view
Stock, Purchasing, Warehouse work, Merchandising	hidden · view · act · manage

Pages are need-to-know. PAGES in src/lib/domain/perms.ts says which levels open each page; the menu, the phone tabs, the palette and every page guard read it, so what is offered and what opens never differ. Someone without the Command centre lands on their own first page (care on Confirm, the warehouse on Pick & pack). Team & access → What each job sees lists each job's pages; page-access.test.ts pins them. A teammate's stored access is only where they differ from their job, so improving a preset reaches everyone on that job.

Rules that always hold:

• Every stage change is checked on the server against the area that owns that hand-off.
• Nobody can grant more than they hold. Only an admin grants admin. The last active admin can't be switched off.
• Five wrong passwords lock an account for 15 minutes.
• New teammates get a one-time join link (7 days) and set their own password.

Connecting the stores

Everything is in .env.example, and /channels shows what each store still needs, its webhook address, and a Check connection button that verifies the token and its scopes.

• Shopify (FIG, Women'secret EG/KW, Labesny): Admin GraphQL 2025-07, incremental pull plus signed webhooks. App orders that FIG's Medusa apps push into Shopify are filed under the app channel and de-duplicated against the direct Medusa feed.
• Medusa (FIG app, Labesny app): admin API with a secret API key.
• WooCommerce (figeg.com): REST v3 until the Shopify store launches.
• Aramex: tracking moves orders to out for delivery, delivered, or refused, and flags exceptions. Shipment creation is only drafted. Real creation needs an explicit go-ahead, because the account is shared with the live website.
• Lucida: stock by barcode (both company databases are merged; the username picks the database).
• Write-back (RELAY_WRITE_BACK=true): sends fulfilment and tracking to Shopify, marks COD orders paid when settled, and adds relay:<stage> tags. It never replaces a tag list, and every attempt is logged on the timeline.

Store facts only ever move an order forward. A late webhook can't undo work the floor already did.

Checks

npx tsc --noEmit && npm run lint && npm test && npm run build

Layout

src/lib/domain/     pure rules: stages & transitions, access, risk, autopilot, SLAs, return policies
src/lib/engine.ts   the only path that changes an order or a return (ingest, move, hold, note, return)
src/lib/connectors/ Shopify, Medusa, WooCommerce, Aramex, Lucida (pure mappers + tested)
src/lib/sync.ts     pull + courier tracking; /api/webhooks/[platform]/[channel]; /api/cron
src/lib/insights.ts "Relay noticed"   src/lib/copilot/ Ask Relay tools
src/app/(console)/  command centre, orders, pipeline, queues, returns, cash, insights, setup
src/seed/           the demo floor (fictional people, real public catalogue)