Diamond Stone Platform: Client Portal

Date: 2026-11-11. Revision 1. Status: draft for owner review. One of three customer-facing parts, each with its own document: this one, docs/WEBSITE.md (public website) and docs/STORE.md (online store). Rules they share are in docs/BRAND.md and docs/DESIGN.md.

1. What it is, and what it is not

The portal is where a customer who already has a quote or an order follows it, approves, pays, receives and gets help. It is the customer's side of the same records the staff work on, so nothing is typed twice and the customer never sees a copy that is out of date.

	Client portal	Public website	Store
Who	A known customer, signed in	Anyone	Anyone; pays online
Purpose	Follow and act on their own quotes and orders	Be found, convince, capture an enquiry	Order samples without talking to anyone
Signed in	Yes: phone number and code once, then a passkey	No	No account needed; an order number and a link
Address	`portal.`	The main address	`/store` on the main address
Shell	A line of words with counts, and the bar: "WhatsApp" at the left, the page's action at the right. No Halo, Stream or Omnibar	The same bar; one action per page	The same bar; a basket
Prices	Their own quote and invoices	None	The price of samples only

2. Who uses it

One customer company can have several people, each with one role.

Role	Can
Administrator	Everything below, and add or remove their colleagues
Approver	Accept quotes, approve the range and the layout
Payer	See invoices and statements, send payment proof
Viewer	Follow orders, download documents

Staff create the first person at a customer as its administrator. From then on the customer manages their own people. A person can belong to more than one company (a consultant on two clients' projects) and switches between them under "Me".

Customers who are traders sell the stone on to their own customers. They use the same portal with different rules: they are never asked for site photographs or who their customer is, and they get a reseller pack of unbranded photographs and datasheets (docs/CONTENT.md section 14).

3. What the customer needs, in order

Taken from the buyer research (docs/BRAND.md section 5): the fears are the wrong stone, a late delivery, and being blamed. So:

Is my order all right? The answer is on the first screen without a tap.
Will it match what I approved? The range, approved before they accept the quote; then the layout of their own job (or photographs of the actual pieces, for a small order), approved before loading.
When does it arrive? A date, a route line, and a message on each real event.
What do you need from me? Shown in the line of words with counts: to approve, to pay, to confirm the site.
Where are my papers? Every document for the order, in one place.
Who do I talk to? A named person with a face, one tap from every screen.

4. Screens

● drawn in the sketch · ◐ specified · ○ still to draw.

Screen	Their question	Shows first	Action
Your orders	Is everything all right?	The order that is moving: stone photo, a thin progress line with its stage in words, next date	Open	◐
Order	Where is it?	Stone photo; route line with the truck or vessel; the progress line with its stage in words; their contact	Message	●
Quote	Is this what I asked for, and how much?	Stone photo; validity, lead time, stock; total with VAT, opening to its lines	Accept	●
Ask for a change, or decline	Can it be different?	The quote with the line they want changed	Send	○
Approve the range	Is this the range I will get?	The lightest, the typical and the most veined piece, full screen, swipe through. Before the quote is accepted	Approve, or ask	●
Approve the layout	Is this my job?	Their own job laid out and numbered, full screen; tap a piece to ask for a change. For a small order, photographs of the actual pieces. Before loading	Approve, or ask for a change	●
Pay	How much, and how?	Amount due; bank details with copy; a place for the transfer slip	Send proof	●
Invoices and statement	What do I owe?	Total owed; invoices as rows, each marked paid or due	Download	◐
Documents	Where are my papers?	One list per order: invoice, packing list, photos, test report, delivery note	Send all	●
Delivery	When, and am I ready?	A week strip to pick the day and half-day; three site checks; who receives; map pin	Confirm	●
Delivered	Did it go well?	Photo of the delivery; slabs, on time, photos; five stars	Send	●
Report a problem	Something is wrong	Camera first; then what and how many	Send	○
My cases	What is happening with my problem?	Cases with a status and a named owner	Open	◐
Messages	Can I ask something?	The conversation with their contact; continues on WhatsApp if they prefer	Send	○
Help	How do I…?	Six picture topics; their open case; their contact	Talk to us	●
Samples	Can I see it first?	Samples requested with courier dots	Request	○
Order again	Same as last time	The last order, editable	Ask for a quote	○
Saved stones	What did I like?	Stone tiles	Request samples	○
Our projects	Which site is this for?	Their sites as cards with open orders	Open	○
Our people	Who else can see this?	Faces with roles	Add	○
Company details	Are our details right?	Legal name, tax number, addresses	Edit	○
Me	Alerts, devices, language			○

The customer's Halo

Superseded on 12 November 2026 by docs/SITE-DESIGN.md section 13 and "The portal's look" below. Kept for history; do not build from it.

At most five rings, each something they can act on: You; Approve (material or a quote); Pay; the order moving; their contact. With nothing waiting, the Halo shows only "You" and their contact, and the first screen says everything is on track.

Getting in

A link in a WhatsApp or email message opens the exact record. The first time, they give their phone number and a code and create a passkey; after that, a fingerprint.
On a computer they scan a code with their phone.
A link never shows anything by itself: the record appears only after sign-in.

5. What the portal must never show

Enforced by the server, not by hiding things on the screen:

Another customer's anything.
Cost, margin, supplier names, quarry names (public and customers see "Oman").
Staff notes, internal messages, the audit trail.
Lots held for someone else.
Where the stone was collected. For a back-to-back order the stone travels straight from the factory. The customer sees the city at most, never the factory, its address or its position on a map.
The truck's exact position until it is in the general area allowed by the administrator; before that, stages and an area only.
The driver: no name, phone number, card or licence, unless the administrator has chosen to show a first name. The customer's contact is always their Diamond Stone person.

These three are settings with defaults (docs/MODULES.md section 12), and the portal's "Order" screen is drawn both ways in the sketch.

6. How it connects

The customer does	Staff see	Money
Approves the range	Sales: the quote can now be accepted	None
Accepts a quote	Sales: a ring; the order is created; the proforma is sent	None yet
Sends payment proof	Accountant: a ring with the slip beside the invoice	On acceptance: bank, customer advance
Approves the layout, or the photographs of the actual pieces	Purchasing: the job is released for packing and loading	None
Confirms the site and day	Shipping: the delivery is booked	None
Receives and rates	Accountant: delivered, so invoice; owner's dashboard: the rating	Revenue recognised on the signed delivery
Reports a problem	A case with a named owner and a reply timer	A claim, if accepted

Every one of these sends the customer a message on the channel they chose, and each message opens the same record.

7. Messages the portal sends

On real events only, never on a timer alone: quote ready; range ready to approve; quote about to expire; order confirmed; layout (or photographs of the pieces) ready to approve; payment received; loaded; left; at the border or port; arriving tomorrow; delivered; documents ready; how did it go. Each has its own switch (docs/MODULES.md section 9). The customer chooses WhatsApp or email and quiet hours under "Me".

8. Measures

Measure	Target to set
Customers who open the portal within a day of the first link
Time from "ready to approve" to approved
Orders where the customer never had to ask "where is it?"
Rating after delivery; share of orders rated
Problems reported through the portal rather than by phone

9. Decisions

Whether customers may pay online by card in the portal, or by bank transfer with proof only (the first release assumes transfer with proof).
~~Whether a customer sees a live map of the truck.~~ Settled as a setting: by default only once the truck is in the general area (docs/MODULES.md section 12).
Whether the portal shows a price list to trade customers, or prices appear only in quotes (this plan: quotes only).
Arabic from the first release, or English first.

Documents and terms (added 11 November 2026)

The customer sees every paper of an order in one list, opens or downloads the stored PDF, accepts a quote with its terms (three key terms in plain words, the full text one tap away, confirmed with passkey), and can check any paper from its code. Statements always need sign-in. See docs/DOCUMENTS.md.

Currency, and the customer's Halo (added 11 November 2026)

The customer sees every amount in their own currency and never a rial equivalent (docs/CURRENCY.md). Customers who are traders, and any customer with more than five open orders, may choose which orders to watch in their line of words (the portal has no Halo: see "The portal's look" below).

Installing (added 11 November 2026)

The portal works fully in a browser tab. Adding it to the home screen is offered once, after a useful moment, and never pressed. On iPhones it is offered only for alerts, because links from messages still open Safari. See docs/INSTALL.md section 4.

The portal's look (added 11 November 2026, by the owner's request)

