Diamond Stone Platform: Master Plan

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

Changes in this revision: sign-in by phone number, code and passkey; automatic email and WhatsApp messages; website chat; a helpdesk; notifications (docs/MODULES.md sections 8 to 11). Revision 12: logistics with driver and carrier views, a combined email and WhatsApp inbox, channel publishing, company and user setup, roles and controls, a workflow standard and stone-trading rules, all detailed in docs/MODULES.md; every screen and card in docs/SCREENS.md; a phone test matrix; stock costed by lot; new risks and decisions.

This plan covers what is built, on what, and in what order. Three companions go deeper: docs/DESIGN.md (how it looks and behaves), docs/SCREENS.md (every screen and card) and docs/MODULES.md (how the main parts work). The 26 documents in docs/planning/ and the earlier 30-module proposal are background only; where they disagree with this file, this file wins.

1. What we are building

Diamond Stone buys marble from suppliers and sells it to project buyers, contractors, designers and importers. It does not quarry or fabricate. One system, three parts:

• Public website: catalogue and lead tools that bring enquiries in.
• Client portal: the customer's view of quotes, orders, shipments, invoices and documents.
• Staff app: runs the company from a phone.

Rules:

1. The customer comes first. Customer-facing work is built before internal tooling, and every stage is judged by what the customer sees.
2. The staff app is phone only, tuned to two phones. Every screen is designed and tested on the Samsung Galaxy S25 and Galaxy A55 5G (section 7). The staff app has no desktop layout; on a computer its layout appears in a centred column. The website and the client portal also have tablet and desk layouts (docs/SITE-DESIGN.md section 14).
3. One login, one database, one customer record, one design kit.
4. Nobody types the same thing twice. A business event posts its own accounting entry.
5. A person approves anything that moves money, issues a price, or publishes.
6. Nothing is built until someone will use it that month.

2. Customer experience

Promises (targets for the owner to set)

The system times each promise and shows the owner where it was missed.

The journey

Portal rules

• No passwords and no email sign-in: phone number, then a one-time code by WhatsApp (text message as fallback), then a passkey.
• One screen per order, with a stage track and a button to message the named contact.
• English and Arabic; the customer chooses once.
• The customer is never asked to retype something the company already has.
• No tricks: no forced marketing consent, no hidden costs, no false urgency.

Channels

WhatsApp is the main channel in Oman, with email for documents. Messages are sent through the official WhatsApp Business platform. The existing setup points at an unofficial gateway, which risks the number being blocked (decision 6).

Measures

First-reply time, quote turnaround, quotes won, on-time delivery, claims per order, repeat orders, and the one-question score after delivery.

3. Lead magnets

Drawn from the earlier website audit and its seven proposed "sales magnets", cut to what a trader can deliver well. Superseded by docs/MARKETING.md section 5, which keeps these eight, adds six (a project sample box, a submittal pack, a tender rate, a talk for design firms, a prequalification pack, a trade account) and ranks all fourteen by the strength of their evidence.

Gating rule: everything about the stones is free to browse. Contact details are asked for only when the customer receives something made for them, and marketing consent is a separate, optional tick.

Build first

Build next

Left out

The room visualiser in augmented reality, the BIM and 3D texture generator, the offcut marketplace and the maintenance-contract "stone passport". They are heavy to build or belong to a fabricator, not a trader. A care guide sent after delivery covers the last one.

How each magnet works inside

Every magnet creates an enquiry in Sell with its source, starts the reply timer, raises a Halo ring for sales, and sends the customer an acknowledgement. Sample QR scans and pack downloads are added to the customer's timeline so sales can see interest building.

The specifier pack depends on real test reports and certificates for each stone (decision 9). Without them it ships with the datasheet and texture only.

4. New build

Everything is built new. The current code is not extended.

Why: the current build stores records as JSON text in a file inside the container, the API trusts a header saying who the user is, and the staff app was drawn for desktop.

5. Structure

Nine areas on one foundation. Details of how the main ones work are in docs/MODULES.md.

Foundation: login and roles, parties (customers, suppliers, staff), files, messages, English and Arabic, offline drafts, notifications, numbering, audit log.

Deliberately out

Quarry, block, production, royalty and weighbridge features; blocks as a product (docs/MATCHING.md); a desktop layout for the staff app; AI voice agents and PBX; cold-calling campaigns; Gmail signature sync; and the unrelated school, childcare, hospitality and signage modules.

