Documentation

How Advi Systems works, in plain language.

These guides describe the system as it ships today — every claim here is something you can verify by clicking around the dashboard or watching the network tab. Prompt Studio for structured prompts, Advi Agents for lead capture, both protected by Clerk sign-in, backed by Supabase in Frankfurt, and powered by OpenRouter as the AI gateway.

Product guides#

Two products and a security overview. The product guides walk you through the setup flow, what happens behind the scenes when you use them, and how to get reliable results. The security page is written for procurement and compliance reviewers — short enough to read in one sitting, detailed enough to brief a security team.

01guide

Prompt Studio guide

A guided form that turns a vague AI request into a structured, repeatable prompt. Learn what each of the twelve fields does, why structure beats freeform, how the result is generated, and how to iterate on past runs.

Read guide

02guide

Advi Agents guide

AI chat agents you embed on your website or connect to messaging apps. Learn how to create an agent, upload knowledge, deploy the widget, capture leads, and route conversations to humans or your CRM.

Read guide

03guide

Security notes

How sign-in works, how your workspace is kept separate from everyone else's, what data is sent to AI providers and what isn't, and where everything is stored. Written for buyers and procurement teams.

Read guide

What the platform actually is#

Advi Systems is two products bolted onto one account system. The four notes below explain who owns what, what each product does, how AI is called, and where your data physically lives. If you take nothing else away, take these four.

01note

Who can do what

Everything inside the dashboard is gated by sign-in. When you create or join an organization, that organization becomes your workspace and every piece of data you create — prompts, agents, conversations, knowledge — is tagged with that workspace's ID. Other workspaces never see it. If you sign in without joining an organization, you get a personal workspace that works the same way but for just you.

02note

Two products, one account

Prompt Studio is the prompt-engineering side: a structured form that crafts production-quality prompts in 20+ proven frameworks (CO-STAR, RTF, PAIN, RISE, and so on). Advi Agents is the lead-capture side: AI chatbots you embed on your website or wire to WhatsApp, Telegram, Messenger, and Instagram. Both share the same sign-in, the same billing, and the same workspace.

03note

How the AI is reached

All conversations with language models go through OpenRouter — a gateway that lets us route to OpenAI, Anthropic, Meta, Mistral, Google and others without separate integrations. The API keys live only on our servers, never in your browser, and only the models on our approved list are reachable. If a request asks for a model that isn't on your plan's allowlist, the request is rejected before any provider is contacted.

04note

Where your data lives

Your prompts, agents, conversations, contacts, and knowledge are stored in Supabase Postgres in Frankfurt, Germany — inside the EU. We use pgvector (a Postgres extension) to store and search 'embeddings' of your knowledge base — numerical fingerprints that let the system find the most relevant passages for each visitor question in milliseconds. The credentials that can read and write the database are server-only; your browser never sees them.

What it's built on, and why each choice matters#

The stack is intentionally small. Fewer moving parts means fewer places where data can leak, fewer vendors to vet, and fewer failure modes. Here is everything load-bearing in the system.

Browser side

Next.js 16 — the framework that serves the dashboard and runs API routes on the same server. Pages render on the server first so the browser receives a finished page, not a loading spinner.
React 19 — what builds the interactive parts of the dashboard. Streaming responses (like the prompt generator) update the screen as data arrives rather than waiting for it to finish.
Tailwind CSS — the styling layer. Every visual token (colors, spacing, type) is defined once and reused, which keeps the UI consistent.
Clerk — handles sign-in, sign-up, password reset, organization switching, and (where you enable it) multi-factor authentication. Clerk has SOC 2 Type II certification.

Server side

Supabase Postgres (Frankfurt) — the database. EU region, daily automated backups, encryption at rest done by the provider.
pgvector — a Postgres extension that stores 1,536-number fingerprints of every knowledge-base item so the system can find the most relevant ones for each visitor question. Searches use an HNSW index, which is the same algorithm used inside production search engines.
OpenRouter — the gateway that forwards prompts to the actual AI provider (OpenAI, Anthropic, Meta, Mistral, Google). One integration, every model.
Server-only secrets — every API key (OpenRouter, Supabase service role, Clerk secret, channel webhook secrets) exists only inside server code. They are never sent to your browser and never embedded in the widget bundle.

What the API exposes, and what's locked#

The system has two completely separate API surfaces. Authenticated routes are the ones the dashboard talks to — every request must include a valid Clerk session, and the server filters every database query by your workspace. Public routes are the ones the embeddable widget calls from visitor browsers — they only accept a public agent token and can only see that single agent's chat, knowledge retrieval, and lead capture. They cannot reach your management data, even if a visitor reverse-engineers the widget.

Method	Path	What it does	Access
POST	/api/refine	Sends your Prompt Studio form to the AI and streams the refined prompt back as it generates.	Sign-in
GET	/api/prompts/history	Returns the prompts you've saved in this workspace, newest first, paged at 100.	Sign-in
POST	/api/prompts/history	Saves a freshly generated prompt to your workspace so you can re-open or iterate on it later.	Sign-in
DELETE	/api/prompts/history/[id]	Removes a single saved prompt from your workspace. Other workspaces' prompts are not addressable here.	Sign-in
GET	/api/agents	Lists the agents you've created in this workspace.	Sign-in
POST	/api/agents	Creates a new agent with the persona, model, knowledge, and widget settings you choose.	Sign-in
GET	/api/agents/[id]	Returns the full configuration for one of your agents.	Sign-in
PATCH	/api/agents/[id]	Updates settings on one of your agents — system prompt, colors, channels, tools, anything editable.	Sign-in
DELETE	/api/agents/[id]	Deletes the agent and every related record (knowledge, conversations, contacts, sessions) in one operation.	Sign-in
GET	/api/agents/analytics	Aggregated session, message, contact, channel, and conversion counts for your workspace.	Sign-in
GET	/api/widget/[token]	Returns the embeddable chat widget as JavaScript. Loaded by the <script> tag on your website.	Public
POST	/api/agent/[token]/chat	The visitor sends a message; the agent reads its knowledge base and streams a reply back.	Public
POST	/api/agent/[token]/lead	Saves a visitor's name, email, or phone when they choose to share it. Also fires your lead webhook.	Public
POST	/api/agent/[token]/handoff	Visitor asks for a human; fires your handoff webhook with the full transcript attached.	Public
POST	/api/agent/[token]/csat	Captures the visitor's satisfaction rating (0–5) at the end of a conversation.	Public

The "Sign-in" routes return 401 Unauthorized if you are not signed in — they are not browsable from a public URL. The "Public" routes only ever address a specific agent through that agent's token; they have no listing endpoint, no admin endpoint, and no way to enumerate other agents.