Build and Deploy a B2B SaaS AI Support Platform | Next.js 15, React, Convex, Turborepo, Vapi, AWS

Key Concepts

• Echo: A production-grade AI support platform.
• Convex: The backend-as-a-service platform used for database, storage, and serverless functions.
• RAG (Retrieval-Augmented Generation): A framework for enhancing AI responses by grounding them in external data (documentation, files).
• Embeddings: Vector representations of text used for semantic search.
• Namespacing: A security mechanism to ensure data isolation between different organizations (tenants).
• AWS Secrets Manager: Used for secure, per-tenant storage of third-party API keys (e.g., Vapi).
• White Labeling: Allowing organizations to bring their own API keys for services like Vapi to maintain data and billing isolation.
• Clerk Billing: Used for managing subscription plans and organization-level access control.

---

1. Backend Infrastructure & RAG Implementation

The project utilizes Convex to handle file storage and retrieval.

• File Handling: The system supports various file types (PDF, HTML, Images). It uses extractTextContent to convert these into raw text.
• Embeddings: The convex-dev/rag component is used to generate vector embeddings.
• Security: Embeddings are stored within Namespaces tied to an organizationID. This prevents cross-tenant data leakage.
• Optimization: A contentHash is generated from file bytes to avoid redundant re-indexing of identical files.

2. File Management & Security

• Add/Delete Workflow: Files are uploaded to Convex storage, then indexed via RAG. Deletion requires a two-step process: removing the file from storage and deleting the corresponding RAG entry.
• Authorization: Every mutation and action verifies the user's identity and organizationID to ensure users can only manage their own organization's knowledge base.

3. AI Search & Tooling

• Search Tool: A custom tool is created for the AI agent to query the knowledge base.
• Prompt Engineering: The system uses strict system prompts to prevent "hallucinations." If the AI cannot find an answer in the RAG-provided context, it is instructed to escalate to a human operator rather than guessing.
• Playground: A developer tool is integrated to test agent behavior, view tool calls, and debug prompt responses in real-time.

4. Multi-Tenancy & Billing

• AWS Secrets Manager: To support white labeling, the app stores third-party API keys (e.g., Vapi) in AWS Secrets Manager, keyed by organizationID.
• Clerk Billing: The app uses Clerk’s subscription plans to gate features.
  • UI Protection: The protect component from Clerk is used to wrap premium features (e.g., Knowledge Base, Voice Assistant).
  • Webhooks: A clerk-webhook endpoint is implemented to listen for subscription.updated events, which automatically updates the organization's status in the Convex database and adjusts membership limits.

5. Widget & Embed Script

• Embed Script: A Vite-based app generates a minified JavaScript file (widget.js).
• Iframe Integration: The script injects an iframe into the client's website, loading the widget app from a specific URL.
• Dynamic Configuration: The script reads data-organization-id attributes from the host page to dynamically load the correct organization's settings and chat interface.

---

Step-by-Step Methodologies

1. Embedding Generation:
   • Upload file -> Extract text (via AI or decoder) -> Generate vector embedding -> Store in RAG namespace.
2. Subscription Sync:
   • User upgrades on Clerk -> Webhook fires -> Convex upsert mutation updates subscription status -> Organization permissions (e.g., member limits) are updated via Clerk Backend API.
3. Session Management:
   • A refresh mutation is triggered on user activity (e.g., sending a message). If the session is within a 4-hour expiry threshold, it is extended by 24 hours.

Notable Quotes

• "If you take a look at the messages... we check if the conversation status is unresolved and only if it's unresolved do we actually trigger AI response."
• "We don't want to infinitely fill our embedding and not be able to delete that embedding. This way, we tightly couple them together."

Synthesis

The project demonstrates a robust architecture for a B2B SaaS. By combining Convex for real-time data, RAG for intelligent support, AWS Secrets Manager for secure multi-tenancy, and Clerk for billing, the system achieves a high level of isolation and scalability. The use of an Iframe-based embed script ensures that the chat widget can be easily integrated into any third-party website while maintaining a secure, sandboxed environment for the AI interactions.