The portal now takes the public website's look (docs/SITE-DESIGN.md section 13), not the staff app's. The customer's Halo becomes one line of words with counts ("To approve 1 · To pay 1 · On the way · Papers") and the Omnibar becomes the bar: the word "WhatsApp" at the left, the order's next step at the right, always visible. What a customer can see and do is unchanged. It also gets tablet and desk layouts. All portal screens are redrawn in docs/ui-shell-mockup.html.

Matching (added 11 November 2026)

The customer approves twice: the range, before accepting a quote, and the layout of their own job (or photographs of the actual pieces, for a small order) before loading. The order shows "one lot" and the spare kept for them with its end date; delivery shows which crate holds which numbers, the plan and three lines of laying advice; "More of the same" offers what is left of their lot. See docs/MATCHING.md.

Delivery and collection (added 12 November 2026)

On the day the customer sees the stage, the arrival window, the vehicle's type and plate, and who offloads; not the driver's name or phone unless switched on for that order. A customer who collects names the person in the portal first. docs/LOGISTICS.md sections 1 and 4.

After the critique (12 November 2026)

From docs/CRITIQUE.md section 5. Customers will stay in WhatsApp, so: each action (approve the range, see the floor, accept, pay, authorise a collector) works from its own signed, single-purpose link; a code is asked only for accepting and paying; a fingerprint is offered later, never required, and never called a "passkey"; papers arrive in the chat as files. A forwarded link lets the receiver ask the customer's administrator to be let in, with one tap. An approval link can be forwarded and records who approved. The portal never tells the customer what is hidden from them. This settles the open question on links: a link opens one thing, for one purpose, for a limited time, and never the account.