Diamond Stone Platform: Modules

Date: 2026-11-11. Revision 2. Status: draft for owner review.

Companion to docs/PLAN.md (what is built and in what order), docs/DESIGN.md (how it looks and behaves) and docs/SCREENS.md (every screen and card). This document sets out how eleven parts of the system work, from eight research passes and the earlier DiyaOS and Diamond Stone planning documents.

1. Stone trading rules
2. Logistics, drivers and carriers
3. Inbox: email and WhatsApp together
4. Channels: change it once, publish everywhere
5. Setting up a company and its people
6. Roles, limits and controls
7. How every workflow is designed
8. Signing in
9. Automatic messages by email and WhatsApp
10. Website chat and the helpdesk
11. Notifications

1. Stone trading rules

A survey of stone-industry software found no product built for a small trader that sources against orders and exports, and none offering Arabic. The good ones share a short list of features. Those are adopted here; fabrication features are not.

What is adopted

One correction to the accounting

The plan valued stock at weighted average cost. Stone lots are not interchangeable, and the accounting standard expects items like that to be costed individually. Stock is now costed by specific lot. The accountant confirms this before the stock tables are built, because it shapes them.

Not for a trader

Photo stations and slab scanners, vein-matching and nesting, CAD and CNC links, RFID, kitchen visualisers, offcut management, an own marketplace. If cutting is ever outsourced, one simple screen adds the cutting cost to the lot.

To settle with the owner

• The allowance rule for gross and net: no published standard was found, so nothing is fixed in the software until five real invoices or packing lists have been reviewed.
• Whether the discount limit means a percentage off list or a floor on margin. The earlier documents use it both ways.
• The split-bundle charge (earlier documents say 8% and 12%).

2. Logistics, drivers and carriers

Own trucks and outside carriers are both supported, at any volume.

What a phone can and cannot do

A web app cannot report a phone's location once the screen is off or another app is in front. The published standard allows location only to a visible page. Continuous tracking therefore needs either a real Android app running a background service, or a tracker on the vehicle. WhatsApp's business interface does not pass on live location, only single pins.

Three levels of tracking

Oman already requires approved trackers on trucks, so for outside carriers the cheapest source of live position is often their existing tracker, if they will share it.

Staff can always enter or correct any milestone by hand. A manual entry overrides an automatic one and records who changed it, when and why. Every event shows its source: driver, carrier, staff, tracker or tracking service.

The record

Statuses are kept short: planned, booked, loaded, in transit, arrived, delivered, closed, with on hold beside them. Finer steps (at the border, customs cleared, gate-in) are dated events on the timeline, not separate states.

The driver

• Own drivers are staff: they sign in, and can run the driver app.
• Outside drivers get one link per job by WhatsApp. No account and no install. The first time they open it, they confirm their phone number with a code.
• One screen per job: where to go with a Navigate button, four to six large stage buttons with an icon and a word in the driver's language, the camera, and a voice note for anything unusual. No typing.
• The app never needs touching while the vehicle is moving. Police in Oman treat any phone use while driving as an offence.
• The driver sees quantities and addresses. Never prices, customers' finances or other jobs.
• Location is collected only between job start and delivery, with the driver's consent on first use.

Proof of delivery

In order of strength:

1. A one-time code sent to the receiver named on the order.
2. The receiver's name, signature on the screen and a photo.
3. Refused or nobody there, with a reason and photos.

Each is stamped with time and place. A delivery signed far from the site, or by someone not named in advance, is flagged for review. Shortage or damage opens a claim with the photos attached; nothing is quietly edited.

The logistics company

• A carrier or forwarder is a supplier record with its own contact.
• The carrier's dispatcher gets a simple view of their jobs only: accept or decline, assign driver and vehicle, update status, upload documents and the freight bill.
• They see the pickup and drop points, the cargo and weight, the site contact and their own agreed rate. Never the selling price or another carrier's work.
• Many small carriers will not use any portal. Staff then enter the updates from WhatsApp messages on their behalf, and the event is marked as entered by staff.

