Case studies - AI scoping assistant: architecture and build

A conversation before the contact form

For most people, the hardest step in commissioning a website or a system happens right at the start: turning a still-fuzzy idea into a message they can actually send. How much detail is enough? Does the wording sound professional? Should budget come up this early? Faced with these hesitations, many collaborations that could have happened stall at an empty form.

The form didn't do anything wrong. The format simply asks visitors to complete the hardest part of the entire process — scoping the requirements — alone. And that is precisely the work the technical side should be doing with them.

This time, the client was us. More precisely: every visitor who lands on the helloio site with an idea they can't quite articulate yet. We decided to replace the intake form with a conversation.

Scoping, one question at a time

We built a scoping assistant into /start: visitors describe what they want to build in a few sentences, the assistant restates the idea in its own words to confirm it understood, then asks exactly one scope-defining question at a time — does a booking need approval before it's confirmed, are there existing systems to integrate with, what scale are we building for? No questionnaires, no rushing ahead.

After each reply, the system generates a few quick suggestions for how the visitor might respond, so even people who would rather not type can carry the conversation through. After roughly four to seven turns, the assistant condenses everything into a structured project brief: the core goal, desired features, tools to integrate, an initial technical direction, and a sense of scale. The visitor confirms, leaves a name and email, and sends it off in one click — the brief and the full conversation land in our inbox, our Notion CRM, and our Discord at once, while a confirmation email goes to the visitor: four channels in all.

When visitors ask to see real cases, the assistant picks the most relevant of our public case studies and shares a clickable link. The entire experience ships in both Chinese and English, with the language matching the site you're on — consistent and predictable.

Grounding answers in real knowledge

The biggest risk of a conversational interface is a model inventing answers where its knowledge runs out. We close that gap with retrieval-augmented generation (RAG).

The idea behind RAG is straightforward: instead of expecting the model to remember everything, you retrieve the most relevant material from your own knowledge base before it answers. The model handles understanding and expression; the facts come from your data. For any team bringing AI into their own service, this is what grounds it in your business rather than letting it invent answers.

We distilled helloio's services, technologies, process, and public case studies into a bilingual knowledge base — every entry written and reviewed by hand — then embedded it with Voyage into vectors built for semantic retrieval, stored in PostgreSQL's pgvector extension. On every turn, the system retrieves the entries most relevant to the visitor's recent messages and injects them into the model's context — that's what lets the assistant cite real cases and state accurate capability boundaries instead of speaking in generalities.

The conversation itself runs on Claude Sonnet; quick replies are generated in parallel by the lighter Claude Haiku; the unchanging persona and rules are cached and reused (prompt caching), keeping per-turn latency and cost low.

For the knowledge layer we chose the pgvector vector database over simple file-based retrieval. It is the same architecture we deliver when building AI integration for clients, and it leaves room to grow: from today's scale to many times larger, across multiple product lines, all on the same foundation. When a project calls for maximum lightness, file-based retrieval is a perfectly sound route — a trade-off we advise on case by case.

The details of the experience are something visitors rarely name but readily feel. Replies stream in character by character, and we used the browser's MutationObserver to measure per-frame output, flattening the model's bursty token cadence into a steady typing rhythm. This kind of work, buried beneath the surface, is exactly what makes a conversation read smoothly.

Cost and security, built into the foundation

A chat endpoint that requires no login, is open to everyone, and bills you on every call is, to an attacker, an open invitation to drain your wallet. The risk has a name — Denial of Wallet, catalogued under "Unbounded Consumption" in the OWASP Top 10 for LLM applications. From day one, defending against it was treated as fundamental work, not an afterthought.

The defense has three layers. The first lives in code: hard caps on the maximum cost of a single request — turns, message length, and total input size. There's an easy-to-miss subtlety here: the chat endpoint keeps no conversation state of its own — the full history is supplied by the browser — while model parameters only limit the output. Without a server-side cap on input, an attacker can forge a five-hundred-message history and blow up the cost of every single turn.

The second layer is a human gate: after passing one Cloudflare Turnstile check, the server issues a short-lived signed pass that every subsequent chat request must present — bots never reach the paid endpoint at all. The third layer is a billing-level spend cap as the final backstop. Each layer does its own job; if one is ever bypassed, the next still holds.

Honesty is a design feature

We spent more effort teaching the AI what not to say than making it eloquent. The assistant never quotes exact prices — estimates need human judgment, so it speaks only in scale. Requests outside our scope (a native app, say) get a straight answer that this isn't our focus, along with an alternative direction. Asked "are you human?", it answers plainly that it's an AI assistant powered by Claude, and that a person from helloio takes over from here.

None of this is the model's natural disposition; it is designed, rule by rule, into the system prompt. One prompt serves both languages — the English site layers a thin language override on top, inheriting the persona, the rules, and the brief format. Both languages run on a single core.

After launch: data over guesswork, privacy done right

The assistant shipped together with seven entry points across the site — a conversation box in the homepage hero, a dual-path call to action in the footer, contextual links on the process and case pages — each carrying a source tag. Which entry starts the most conversations, and which converts them into submitted briefs — the data answers, so we don't have to guess.

Conversations are used to improve the service and patch gaps in the knowledge base. Both the interface and the privacy policy state this clearly: conversations that don't lead to a submitted brief are deleted automatically after ninety days, and records are never linked to browser identifiers. The way we treat data should hold to the same standard as the way we treat code.

What we sell is what we run

With the assistant live, the helloio intake changed from "please fill in the form" to "let's figure it out together". Outwardly, it is where real project inquiries arrive every day; inwardly, it gives every technology we offer — Claude integration, vector retrieval, streaming interfaces, security hardening — a working example anyone can open and try.

For helloio, the real gain of this project was turning what an AI assistant ought to be into operable engineering: grounded in real knowledge, upfront about its limits, careful with people's data. If you're weighing AI for your own product or workflow, this assistant is our first answer to that question — go have a chat with it.

What we did