How Chatvia works
This section explains what happens inside Chatvia, from the moment you add a file to the moment a chatter reads an answer. You don't need to know any of it to use Chatvia. It helps when you want to understand why an agent answered the way it did, or which setting to change.
The parts
A Chatvia install has five parts. They all run from the same code.
| Part | What it does |
|---|---|
| Web app | The dashboard for your team, the admin panel for the person who runs the server, the hosted chat, the widget and the API. |
| Background workers | Do the slow work outside the web request: reading files, splitting them, writing to the chat log, analytics, voice calls. |
| Real-time server | Pushes live updates to open pages: training progress, new messages, human handoff, notifications. |
| PostgreSQL | Stores everything. It also does the search: by meaning (pgvector) and by keywords (pg_textsearch or the built-in full-text search). |
| Redis | Holds the work queues, the cache, the rate limits and the recent history of each chat. |
Chatvia also talks to outside AI services. You pick them in the admin panel, under Settings → AI models. Their API keys go in Settings → AI providers.
- A chat model, which writes the answers.
- An embedding model, which turns text into numbers that capture its meaning, so it can be searched by meaning.
- Optional services: a document reader (OCR) for PDFs, Word files and images, speech to text for audio and video, a reranker that sorts search results, and smaller models for side jobs such as follow-up questions and guardrails (Models for app tasks).
The two big flows
Almost everything Chatvia does is part of one of two flows.
1. Learning: from a source to searchable knowledge. This runs in the background when you add or train a source.
- Read the text out of the source (a PDF, a web page, a recording, a typed text).
- Split the text into small parts, called chunks.
- Optionally, ask an AI model to add a short summary and the questions each chunk answers.
- Turn each chunk into an embedding (a list of numbers that captures its meaning).
- Store the chunks with their embeddings, and index them for search by meaning and by keywords.
Read more in From source to knowledge.
2. Answering: from a question to an answer. This runs every time a chatter sends a message.
- Check that the message is allowed: the agent is on, no limit is reached, the visitor is not blocked, and the guardrails find nothing wrong.
- If the question is a follow-up, like "and on Android?", rewrite it into a full question.
- If it matches a saved Q&A pair, send the saved answer. No AI model is used.
- Otherwise, search the agent's knowledge with hybrid search (by meaning and by keywords), then keep only the parts that really match.
- Build the prompt: the agent's instructions, the recent chat history, the matching knowledge and the tools it may use.
- The chat model writes the answer. It may call tools on the way.
- Check the answer, stream it to the chatter word by word, and save it.
- In the background: count the message, update analytics, sort the conversation into topics.
Read more in How search works and How an agent answers.
In this section
- From source to knowledge: how files, web pages and texts become chunks, and what the AI enhancement adds.
- How search works: hybrid search, the two keyword search engines, reranking, and the relevance check.
- How an agent answers: the checks on each message, the prompt, tools and approvals, guardrails and streaming.
- Behind the scenes: what happens after a reply, the background workers, and the scheduled clean-up jobs.