Voice First
Vocali prioritizes real-time, low-latency audio processing above all else. Speed is the difference between a tool and an experience.
Project Insights
What buildingVocali taught me
This page documents the engineering decisions, performance discoveries, and architectural invariants of the Vocali platform. By maintaining this record, we ensure future development aligns with the core principles of low-latency AI communication.
Seamless Handoffs
AI shouldn't trap users. The architecture guarantees a smooth transition to a human agent the moment intent shifts or frustration is detected.
Enterprise Grade
Built from day one to support B2B SaaS requirements: RBAC, isolated tenant data in Convex, and strict auth boundaries.
Lessons worth preserving
AI Voice
Voice configuration is a runtime capability
The widget does not need a build-time Vapi key. It loads the organization’s public key only after the organization, session, and widget settings have been validated.
Evidence: The loading screen advances from organization validation to session validation, settings, and optional voice credentials; the Vapi hook creates its client from that resolved public key.
Watch for: Do not make voice availability depend on an unrelated NEXT_PUBLIC environment variable; it breaks tenant-configured calls before the widget can initialize.
Convex / State
Agent message ordering belongs to the agent runtime
The Convex Agent runtime persists prompts, assistant output, and tool results in the order expected by the model provider. Conversation state remains durable and reactive in Convex.
Evidence: The public message action calls generateText with tools and relies on the runtime’s storage behavior instead of inserting a second assistant message after a tool result.
Watch for: Manual persistence in the middle of a tool-call sequence can violate strict tool/result ordering and make later prompts fail.
Authentication
Dashboard identity and visitor identity are different
Clerk protects operator routes and organization membership, while the public widget uses a short-lived contact session. Both identities must be checked at their own boundary.
Evidence: Public conversation and message functions validate session expiration and verify that the session is attached to the requested organization, conversation, and thread.
Watch for: A valid contact-session ID is not sufficient authorization for another organization’s conversation or thread.
Frontend Performance
Keep rendering state local and visual effects declarative
Jotai holds widget-local state such as the active screen and organization-scoped browser session, while CSS handles decorative animation and responsive presentation.
Evidence: The widget uses atoms for durable contact-session keys and a reducer-backed initialization flow; its visual styling stays in the established Tailwind component layer.
Watch for: Avoid turning transitions or presentation-only effects into global state. Keep network lifecycle state separate from the design system.
React
Initialization is a state machine, not a race
Widget startup has ordered dependencies: organization, existing session, settings, then optional voice credentials. Each asynchronous step must ignore work after unmount or a changed input.
Evidence: The loading screen uses reducer transitions and cancellation flags around Convex actions and mutations before choosing the auth or selection screen.
Watch for: Do not collapse startup into parallel requests unless their authorization and failure modes are genuinely independent.
Database / RAG
Tenant boundaries must follow the data
Knowledge-base entries are inserted into an organization namespace, carry organization metadata, and are checked again on deletion.
Evidence: File ingestion records the storage ID and uploader organization; the support search tool derives its RAG namespace from the conversation’s organization.
Watch for: Never make a cross-tenant search convenient by falling back to a global namespace.
Security
Secrets need an explicit lifecycle
Provider credentials are encrypted with AES-256-GCM in backend storage. The public widget endpoint returns only the public Vapi credential it needs to connect.
Evidence: The encryption helper validates a 32-byte hex key, stores IV and authentication tag with ciphertext, and the public secret action drops the private key before its response.
Watch for: Do not log plaintext provider values, ciphertext parsing failures, or full integration payloads in a browser-visible surface.
Next.js
Next.js routing carries an auth contract
The proxy distinguishes public widget-support pages from protected dashboard routes and redirects signed-in users without an active organization to selection.
Evidence: The web app pairs Clerk middleware with dashboard guards and a client-only visual transition after hydration.
Watch for: Adding a page requires deciding whether it is public, organization-free, or organization-protected—not just adding a route file.
Where to look first
Auth Layout
apps/web/modules/auth/ui/layouts/auth-layout.tsxContains the branded, hydration-safe auth presentation and its visual transition boundary.
Button Component
packages/ui/src/components/button.tsxCentralized button design system with numerous light-mode optimized variants and gradients.
Convex Schema
packages/backend/convex/schema.tsDefines conversations, sessions, organization settings, subscriptions, and encrypted provider records.
Widget startup
apps/widget/modules/widget/ui/screens/widget-loading-screen.tsxCoordinates organization validation, session restoration, widget configuration, and optional voice setup.
Public ownership checks
packages/backend/convex/public/messages.tsEnforces contact-session ownership before visitor messages are read or created.
Operations and next steps
Debugging a widget that stops on startup
Check the initialization step in order: organization ID, stored session scope, widget settings, then Vapi credentials. A missing optional voice integration should still route the visitor to chat rather than fail the entire widget.
Performance boundary
Use Convex’s reactive/paginated queries for durable lists and keep animation work in CSS. Avoid a page-wide polling loop for conversations, files, or widget state.
Deployment lesson
The dashboard, widget, embed bundle, and Convex deployment are separate release surfaces. Set the production widget URL at embed build time and configure Clerk webhooks against the Convex HTTP endpoint.
Future improvement
Anonymous contact-session creation is intentionally public for the embed flow. Add rate limiting, abuse controls, and end-to-end ownership tests before operating it at high-volume public scale.
Maintenance invariants
Clerk organization membership protects operator workflows; contact sessions protect visitor workflows.
A public message operation must prove the contact session owns the conversation and thread it targets.
Knowledge-base retrieval and file ownership always stay inside an organization namespace.
The Convex Agent runtime owns persisted tool-call ordering.
Only public provider credentials may cross the widget boundary.
Widget initialization advances through explicit, cancellation-safe states.
Route access is classified in the proxy before the dashboard renders.
CSS handles presentation; local React/Jotai state handles interaction and request lifecycle.