- AI
- E-commerce
- Web
An AI hair consultant that checks chemical history before it recommends anything, embeddable on the brand storefront.
- Services
- Artificial Intelligence
- Commerce & Growth
- Web & Mobile
- Technologies
- Next.js
- React
- TypeScript
- Tailwind CSS
- RAG
- Open Knowledge Format
- +15 more
- What the client needed
- Prohall Professional is a Brazilian professional hair-care brand selling formaldehyde-free keratin treatments and salon-grade home care. Which product is right depends entirely on the customer's hair — its type, its porosity, its damage level and, above all, its chemical history. Recommending a keratin treatment to somebody who has just bleached their hair produces an unhappy customer and a safety problem rather than a sale. The brand needed a storefront that qualifies a customer before it sells to one.
- What we built
- The platform replaces the product grid and the search box with a single question — "What's going on with your hair?" — and an AI consultant behind it. Customers describe their hair in their own words, take a roughly sixty-second guided quiz, or scan a photo, and any of those routes is distilled into one structured hair profile. The consultant asks before it guesses, grounds every recommendation in the brand's real product line, and is comfortable saying that the answer is just advice when no product is the right move. It was delivered as a standalone application and as an embeddable consult widget for the brand's existing Shopify storefront.
- Why it mattered
- Professional chemistry sits in a regulated category where a confident wrong answer costs trust rather than a single conversion. A stock "ask our AI" widget will invent ingredients, claims and products that do not exist, which is a legal and brand-trust liability here. Putting a deterministic safety gate and a human-approved knowledge base around the model is what made the consultant something the brand could put in front of customers. It also turns the storefront into the brand's actual differentiator — salon expertise — instead of a catalogue with a search box.
At a glance
- Three intake modes: text, quiz and photo
- Safety gate runs before the model
- Answers only from approved brand knowledge
- Trilingual across English, Spanish and Portuguese
Selling professional hair chemistry direct to consumers raises problems a normal e-commerce build never has to solve. The recommendation is a safety decision before it is a sales decision, and the customer describing the problem rarely has the vocabulary for it. The difficult part was never generating fluent text — it was refusing to generate the wrong thing.
- 04
Business constraints
- Layering a keratin treatment on freshly bleached hair can damage it, so the product logic had to refuse or defer in the right situations rather than upsell.
- Cosmetic guidance is regulated, so every answer had to stay salon-style and MoCRA-aligned with no medical claims in any language.
- The brand already sold on Shopify, so the consultant could not be a walled garden that ignored the storefront already driving checkout.
- A hallucinating chatbot would have damaged brand trust faster than any catalogue page could rebuild it.
- 04
Technical constraints
- Customers speak in plain language rather than SKUs, so free text, quiz answers and photographs all had to resolve into one structured hair profile.
- The same consultant had to run on a second domain, which meant exposing a public API cross-origin without opening it to the world.
- The marketing domain's www and apex hosts count as different origins, and the mismatch broke the embed until origin matching was made exact and configurable per environment.
- Photographs arrive at unpredictable quality, so assessment needed confidence handling and a gate that asks for a retake instead of guessing.
- 04
What the old system could not do
- A product grid and a search box cannot ask about chemical history before returning a result.
- A generic "ask our AI" widget answers from general knowledge, so it confidently invents ingredients, claims and products that do not exist.
- Off-the-shelf chat tools give the brand no way to govern exactly what the assistant is allowed to know.
- Nothing in the existing storefront could turn a plain-language description of hair into a profile the system could reason over.
- 01Discovery
Advice first, products second
The engagement started from the brand's own reality: the right product depends on hair type, porosity, damage and chemical history, and sometimes there is no right product at all. That reframed the entry point from a catalogue to a single question, and made "sometimes the answer is just advice" a supported outcome rather than a failure state. It also fixed the compliance line early — cosmetic, salon-style guidance, never a medical claim.
- Advice-first positioning
- Compliance boundaries
- Intake mode definitions
- 02Technical planning
Guardrails on both ends
The core decision was made before the first prompt: a raw language model would not talk directly to customers. The reasoning was planned as composable, independently tested modules — safety, knowledge, recommendation, vision and distillation — with guardrails on both ends of the pipeline. A model gateway was specified as well, so the reasoning layer would not be locked to a single provider.
- Pipeline stage contract
- Cite-or-refuse policy
- Module test boundaries
- 03Architecture
A per-customer hair brain
The data model was built around a personal hair record isolated with Row-Level Security: the evolving profile, past chemical services with recency confidence, distilled interactions, and recommendations carrying their gate status and outcome. A vector-searchable knowledge base holds the product and hair-science ground truth. The consult request flow was fixed as validation, distillation, safety gate, retrieval, grounded synthesis, verifier, then a streamed response.
- Row-Level Security data model
- pgvector knowledge base
- Consult request flow
- 04Design
Editorial, monochrome, mobile-first
The interface is a typographic system with a serif display face and generous whitespace, closer to a considered brand site than a SaaS dashboard. The phone layout is the primary design, since most hair-care browsing happens on a phone. Trust markers and the "real advice first, products second" framing appear before a single product does.
- Mobile-first layouts
- Trust marker system
- Guided quiz path
- 05Build
Gate, grounding and verifier
The safety gate was built as pure, testable logic that runs before the model, so the safety decision never depends on a generated guess. The knowledge modules — retrieval, grounding, routing, answer synthesis and a verifier policy — were built around an Open Knowledge Format layer that turns the brand's approved markdown into the only ground truth the assistant may use. Unit tests cover the highest-risk logic and end-to-end tests cover the critical flows, including a production configuration.
- Deterministic safety gate
- OKF knowledge pipeline
- Vitest and Playwright suites
- 06Launch & scale
Embedding on the storefront
The application went live on Vercel with environment-scoped configuration and a health endpoint. A dedicated public-consult layer then exposed the same assistant to the Shopify storefront on a different domain, guarded by an exact-match origin allowlist, a per-site API key, an HMAC-signed unlock token and shared rate limiting, with regression tests covering both the www and apex hosts. The back-office was handed to the brand team behind role-based access control and an append-only audit log.
- Hardened public consult API
- Origin regression tests
- RBAC back-office handover
Three-modal intake
Customers start whichever way suits them, and every route produces the same structured hair profile the rest of the pipeline reasons over.
- Free-text description
Customers describe their hair in their own words, and a distillation layer converts that into intent plus interpretation rather than storing a verbatim transcript.
- Guided quiz
A roughly sixty-second tappable path lowers the barrier for people who do not know what to ask, and lands on the same profile as free text.
- Photo scan with a quality gate
Vision assessment returns structured observations as attribute, value and evidence with confidence handling, and a client and server quality gate asks for a retake when an image is unusable.
- Voice input
Speech-to-text lets a customer simply talk about their hair instead of typing it, which matters most in the phone layout.
The deterministic safety gate
The safety decision is pure logic that runs before the model rather than an inference the model is trusted to make.
- Chemical history as input
Past colour, bleach, keratin and relaxer services are stored as records with recency confidence, and those records are what the gate reads.
- Ask-first questions
Where the history is missing or recent the gate can force a clarifying question — "before I recommend anything, when did you last colour it?" — instead of returning a regimen.
- Clear, wait or strand test
The gate returns one of three verdicts and can hold a recommendation entirely rather than quietly softening it.
- Independent of the model
The gate lives in its own module with its own unit tests, so a change to a prompt cannot talk it out of a verdict.
Grounded, cite-or-refuse answering
Answers are assembled only from a human-approved knowledge base, and a second pass checks the drafted answer against its sources before it reaches the customer.
- Open Knowledge Format corpus
The brand team's approved markdown is loaded, parsed and indexed into the corpus that becomes the only ground truth the assistant may draw on.
- Similarity retrieval
The product and hair-science knowledge base is vector-searchable in pgvector and queried by similarity on every consult.
- Second-pass verifier
A verifier policy checks the composed answer against the sources it cited before the response is streamed back.
- Advice as a valid outcome
Where no product is the right move the consultant says so, and it makes no medical claims in English, Spanish or Portuguese.
Commerce and the embeddable API
The consultant extends the brand's existing Shopify presence rather than replacing it, and runs on the marketing domain through a hardened public API.
- Shopify catalogue and checkout
Storefront and Admin API integration covers catalogue sync, cart, customer account, checkout and order sync, with incoming webhooks verified by HMAC.
- Product page back into consult
Product pages carry a path straight back into the consultant, so a customer can ask whether that particular product fits their hair.
- Cross-origin guards
The public consult layer is protected by an exact-match origin allowlist with correct CORS preflight handling, a per-site API key, an HMAC-signed unlock token and shared rate limiting.
- Governed back-office
The brand team curates the approved knowledge, reviews product entries and conversations and generates articles behind role-based access control, an append-only audit log, and admin routes that return a normal 404 to unauthorised visitors.
A consult is validated and distilled into a profile, gated on chemical history, then answered only from the approved knowledge base and verified before it streams back.
- describe or scan flows from Customer to Validation and distillation.
- Data flows from Validation and distillation to Personal hair brain.
- hair profile flows from Validation and distillation to Deterministic safety gate.
- Data flows from Personal hair brain to Deterministic safety gate.
- ask first returns from Deterministic safety gate to Customer.
- retrieval flows from Deterministic safety gate to Approved knowledge base.
- Data flows from Approved knowledge base to Grounded answer synthesis.
- Data flows from Shopify Storefront and Admin to Grounded answer synthesis.
- Data flows from Grounded answer synthesis to Second-pass verifier.
- streamed answer returns from Second-pass verifier to Customer.
A catalogue that behaves like a stylist
A live AI hair consultant runs at www.prohall.ai and embeds on the brand's Shopify storefront.
Text, quiz and photo intake plus voice input, delivered across a full English, Spanish and Portuguese experience.
A safety-gated, grounded recommendation pipeline that provably asks before it recommends.
A governed back-office covering knowledge curation, product-library and conversation review, and staff management under RBAC with an audit trail.
Verified figures have not been published for this engagement. These are the outcomes the team can attest to.
Frontend
- Next.js
- React
- TypeScript
- Tailwind CSS
AI
- RAG
- Open Knowledge Format
- OpenRouter
- Vision analysis
- Speech-to-text
Backend
- Zod
- HMAC-signed tokens
Data
- Supabase
- PostgreSQL
- Row-Level Security
- pgvector
Commerce
- Shopify Storefront API
- Shopify Admin API
Infrastructure
- Vercel
- Rate limiting
- Vitest
- Playwright
Tell us the constraint you are trying to remove. A senior engineer reads every enquiry and replies within one business day.