Sea freight

• Enter the container number, bill of lading or vessel once. A container-tracking service supplies the milestones: gate-in, loaded, departed, transhipped, arrived, discharged, released.
• One service covering all carriers is used, at a small fee per container. Connecting to each shipping line separately is not worth it at this scale.
• Arrival dates are shown as a range. Published figures put ships on time only about six times in ten, and late ones about five days late.
• A free-time countdown per container warns before storage charges start.
• Vessel position on a map is optional and comes last; reliable sources need a paid plan or their own receiving station.

Maps

• The map is built on open map data hosted by us, on the same Cloudflare account. No per-view fees, and no question about licence terms for tracking.
• Every map has a list beside it; the list is the main view and the map supports it.
• A stale position is shown honestly: "Last seen 14:20 near Nizwa", never a pin that looks live.
• Delivery points are captured as a pin: the customer shares a WhatsApp location or drops a pin, and we add a landmark, a gate photo and a contact. Oman's national address system is still being rolled out.

What the customer sees

A stage list with dates, an arrival window, the documents, and their contact. A map appears when the load is on the road. They never see the driver's phone number, the carrier's name or any cost.

Rules of the road built in

• Truck movement bans in Muscat and the summer midday outdoor work ban appear as notices that staff can edit, since they change by season.
• Weight limits are settings per route, since published figures conflict.
• Border paperwork is a checklist per destination, completed with the customs broker.

3. Inbox: email and WhatsApp together

One contact, one place; one screen to answer on either channel (revision 3)

Owner's instruction, 11 November 2026. Screens: "Inbox: one contact, one place" in the sketch. This subsection is the rule; the tables below it give the detail.

The inbox is a list of people, not of threads or channels. Each person appears once, however many numbers and addresses they write from and whichever channel they last used. The row shows who they are, their company, the channels they use as small marks, the latest message, and the reply timer.

Opening a person shows everything said with them, in one timeline. WhatsApp messages, emails, website chat, comments and reviews from social channels, calls logged, documents sent, and the team's own notes, in the order they happened.

Answering happens on the same screen, on whichever channel fits. The composer at the bottom has a channel switch on its left.

A person and their company.

• A person has one record with every number, address and WhatsApp identity they use, the channel and language they prefer, their quiet hours, and what they have agreed to receive.
• A company view shows everyone at that customer in one timeline, each message marked with who wrote it, with a filter per person. The composer there asks who the message is for.
• Someone copied on an email who is not yet known appears as a participant and can be added as a contact in one tap.
• A message from an unknown number or address opens a "Who is this?" card with any likely match and the reason. Nothing is merged until a person chooses; a wrong link can be undone.

The team in one place. One owner per conversation; assign or hand over; mention a colleague in a note; "Salim is replying" so two people do not answer at once, with a warning if someone answered since you started; who has seen it; snooze; open, waiting on the customer, waiting on us, closed. Suppliers, carriers and drivers have the same kind of timeline.

What this means for the build

• Identity matching is the core: numbers, addresses and WhatsApp identities all resolve to one person, and people to one company.
• Each message stores its channel, direction, the address used, delivery state, the email thread it belongs to, and the record it is about.
• Search runs across every channel at once.
• Drafted replies (docs/AI.md) appear in the composer on whichever channel is selected.

One place for every conversation with customers and suppliers.

How it works

Email

• The company's Google Workspace is connected as an internal app, which avoids Google's outside-app review.
• Shared addresses such as sales@ and orders@ are real mailboxes the system reads and sends from.
• Access is limited to those named mailboxes. Staff personal mailboxes are not read.
• Replies keep the email's thread references so they land in the customer's existing thread.
• The domain is set up so mail is trusted: SPF, DKIM and DMARC.

WhatsApp