6. Technology

Repo layout:

apps/site       public website and lead tools
apps/portal     client portal
apps/staff      staff app
apps/api        Rust API
crates/core     Rust rules (also built to WASM)
packages/ui     tokens, shell, elements
legacy/         the current apps, until switched off

Sign-in: a code to the phone proves it once; after that the fingerprint signs in, through a passkey. Everyone registers the same way: phone number, then a one-time code, then a passkey (WebAuthn/FIDO2) from then on. No Google sign-in, no email sign-in, no passwords. Details in docs/MODULES.md section 8.

Offline is limited to four jobs: submit an expense, record a supplier inspection, record a delivery, clock in. Each saves as an encrypted draft. Everything else needs a connection.

What an installed web app can do on the target phones is set out in section 7.

7. Target phones

The staff app is designed, tuned and tested on two phones: the Samsung Galaxy S25 and the Samsung Galaxy A55 5G. The client portal and public site are tuned on the same two but must still work on whatever phone a customer has, including iPhones.

The two phones

The A55 is the slower phone by a wide margin. Everything is tuned on the A55; if it is smooth there, it is smooth on the S25.

Design numbers

Layout rules from Samsung's own behaviour

• Edge panel handle. Samsung puts a handle on the upper right edge that can cover controls. Nothing tappable sits in that strip; the top bar's right side holds only the sync badge.
• Navigation bar. Some people use gestures, some the three buttons. The bottom bar sits above whichever is present, using the phone's reported safe area rather than a fixed gap.
• Reach. One UI itself puts reading at the top and actions at the bottom, which matches Halo above and the bottom bar below.
• Keyboard. The Samsung keyboard's height is adjustable by the user, so the layout follows the visible area rather than assuming a size.
• Dark mode. Samsung's browser can force its own dark colours on a site. The app ships a real dark theme and declares it, so the browser leaves it alone.
• Fonts. Web pages on Samsung phones fall back to Roboto, not Samsung's own font. The app ships Rajdhani and IBM Plex Sans Arabic so it looks the same everywhere.
• Corners and camera hole. 16 to 24 px is kept clear of the screen corners; the Halo sits below the status bar.

Performance budget (measured on the A55)

Animation timing is measured in real time, not in frames, so it runs at the same speed on a 60 Hz and a 120 Hz screen.

Adaptive quality: test each phone, fall back automatically

Glass effects (blur and light bending behind the floating controls) are the heaviest thing a web page can ask of a phone's graphics chip. Rather than ban them or assume they work, the app measures each device and chooses a level.

Quality levels

Layout, sizes, icons and behaviour are identical at every level. Only the surface changes. Glass is used only on the floating layer (bottom bar, sheet tops, Halo), never on content.

The test

• First launch: a one-second test draws the real bottom bar over moving content and times every frame. The result sets the starting level.
• In use: the app keeps watching frame times during scrolling and transitions. If frames are dropped repeatedly, it steps down one level for that session and remembers it.
• Never up on its own: it steps up only after a fresh test, run after an app or browser update, or when the user asks.
• Respects the phone: power saving mode, a low battery, or the system's reduced-transparency or reduced-motion settings lower the level at once.
• The person decides last: a setting lets each user choose a level, including "always solid".

Seeing it per user

Each device reports its level and frame rate (no personal content). The Control area shows a small table: person, phone, browser, level, frames per second, last tested. That tells us when a phone is struggling before the person complains.

Where Rust and WASM help, and where they cannot

So WASM makes the glass accurate (correct optics for each shape), and the level system keeps it fast. The research confirmed that the bending effect exists only in Chrome-family browsers, so iPhones stop at level 2, and that nobody has published a test of it on Android phones, so it is verified on the real S25 before it is relied on. A published measurement on a cheaper Samsung found that removing blur roughly halved worst-case frame time, which is why the A55 is expected to carry one small glass surface at most.

Browsers

Samsung phones come with two browsers, and the app must work in both.

• Staff install the app from Chrome, so there is one installed version to support.
• Customers on Samsung phones will mostly arrive in Samsung Internet, so the portal and site are tested there too.
• Oldest versions supported: Chrome 135 and Samsung Internet 29.
• The install button is a convenience; a short "install from the browser menu" guide is always available. A person who opens the install page in Samsung Internet, or inside WhatsApp, is sent to Chrome. The whole process, for staff, customers and drivers, is in docs/INSTALL.md.

