Case study
minaz
A chat widget businesses add with one script tag. It answers visitors only from the business’s own website and documents, cites its sources, and says so when it doesn’t know.
- Status
- In active development, Oct 2026 to present
- Shape
- pnpm + Turborepo monorepo, six packages
- Stack
- Next.js, TypeScript, Cloudflare Workers, PostgreSQL, pgvector, Prisma, Supabase, Trigger.dev, OpenRouter, Preact, Tesseract, Vitest
The problem
A small business’s visitors ask the same questions its website already answers, and a general chatbot answers them with confidence whether or not the site agrees.
minaz is the opposite trade: it only says what the business’s own pages and documents say, shows where it read it, and tells the visitor plainly when the answer isn’t there, so the owner can see the gap and fill it.
Architecture
- web
- Next.js 16 dashboard and marketing site on Cloudflare Workers (OpenNext), Tailwind v4, shadcn/Radix.
- chat-worker
- Hand-written Cloudflare Worker chat API: origin allowlist, rate limiting, query rewriting, hybrid retrieval, SSE streaming with citations, tool calling.
- ingest
- Trigger.dev durable tasks: URL, sitemap and crawl discovery, headless rendering for JS pages, PDF/DOCX/TXT/Markdown parsing, Tesseract OCR for scanned PDFs, token-aware chunking, embeddings.
- db
- PostgreSQL on Supabase with Prisma, pgvector and full-text search.
- widget
- Preact, built with Vite into a single 41 KB script, isolated in Shadow DOM.
- billing
- Usage metering through a merchant-of-record SDK.
Key decisions and trade-offs
Hybrid retrieval, built in Postgres
Vectors and full-text search live in the same table, so one SQL function ranks both and fuses them with Reciprocal Rank Fusion. No second search service to sync, and text search configs are chosen per language.
-- Hybrid search: fuse vector and full-text rankings with Reciprocal Rank Fusion
with semantic as (
select id, row_number() over (order by embedding <=> p_embedding) as rank
from chunks
where org_id = p_org
order by embedding <=> p_embedding
limit 40
),
keyword as (
select id, row_number() over (order by ts_rank_cd(fts, q) desc) as rank
from chunks, websearch_to_tsquery(p_config, p_query) q
where org_id = p_org and fts @@ q
order by ts_rank_cd(fts, q) desc
limit 40
)
select id,
coalesce(1.0 / (60 + s.rank), 0)
+ coalesce(1.0 / (60 + k.rank), 0) as score
from semantic s
full outer join keyword k using (id)
order by score desc
limit p_k;Tools that can’t double-book
The agent can book meetings and fire webhooks, which means a network retry could act twice. Every tool run is keyed by conversation and call id, actions that change something wait for the visitor to confirm, and each call has a timeout and bounded retries.
// A retried tool call must never book the same slot twice.
async function runTool(call: ToolCall, ctx: Ctx) {
const key = `${ctx.conversationId}:${call.id}`;
const prior = await db.toolRun.findUnique({ where: { key } });
if (prior?.status === "succeeded") return prior.result;
if (call.needsConfirmation && !ctx.confirmed(call.id)) {
return { status: "awaiting_confirmation", summary: describe(call) };
}
const result = await withRetry(() => tools[call.name](call.args, {
signal: AbortSignal.timeout(8_000),
idempotencyKey: key,
}));
await db.toolRun.upsert({ where: { key }, create: { key, status: "succeeded", result }, update: { status: "succeeded", result } });
return result;
}- Multi-tenant: Supabase Auth (email and Google), organizations, owner/admin/member roles, invitations, per-plan limits.
- Usage-based pricing: one action is one answered question or one integration run, with visible, capped overage.
- Conversations dashboard: URL-driven filters, server pagination, no-answer tracking, CSV export that is safe from formula injection.
- Per-step token and USD cost logging, and a cost-per-action margin report.
What I’d do next
- Tune retrieval on the first real customer content, using the questions it couldn’t answer.
- Use the per-action cost report to set plan limits from measured margins, not guesses.