• The official WhatsApp Business platform, on a dedicated company number.
• The 24-hour rule is built into the composer. While the customer's window is open, staff type freely and see how long is left. Once it closes, typing is replaced by a choice of approved templates, with a note that the message is charged.
• Since October 2026 ordinary replies are charged beyond 1,000 a month per number. A usage counter shows the month's total.
• WhatsApp now lets people use a username instead of showing their number. Contacts are therefore matched on WhatsApp's own customer ID, with the number kept when it is available.
• Consent is recorded per contact: who, when, how, and for what. A customer writing to us allows a reply; it does not allow marketing. "Stop" in English or Arabic is honoured at once on every channel.
• Staff who must keep using the WhatsApp app on the same number is a later option that needs a provider and has limits.

Not in the first version

Automatic merging, chatbots, marketing broadcasts and calling. (Suggested replies are now planned with the inbox, as drafts a person sends: docs/AI.md. Comments and messages from Instagram and Facebook arrive once Meta approves access: docs/SOCIAL.md.)

What is kept and what is not

Messages and attachments are stored encrypted. Nothing from a message appears in a notification beyond who it is from. Correspondence tied to an order is kept with the order; enquiries that went nowhere are cleared after a set period. An audit log records who read and exported what.

4. Channels: change it once, publish everywhere

The full plan for social posting (what is automatic, the screens, how this app and the channel service talk, settings, risks) is in docs/SOCIAL.md. This section keeps the facts about each platform.

The connector service as it stands