What changes because staff are on Android

Compared with the earlier iPhone-based assumptions:

Samsung puts unused apps to sleep, so the app still saves its state at every step and never depends on background timing.

iPhones

Customers will open the portal and site on iPhones. Those two parts keep to features every phone supports, and are spot-checked on one iPhone each stage. The staff app is not tuned for iPhone in this build; it will run, without the Android extras above.

To measure on the real phones first

Day one of Stage 0, on both phones, in both browsers, in a tab and installed:

1. The actual page width and height (the A55's width is the main unknown).
2. The safe-area gaps at top and bottom, with gestures and with three buttons.
3. Whether animation runs at 120 Hz, and which glass quality level each phone holds at full frame rate.
4. Camera capture and QR reading.
5. Which passkey provider the phone offers.

These five results replace the "likely" figures above.

Other phones: what customers use

Staff phones are the two Samsungs. Customers and the public use whatever they have, so the portal and public site are checked more widely. Figures are from October 2026.

Page widths that matter, in order: 375 to 393 px (most iPhones, Samsung at 384, Xiaomi at 393), 360 px, 402 to 414 px, 420 to 440 px (large iPhones), and under 344 px (enlarged display settings and folding-phone covers). The 384 px bucket is the third most common in Oman and worldwide, which supports the A55 figure.

Layout rules that make one design hold everywhere:

• One layout from 344 to 440 px wide, with no jumps. Below 344 px, side margins tighten and the staff app's Omnibar labels drop to icons.
• Above 480 px (tablets, opened folding phones, computers) the staff app's phone layout sits in a centred column; the website and portal change to their tablet and desk layouts (docs/SITE-DESIGN.md section 14).
• Heights from 568 to 960 px. Below 600 px the top bar scrolls away.
• About one person in four has enlarged the text on their phone. Everything survives 200%.
• Links opened inside WhatsApp, Instagram or Facebook show in a cut-down browser with its own bars and no saved sign-in. Entry pages are tested there, with an "open in browser" route for sign-in.

Test matrix

Phones to have in hand: the S25 and A55 already owned, one standard iPhone, and one low-cost Android. Borrow a small or large iPhone and a folding phone each stage.

After launch the app records page size, text scale, browser and speed in broad buckets, with no personal detail, and the matrix is re-ranked each quarter from what customers actually use.

8. Design

All design decisions live in docs/DESIGN.md; a live sketch is in docs/ui-shell-mockup.html. In summary:

• Basis. The ideas behind Apple's Liquid Glass, applied as layout and behaviour rules: content underneath, a thin floating layer of controls above, capsule shapes, one tinted action per screen, things opening from their source. Glass is only on the floating layer and adapts to each phone (section 7).
• Evidence. Six research passes. The main lessons: simple and familiar beats clever; visuals work with a few words, not instead of them; navigation must stay visible; polish buys patience, not usability.
• Shell. One shell on every staff app screen: Halo rings at the top for what needs attention, with a drawer that drops from each ring; the stream in the middle; the Omnibar at the bottom, showing where you are, Add, Scan and Search. With a record open, the Omnibar becomes that record's one named action. The website and portal have no Halo, Stream or Omnibar: the portal has a line of words with counts, and both have a bar with the word "WhatsApp" at the left and the page's action at the right (docs/SITE-DESIGN.md).
• Cards and screens. Every card is designed from what the person needs to know, with the customer and the stone leading and record numbers last (docs/SCREENS.md).
• Type and layout. Rajdhani for all text, Orbitron for the wordmark only, IBM Plex Sans Arabic; accent teal #006F73; a fixed scale with a 16 px body; one money format; sizes checked in real millimetres at normal viewing distance on both phones.
• Visual-first. A table of which visual to use for each kind of information, chart rules, and stone-specific visuals: the real photograph as hero, a property scale for datasheets, a container fill drawing.
• Icons and motion. One icon set with a word beside each icon until it passes a recognition test; five timing tokens; nothing moves at rest.
• Quality bar. Thirty-two checks every screen must pass, and a testing method with staff and customers.

9. Screens in the first release

About 60 screens, most of them the same list-and-record pattern.

10. Automation

Postings without typing (the full table is written in the Money stage):

Customer updates without typing: each stage change on an order sends the customer a WhatsApp or email message from an approved template and updates the portal.

The full plan for AI in every module is docs/AI.md. Jev makes typed choices only; it does not write or read documents, has no image product ready for production, and is weak on sums, dates and Arabic. Drafting uses a language model, reading paper uses a document reader, and sums are done by code.

Where Jev is used (a typed decision, never free text):

• Route a new enquiry to the right person and priority.
• Suggest the category and account for a receipt or supplier bill.
• Flag a bill that does not match its order and receipt.
• Check an inspection photo set is complete and readable.
• Suggest which customer a bank line belongs to.

Each suggestion shows its confidence; below a set level it goes to a person. Jev never posts, approves or sends. It is an early-access outside service, so it sits behind one adapter and the system works without it.

11. Accounting: IFRS for SMEs

Built to the third edition, effective 1 January 2027. Oman permits it for unlisted companies (Financial Services Authority Decision 2/2025).

• Double-entry ledger in whole baisa. No edits or deletes; corrections are reversals.
• Periods open, then closed; reopening needs two people.
• Dimensions on each line: department, customer order, shipment.
• Currencies: books in OMR. Customers, suppliers and freight are often in US dollars: each record stays in its own currency with its rate locked, and the customer sees only their own. Full plan in docs/CURRENCY.md.
• Stock: costed by specific lot, with landed cost spread over the lot; goods shipped direct from supplier to customer go straight to cost of sales; stock held at the lower of cost and selling value. (Changed from weighted average: stone lots are not interchangeable. The accountant confirms.)
• Revenue: advances are a liability until control passes to the customer.
• Margin per order from sale price, purchase cost and landed cost.
• Fixed assets, leases, end-of-service benefit accrual, provisions.
• Statements: financial position, income, cash flows, changes in equity, trial balance, notes support.
• Oman VAT at 5 %, exports zero-rated, VAT return pack, gapless invoice numbers, tax invoice within 15 days, 10-year records.
• E-invoicing: mandatory from 1 April 2027 above OMR 5 million of annual supplies, otherwise 1 October 2027 (Tax Authority Decision 189/2026), through an accredited provider. Invoices are structured from day one.
• Before it becomes the books of record: opening balances loaded and three closed months run in parallel.

The software makes compliant books possible. The policies and sign-off belong to the company's accountant and auditor.

Detail is in docs/ACCOUNTS.md: how each event in the app posts to the ledger, the chart of accounts, the 22 accounting screens, the month-end close, the management, IFRS for SMEs, audit and tax reports, the Oman legal requirements and dates, the 20-schedule audit pack, and the controls an auditor relies on. Two corrections from that research: the third edition keeps the incurred-loss model for receivables (no expected credit loss), and the income tax return is due four months after year end with audited accounts.

How each kind of user reaches every place is in docs/JOURNEYS.md. Every screen and setting, with the gaps found, is in docs/INVENTORY.md. Logo, colours, typefaces and wording are in docs/BRAND.md; each role's screens, and the owner's, are in docs/ROLES.md; element sizes and pixel density are in docs/DESIGN.md section 4. Back-to-back orders (ordered at the factory, delivered straight to the customer) and what customers may see of the origin, the truck and the driver are in docs/MODULES.md section 12. The three customer-facing parts each have their own document: docs/PORTAL.md (client portal), docs/WEBSITE.md (public website, with search, answer and AI visibility) and docs/STORE.md (samples store). How each person flows through their work, and the gaps that showed, are in docs/FLOWS.md with diagrams in docs/user-flows.html. Social channels: written, approved and scheduled in this app, sent by the separate channel service, with results and replies coming back (docs/SOCIAL.md). Where content comes from: photographs and facts captured during normal work, checked, masked and offered as drafts (docs/CONTENT.md, map in docs/content-map.html). Each role's work by day, week and month is in docs/ROLES.md section 13. Photo requests to customers, and customers who are traders, are in docs/CONTENT.md section 14. The Halo is one band at the very top of every signed-in staff app screen; it opens downward for one ring and pulls down to show everything (docs/DESIGN.md section 7). HR in full (contracts, permits, all leave kinds, hours, pay rules, renewals, Omanisation, with sixteen points for a PRO) is in docs/HR.md. The inbox is one row per person and one timeline for everything said with them; the team answers by WhatsApp or email from the same screen (docs/MODULES.md section 3). How the interface is coded (layers, glass at four levels, the movement vocabulary and springs, and why each feels as it does) is in docs/FRONTEND.md and docs/ui-build.html, including an audit of what the build plan was missing: a level for bright sun, reach, the phone's text size, screen readers, Arabic, and what a web app cannot do on each phone. The public website, reviewed (what the first plan missed; what each kind of buyer wants; ten ways people arrive and the one path to becoming a customer; the priced sample as the product listed in search; beyond the site; and running it all as records from the staff app) is in docs/WEBSITE.md sections 13 to 21, drawn in docs/website-map.html. Marketing and lead magnets (who names the stone and who buys it; fourteen magnets ranked by evidence; channels in order for one person; forty firms; the Gulf's year; consent, bribery and claims rules; measuring from sample to order) are in docs/MARKETING.md, drawn in docs/marketing-map.html. Other stone companies' websites (37 read page by page; best in class and what each lacks; where ours stands feature by feature; sixteen gaps and what was done; faults to guard against) are in docs/COMPETITORS.md. How the website and portal move (measured against 19 premium sites; one curve, short rises, fades; a live sheet) is in docs/SITE-MOTION.md and docs/site-motion.html. The website's own look (editorial, not app-like: photographs to the edges, type and space instead of boxes, one quiet action; a wide-screen layout proposed; who keeps each part current) is in docs/SITE-DESIGN.md, drawn in docs/website-design.html. The catalogue (one record per stone feeding every place; seven kinds of name and how far each may travel; variants; readiness per place; adding, changing and withdrawing; how a customer keeps the name they used, with the mapping to our stone on staff screens only and no public page per market name: Revision 2) is in docs/CATALOGUE.md, drawn in docs/catalogue-map.html. The home page and landing pages (eleven parts in the order a stranger asks; fourteen blocks filled from records; pages by use, market, audience and campaign, each needing something of its own) are in docs/LANDING.md. Articles, facts and history (a library where no claim passes without a sourced fact; what may and may not be said about Omani stone; two sourced timelines) are in docs/EDITORIAL.md. Getting the app onto a phone (staff install from Chrome before signing in; customers are offered it once after a useful moment and never need it; drivers install nothing; updates; what goes wrong) is in docs/INSTALL.md. The Halo and the Omnibar, replanned (what each does, how a person adds, removes and reorders rings, putting work off and handing it over, nine Omnibar modes, their parts, and 44 problems with answers) are in docs/SHELL.md, drawn in docs/shell-map.html. US dollars and other currencies through every module are in docs/CURRENCY.md. Components and motion: the 96 components of the shared interface, each with named parts, a few kinds, switchable features and all its states, are in docs/COMPONENTS.md; the evaluation of the motion plan and its completed specification are in docs/MOTION.md; both are drawn with live samples in docs/component-map.html. Every technology, what it does, what it gains and what it connects to is in docs/STACK.md, drawn in docs/stack-map.html. Documents and terms (every paper made from the record and fixed once issued, default terms as versions attached by rule, recorded acceptance, the PDF maker, sharing, the verification code, bank-detail fraud, readiness for e-invoicing in 2027) are in docs/DOCUMENTS.md. Where AI helps, module by module, is in docs/AI.md. How the system itself works (its parts, the path every change takes, fourteen system flows, record stages, every automatic step, every outside service, what runs on a clock and what it never does alone) is drawn in docs/system-flows.html. docs/BRAND.md also lists where this plan disagrees with decisions recorded in the earlier repository.

12. Risks

13. Google Cloud setup

A new project under admin_temp@basegws.venturealliance.om. That account's sign-in on this machine has expired; the other login folders found hold different accounts.

Cost is an estimate only: a few tens of rials a month for the test project, mostly the database. The budget alert is the safeguard.

Scripts: infra/gcp/new-project.ps1 (creates the project; database only with -WithDatabase) and infra/gcp/disable-demo.ps1 (switches off the old demo).

14. Cloudflare setup

What the account shows (read on 2026-11-11)

What Cloudflare does in the new build

Addresses

Order of work

1. Two-step sign-in and a second administrator.
2. Turn on "Always use HTTPS", raise minimum TLS to 1.2, add the www redirect.
3. Replace the global key with narrow tokens.
4. Create the app projects and the API Worker on dev addresses.
5. Remove old records and Workers once the owner confirms they are unused.

15. Build stages

Each stage ends with something in real use. No dates are promised; sizes are relative.

The accountant's decisions are needed early even though Money is Stage 3, because the chart of accounts shapes the invoices customers see in Stage 1.

16. Decisions needed