Skip to content
VirtuAIVirtuAI Docs

Architecture and data flow

How a message flows

Section titled “How a message flows”
VirtuAI data flowPeople and channels send messages to the VirtuAI application on Google Cloud in us-central1. The application stores data in Cloud SQL for PostgreSQL and Cloud Storage, and sends prompts to the model provider the customer chose, using the customer’s key. It can also call services the customer connects, and sends usage events to product analytics.People and channelsWeb chat and voiceWhatsApp (Twilio)Google ChatSlack and TelegramA2A and API clientsHTTPS · sign-in, integrationkey or channel signatureVirtuAI on Google Cloud · us-central1VirtuAI applicationGoogle Kubernetes EngineDatabaseCloud SQL forPostgreSQLFile storageCloud StoragePrivate network · encrypted connectionsEncrypted at rest by Google CloudWorkspace secrets also encrypted by VirtuAIOutside VirtuAIModel provider you chooseGemini or Vertex AIOpenAI · Anthropicusing your keyServices you connectTools, MCP servers, voice,tracing, code sandboxProduct analyticsPostHog (US)
A message comes in on a channel, the application runs the agent, stores the turn, and calls the model provider configured on that agent.
  1. A person writes to an agent on a channel. The request reaches VirtuAI over HTTPS and is checked with the channel’s own mechanism: Twilio’s request signature for WhatsApp, Google’s signed token for Google Chat, the app’s signing secret for Slack, the webhook secret VirtuAI generated for Telegram, a signed-in workspace member for web chat, and an integration key for voice when enforcement is on. Requests that fail the check are rejected before any agent runs.
  2. VirtuAI finds the agent, the workspace it belongs to, and that workspace’s settings and keys. If a budget set to Block is used up, the run stops here on the channels budgets cover.
  3. The agent searches its knowledge bases and calls its tools as needed, then sends the conversation to the model provider configured on the agent, using the workspace’s key.
  4. The reply goes back to the channel. The turn is stored and scanned for sensitive data, and token usage is recorded for budgets and analytics.

Where your data lives

Section titled “Where your data lives”
Data Where it’s stored Notes
Accounts: name, email, workspace memberships and roles Database Passwords are stored as bcrypt hashes
Agents, versions, tools, skills and MCP server connections Database Scoped to the workspace. Telegram and Slack credentials on agents are encrypted by VirtuAI before storage.
Conversation transcripts and agent worklogs Database See data retention
Sensitive data findings Database Category and position only, never a copy of the value
Conversation access log Database Who viewed, revealed, exported or re-scanned what, and when
Knowledge base files Cloud Storage The originals you upload
Knowledge base search index Database Text chunks and their embeddings
Workspace settings and provider keys Database Secrets encrypted by VirtuAI before storage
Integration keys and invitation links Database Keyed hashes only
Token and cost usage Database Kept for 90 days
Assistant avatars and branding images Cloud Storage

What leaves Google Cloud

Section titled “What leaves Google Cloud”
Sent to What When
The model provider on the agent The conversation, instructions, and tool and knowledge base results for that turn Every agent turn
The embedding provider in EMBEDDING_PROVIDER Text from knowledge base documents, and the search query When a document is indexed, and when an agent searches
Channel providers The messages on that channel When the channel is connected
Services you connect Whatever the agent sends to the tool, MCP server, voice provider, tracing service or code sandbox When the agent uses it
PostHog (United States) Usage events: model, tokens, cost, latency, and the prompt and response text of model calls Every model call

See the Security overview for encryption, access control and retention.