The service in the screenshot was found in C:\vaiprojects\hba-marketing-module-api. It was built for the Al Hiba portacabin business, and every channel in it is simulated: nothing is sent to any platform yet. It is reachable on a public address and falls back to built-in default keys. It should be closed off until it is rebuilt (see the plan's risks).

Worth keeping from it: the list describing what each channel can do, approval tied to the exact content, protection against sending twice, the stop switch for all or one channel, and the checks for text length and image type.

Not carried over: the simulated engines, driving sites through an automated browser, the unofficial WhatsApp gateway and its ban-avoidance broadcasts, phone-number lookup and people-graph features, and the helper that lets the service approve its own posts.

What each channel really allows

Nothing is published through an automated browser or an unofficial gateway. Those break the platforms' terms and put the company's accounts and its WhatsApp number at risk. WhatsApp broadcasts go only to people who opted in, through approved templates.

How "change it once" works

1. One record for each stone, for company details, and for each offer.
2. A version per channel is produced from it by a template. A channel's version can be adjusted by hand; if the source later changes, it is marked out of date, not overwritten.
3. Checked before sending: length, image shape, required fields, Arabic.
4. One job per channel, sent by a queue. A failure on one channel never undoes the others.
5. Status per channel: queued, live with a link, failed with a plain reason and a retry, needs reconnecting.
6. Manual channels become tasks with the text ready to copy, a link to the right page, and a tick recording who did it and when.
7. Comments, reviews and enquiries come back into the inbox.

On the phone: one edit screen, then a "Where this goes" sheet listing each channel with a preview card and its status. A change to company details shows exactly what will change where: "Phone number changes on 6 channels: 4 automatic, 2 tasks created."

The phone app never talks to the connector service directly. It talks to our own server, which holds the keys and passes on only what a person approved.

5. Setting up a company and its people

The system starts with one company. It is built so more can be added later: every record belongs to a company from the first day, and a second, dummy company exists in testing to prove one cannot see the other.

First-time company setup

About ten minutes, quick steps first:

1. The owner signs in and saves recovery codes.
2. Company: legal name in English and Arabic, commercial registration number, time zone.
3. Money: base currency (OMR, three decimals), first month of the financial year, the date the books start.
4. VAT: registered or not, number, start date.
5. Accounts: accept the trading-company template; costing by specific lot.
6. Numbering, one site, logo.
7. A second administrator, and the first two or three people by role.

Then straight to a real first task, not a tour. Research on tutorials found people who skipped them did as well as those who read them.

Fixed once the first entry is posted: base currency, financial-year start, costing method.

A checklist on the home screen covers the rest, each item opening its task: opening balances, bank accounts, catalogue and stock, customers and suppliers, approval limits, document templates, payroll, the portal, the website, and a first access review at day 30. During setup the Halo's rings show this progress.

The company starts empty. A separate demonstration company is available for practice; no sample rows are ever mixed into the real books.

Adding people

• An invitation is single-use, expires, and is tied to that person's phone number and role.
• People are separate from positions. A shared address or number belongs to the position ("Sales, Muscat"), so conversations survive a change of staff.
• One person can belong to more than one company, and can be both staff and a customer contact, with a visible switch between them.

Customers and the portal

A link in a WhatsApp or email message is convenient but is not proof of identity, and there are no sign-in codes or sign-in links by email (section 8). So a portal page opened from a link can look, and anything that binds asks again:

• Accepting a quote, seeing all invoices or statements, changing bank or contact details, and adding colleagues each need a fresh code or passkey and an explicit confirm screen.
• Acceptance records who, when, from which device, and the exact version of the quote.
• A link forwarded to someone else carries no authority.

When people move or leave

• A change of role takes effect at once, is logged with before and after, and is reported to the owner.
• Leaving: the account is switched off, not deleted. Every session ends immediately, open records and approvals pass to a named person, conversations pass to their manager, and their history stays.
• Two administrators at all times, so the company is never locked out.
• Anyone active who has not signed in for 30 days is flagged each week.

6. Roles, limits and controls

Roles

Eight fixed roles. One person may hold two; a small company needs that.

Plus a read-only role for the outside accountant or auditor, and four portal roles for customers: administrator, approver, payer, viewer.

A permission is an area, an action and a reach: for example, "create quotes for my own customers". Three things are hidden unless the role allows them: cost and margin, salaries, and bank details. They are held back by the server, including in exports and PDFs.

On the phone, a role is shown as plain sentences ("Can approve purchase orders up to OMR 2,000"), with a "view as this role" preview. When someone is refused, the screen says what is missing and who can grant it, so the fix is not to make everyone an administrator.

Rules that keep duties apart

1. Nobody approves something they created or last edited.
2. Whoever adds a supplier or changes its bank details cannot release its payment. A bank change needs a second person, a call back to a known number, and a waiting period before the first payment.
3. Whoever prepares a payment does not release it.
4. Whoever prepares payroll does not approve or release it.
5. The person who orders, the person who receives and the person who approves the bill are three checks.
6. Bank reconciliation is reviewed by someone other than the payment preparer.
7. Large manual journals and anything posted to a past period need approval. Posted entries are never edited.
8. The administrator role carries no money rights; role changes are acknowledged by the owner.
9. Discounts, credit notes, write-offs and credit-limit increases above the limit are approved by someone other than the salesperson.
10. Stock adjustments above a threshold are approved from outside the warehouse.

Approval limits

• One table: kind of document, amount band, who approves.
• Until the owner sets limits, the owner approves everything.
• One approver by default. Two only for bank changes, role and rule changes, and amounts above the top limit.
• Splitting is detected: the same party on the same day adding up past a limit.
• Cover for leave has start and end dates, is capped at the lender's own limit, and can never go to the requester.
• Silence never approves. An overdue request goes to a named alternate.
• An approval covers the exact content; any edit cancels it.
• Nothing is approved by replying to a WhatsApp or email. Amounts never show on the lock screen.

The limits themselves are the owner's decision. The software sets none by default.

When there are too few people to separate duties

A fraud survey of 2,400 cases found small organisations lose the most per case, and that regular management review is linked with roughly half the loss. So where one person must do two jobs, the owner reviews:

• A weekly exception digest on the owner's phone, acknowledged in the app: anything self-approved or overridden, supplier bank changes, new suppliers paid within a week, payments just under a limit, manual journals, reversals, back-dated entries, credit notes, stock write-offs, price overrides, role changes.
• The owner sees bank balances directly, not through whoever prepares payments.
• Surprise stock counts.
• A confidential way for staff to raise a concern that reaches the owner and one independent person.
• A tamper-evident audit log, and read-only access for the outside accountant each quarter.

Access is reviewed whenever someone joins, moves or leaves; finance and administrator access every quarter; everyone, including portal contacts, every six months.

7. How every workflow is designed

Every process in the system (enquiry to quote, quote to order, order to delivery, bill to payment, month-end, payroll and the rest) is written to one template before it is built.

The rules

The template

For each process, one or two pages:

1. Name, purpose, owner.
2. What starts it.
3. Who takes part.
4. The record, and how it is numbered.
5. Its statuses, each with a one-line meaning, and what the customer sees for each.
6. The steps: from which status to which, who may take it, what must be true, what must be filled in, what happens automatically (entries, stock, messages, documents), who is told, and how it is reversed.
7. Approvals: amounts, who, what happens if nobody answers.
8. Timers and what pauses them.
9. Exceptions, holds and cancellation.
10. Who may see what.
11. What happens offline and when two people edit.
12. What is measured.
13. Test cases.

What is measured

Every step is written to one log, which is also the audit trail. From it: how long each process takes end to end, how much of that is waiting, how long approvals take, how often a record goes through without being sent back, and how often it needs an exception. With tens of cases a week this is a weekly list of the oldest waiting items, not statistics.

The twenty mistakes each workflow is checked against

1. Status implied by empty fields instead of stated.
2. A status changed by editing the record directly.
3. Permission checked on the screen but not on the server.
4. Another customer's or company's record reachable by guessing its number.
5. Everything required at creation, so drafts cannot be saved.
6. Someone approving their own work; a limit avoided by splitting.
7. An approval with no time limit, alternate or cover.
8. Approvals in a row that could run side by side.
9. A rejection with no reason and no way back.
10. Editing or deleting after posting.
11. No way to cancel part-way, leaving stock held.
12. Duplicates from a double tap or retry.
13. One person's changes silently overwriting another's.
14. A message sent before the record is saved, or lost after.
15. Too many notifications, or to the wrong person.
16. A timer that cannot pause.
17. A hard stop with no logged way through.
18. Internal reasons shown to the customer.
19. A sent quote or price list that can still be edited.
20. No log of steps, so nothing can be measured; amounts or tax worked out differently at different steps.

The processes to be written first

Enquiry to quote; quote to order; order to sourcing to delivery; advance and payment verification; supplier bill to payment; sample request; claim; leave request; expense claim; payroll run; month-end close; inviting and removing a person.

8. Signing in

The idea

A code sent to a phone proves the phone is yours once. After that, the phone's own fingerprint or face unlock does the signing in, through a passkey. Codes come back only for a new phone or a lost one.

This is deliberate. Security standards treat text-message codes as a restricted method (numbers can be hijacked) and do not accept email as proof of identity at all. A passkey cannot be phished or guessed, and for the person it is simply their fingerprint.

Who signs in how

One way in for everyone: phone number, one code, then a passkey. There is no "Continue with Google", no email sign-in and no password. (Owner's decision, 11 November 2026.) Registration is the only time a code is the normal route; afterwards a code is used only to enrol a new phone or recover a lost one. Passkeys are WebAuthn/FIDO2 credentials held by the phone; a hardware security key can be added as a second one for the owner and the accountant.

Only phone numbers that an administrator has invited can sign in to the staff app. An unknown number gets the same message as a known one, so nobody can test which numbers are registered.

The screens

Rules

• A session on a personal phone lasts a working week for field roles and a day for finance and administrators, then asks for the fingerprint again.
• After a few minutes untouched, money screens blur until the fingerprint is given.
• Five wrong codes pause that number for a while. Codes are never shown in a notification preview longer than needed and are never sent by email.
• Every sign-in, failed attempt, new device and recovery is in the audit log and visible to the owner.
• No passwords anywhere.

To confirm

• Which text-message provider to use in Oman for the fallback, and its cost. A WhatsApp code is also a charged message.
• Whether every staff phone can hold a passkey. Android stores passkeys in the phone's Google or Samsung password manager, so a phone with neither account set up cannot. This is tested on the real phones in Stage 0; for such a phone the fallback is a code at each sign-in plus an app PIN, with shorter sessions.
• A customer who opens the portal on a computer: they scan a QR code with their phone and approve with the phone's passkey.

9. Automatic messages by email and WhatsApp

What is automated

Messages the company would otherwise have to remember to send. Each is tied to an event or a date, uses an approved template, and stops by itself when it is no longer true.

How it is controlled

• Every automation is a switch the owner can see. One screen lists them all: on or off, how many were sent this month, and how many replies or actions followed.
• Each one shows exactly what it will send, in English and Arabic, with real sample data, before it is switched on.
• Templates are approved before use. WhatsApp requires its own approval for messages sent outside the 24-hour window; the screen shows each template's approval state.
• Consent decides the channel. Messages about a customer's own enquiry or order go out as service messages. Anything promotional goes only to people who opted in, and every such message has a way to stop.
• Quiet hours. Nothing is sent to customers at night or on Friday unless it is a reply.
• A cap per customer per day and per week, so automations never stack up on one person.
• A person can always step in. When staff reply in a conversation, the follow-ups for that conversation pause.
• A full log of what was sent, to whom, why, and what happened.
• No bulk sending to lists, and nothing that tries to get around WhatsApp's limits.
• Amounts are not put in the message itself where the channel is not private; a secure link is used.

What it is built on

The same outbox that sends everything else: a message is queued only after the event is safely saved, each has a one-time key so it is never sent twice, and failures retry and then surface to a person.

10. Website chat and the helpdesk

Website chat

Chat on the public site and in the client portal, under Contact and offered only while someone is on duty, answered by the team from the same inbox as email and WhatsApp. Whether it is on at launch is an open decision (docs/SITE-DESIGN.md section 21).

No chatbot answers customers in the first version. Suggested replies are for staff.

Helpdesk

A question or problem that needs following through becomes a case.

Help centre

Short answers to common questions, on the public site and in the portal: how samples work, how to read a quote, delivery and unloading, care of the stone, how to pay, how to report a problem. Each is one screen with pictures. A person searching Help sees answers first and "Talk to us" second. The same answers feed staff's one-tap replies, so customers and staff say the same thing.

Staff helpdesk

Staff can raise their own cases the same way: "I cannot sign in", "This figure looks wrong", "I need access to…". They go to the administrator, with the screen the person was on attached.

11. Notifications

What notifies whom

Rules

• One notification per event, to the one person who must act. Everything else waits for the digest.
• Nothing private on the lock screen. A notification says who and what kind ("Ahmed sent a message", "A payment is waiting for you"), never an amount or the message itself.
• On duty. Chat and new enquiries go to whoever is marked on duty, so they do not ring everyone. If nobody takes it within the promise, it widens to the team and then the owner.
• Quiet hours per person, outside which only what they have marked urgent comes through.
• Each person chooses what reaches them, within what their role must receive.
• Tapping a notification opens the exact record, with the Omnibar already showing the action.
• Notifications are a nudge, not the record. Anything missed is still in the Halo and the stream.
• Staff phones are Android, where notifications work from the installed app. A staff member on an iPhone must add the app to the Home Screen first.
• Customers are notified by WhatsApp and email, not by the browser.

12. Back-to-back orders, and what the customer may see

Added 11 November 2026 on the owner's instruction.

Back-to-back orders

Many orders never pass through Diamond Stone's own hands. The stone is ordered from the factory for one customer's order and delivered from the factory straight to that customer. This is the normal case, not an exception, so it is a first-class way of fulfilling an order.

Every order line is fulfilled one of two ways, chosen when the order is confirmed and changeable until the supplier order is sent:

One order can mix both: some lines from stock, some back to back, on separate shipments.

The flow (drawn in docs/user-flows.html, "Back-to-back order"):

1. Customer approves the range and accepts the quote. Sales confirms the order.
2. Purchasing taps "Order from factory": the supplier order is filled from the customer order (stone, finish, quantity, date needed). It never shows the customer's price.
3. Owner approves if above the limit. The factory receives it and confirms a ready date.
4. Purchasing sorts and measures at the factory, then lays the job out, photographed and numbered (projects), or photographs the actual pieces (small orders).
5. The customer approves the layout, or the photographs of the pieces, in the portal, or asks for a piece to be changed.
6. Purchasing books transport from the factory: own truck or a carrier, with the factory's loading contact and hours.
7. The customer confirms the delivery day and that the site is ready.
8. The driver collects at the factory (Loaded), travels (Left), arrives and gets the delivery signed.
9. The signed delivery triggers the customer's invoice. The factory's bill is matched to the supplier order and the loading record.

Rules

• A back-to-back supplier order cannot be sent until the customer's advance has been received, unless the owner allows it for that customer. (A setting; default on.)
• The margin for the order is known the moment both prices are: sale price less factory price less transport.
• If the customer does not approve the layout or the pieces, the supplier order goes back to the factory with the photographs and the changes asked for; nothing has moved and nothing is in stock.
• If the customer cancels after the factory has cut or reserved stone, the order shows what Diamond Stone is now committed to pay, before the cancellation is accepted.
• Documents the customer receives (delivery note, packing list, invoice) are issued in Diamond Stone's name with Diamond Stone's address. They never carry the factory's name, address or prices.
• The factory never sees the customer's name or price unless purchasing chooses to share a delivery address for loading papers. The driver's job shows the delivery address; the factory's copy need not.
• In the accounts (docs/ACCOUNTS.md section 2): on loading, goods in transit and a liability to the factory; on signed delivery, revenue and cost of sales together. Stock is never touched.

What the customer sees of the journey

The factory is Diamond Stone's supplier. If a customer can see exactly where their stone was collected, they can go there directly next time. So what the customer sees about the origin, the truck and the driver is controlled by the administrator.

Settings, under Settings → Delivering → What customers see. Each has a default and can be set for everyone, and overridden for one customer or one order.

How the general-area rule works, in plain terms:

• While the truck is inside the origin area, the customer sees "Loading" or "Left", a route line starting at the city's name, and no map position.
• Between the two areas, the customer sees the truck as a shaded region on the route (for example "near Hatta border"), not a moving dot, updated at stage changes.
• Inside the area around their own site, they may see the truck's position, so they can open the gate.
• The route line the customer sees always begins at the centre of the origin city, not at the factory.

Enforced by the server. The customer's phone is never sent the factory's coordinates, the exact position while it is hidden, or any driver field. It is not enough to hide them on the screen. The "view as customer" preview in settings shows exactly what a customer receives.

Driver details

• Who enters them: for an outside carrier, the carrier's dispatcher when assigning the job, or Diamond Stone's shipping staff if the carrier sends them by message. For the company's own drivers, they come from the staff record. For a driver using the job link, the driver confirms their own name and number the first time and the rest is filled from then on.
• What is recorded: name, phone number, identity or residence card number and its photograph, driving licence and expiry, truck plate and type, the carrier they work for. Border crossings and site gates often need the card and plate in advance.
• Who sees them: shipping, the owner, and warehouse on the day. The factory's loading contact sees name and plate only, for the gate. Customers see none of it unless the administrator has chosen to show a first name or the plate.
• Remembered: a driver used before is offered by name; nothing is typed twice. Expired licences are flagged before a job is assigned.
• Kept: as personal data, for as long as the delivery record is needed and no longer; a driver can ask what is held (data protection law).
• When a customer needs to reach the truck (the gate is closed, nobody is on site), they message their Diamond Stone contact, who calls the driver. A masked call through the app is a later option.

The earlier demonstration portal showed the driver's phone number to customers. That is ended by these rules.

Installing and sign-in (added 11 November 2026)

Staff install the app from Chrome first and sign in inside the installed app, so the passkey is made where it will be used. The passkey is tied to the main domain and serves all three apps. Inside another app's browser, sign-in is by code only. See docs/INSTALL.md.

Website chat: how it is offered (changed 11 November 2026)

Section 10 placed a chat button "in the Omnibar position". On the public site and the portal the bar carries the word "WhatsApp", opening it directly; chat sits under Contact and is offered only while someone is on duty. See docs/SITE-DESIGN.md section 21.

The lot as the unit of matching (added 11 November 2026)

Section 1 made the lot the unit of stock. It is now also the unit of matching: one job, one lot, with tone groups, thickness readings, treatment and spare recorded, and checks before an order is confirmed or loaded. No block is ever a stock item. See docs/MATCHING.md sections 6, 8 and 9. The "Reorder" message of section 9 now offers the spare from the customer's own lot.

Logistics, drivers and papers, replanned (12 November 2026)

Section 2 stands for tracking levels, the shipment record and proof of delivery. docs/LOGISTICS.md adds: the five routes, including collection by the customer; what is held about a driver and vehicle in each case; loading witnessed at the factory; the papers by route; delivery terms; claims clocks. Where section 2 says the customer never sees the carrier or driver, the defaults are now in LOGISTICS.md section 4: the vehicle and plate on the day, nothing personal unless switched on.

Controls added after the red-team review (12 November 2026)

docs/CRITIQUE.md section 6 lists 23 controls. Those that change this document:

• Section 12, the advance. "Received" means a matched bank line, not an uploaded slip. Only that makes a hold firm or lets the factory be ordered. The owner may override, and it is recorded.
• Section 8, sign-in. A session opened by a code alone is read-only. A passkey added by code waits 24 hours and every existing device is told. Codes are limited per number, device and country. The session is locked after wrong tries, never the number. Recovering the owner needs a recovery code, a second administrator and a delay.
• Section 6, approvals. A second person for: accepting a quote outside the portal; marking "delivered" by hand; applying a receipt to someone who did not pay. Granting a money role needs the owner's passkey.
• Section 3, merging. Two people where orders or portal users exist. A messaging identity never becomes a sign-in identity.
• Section 9, messages. Bank details are never in a message or behind a link in one: only on the stamped proforma and in the portal. Every outgoing message passes a filter for supplier names, unknown links and bank numbers.
• Section 2, proof of delivery. A job link works only for the named number. Without the receiver's code or confirmation, the state is "pending", not "delivered".
• Settings. Who may override what, at which level: docs/SETTINGS.md section 1.

Salespeople's own WhatsApp (added 12 November 2026)

The critique found that a salesperson's number is where deals really happen, and the plan had deferred it. Researched on 12 November 2026.

Meta offers "coexistence": a number stays on the ordinary WhatsApp Business app on the salesperson's phone and is connected to the official platform, so our system receives what is sent and received. Read on Meta's developer pages:

The plan.

1. Each salesperson has a company-owned number on the Business app, connected by coexistence. Not their personal number.
2. Customers may keep writing to that person. Everything lands in the one inbox, under the customer.
3. Templates, automatic messages and anything sent after 24 hours of silence go from the system; the day's conversation is typed in the app as now.
4. Rules for staff: open the app at least weekly; no Windows app; no change of phone or number without the administrator; groups and calls are outside the record.
5. A line on the profile and in the first message: conversations with us are kept in our systems.
6. When a salesperson leaves, the number and its history stay with the company.

To confirm with a solution provider: that Omani numbers are accepted; how long a number must have been in use; several such numbers under one account and the cost of each; whether the verified badge and display name apply; whether messages the system sends show in the app. Unofficial gateways and automating a personal account stay out of the plan.

Where coexistence is not possible, the fallback is the earlier one: "log to Diamond Stone" from the phone's share sheet, with voice notes written out.

Suppliers, replanned (12 November 2026)

Price requests to suppliers by WhatsApp and email, the reading of their answers, standing prices, and supplier registration are planned in docs/SUPPLIERS.md. It confirms there is no supplier portal: suppliers answer in the channels they use now. Section 3's inbox carries the threads; section 9's automatic messages gain the request, the confirmation, the reminder and the closing message, each approved by a person.