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

Key Concepts

• Monorepo Architecture: Using Turbo Repo to manage multiple applications (Dashboard, Widget, Embed) and shared packages (UI, Backend, Math) in a single repository.
• Convex: A reactive, open-source database that handles real-time data synchronization, backend functions (queries, mutations, actions), and AI agent orchestration.
• Clerk: Authentication provider used for B2B multi-tenancy, managing organizations, and securing API routes.
• AI SDK (Vercel): Framework for integrating AI models (OpenAI, Gemini, etc.) with support for tool calling, message history, and streaming.
• Sentry: Production-grade error tracking with session replay and full-stack visibility.
• Vapi: Voice AI platform for building conversational agents, integrated via "Bring Your Own Key" (BYOK) for white-labeling.
• State Management: Using Yotai for atom-based state management across the widget and dashboard.

---

1. Project Architecture & Setup

• Monorepo Structure: The project uses pnpm workspaces and Turbo Repo. It includes three main apps: web (Operator Dashboard), widget (Customer Chatbox), and embed (Developer Toolkit).
• Shared Packages: Common logic is abstracted into packages/ui (Shadcn UI components), packages/backend (Convex schema/functions), and packages/math (utility examples).
• Tooling: Next.js 15, React 19, Tailwind CSS v4, and pnpm v10.

2. Backend & Database (Convex)

• Schema Design: Tables include users, conversations, contactSessions, and messages.
• Internal vs. Public API: Functions are categorized into public (for the widget) and private (for the authenticated dashboard).
• Actions vs. Mutations: Mutations are used for database operations, while Actions are used for third-party API calls (e.g., OpenAI, Clerk).
• Real-time Sync: Convex’s sync engine automatically updates the UI when database records change, eliminating the need for manual WebSocket management.

3. Authentication & Multi-tenancy

• Clerk Integration: Every account is scoped to an organization. The system enforces organization-level isolation.
• Anonymous Sessions: The widget uses a session-based anonymous authentication method (storing name/email in contactSessions with a 24-hour expiry) to reduce friction for support seekers.
• Middleware: Protects routes by ensuring users are authenticated and belong to an active organization.

4. AI Voice & Chat Agents

• Voice Agents: Integrated via Vapi. The tutorial demonstrates a "Bring Your Own Key" (BYOK) framework, allowing B2B customers to input their own API keys, which are stored securely using AWS Secrets Manager (or environment variables).
• AI Chat: Uses the convex-dev/agent component. It supports thread-based history, allowing the AI to maintain context across messages.
• Tool Calling: AI agents are equipped with tools (e.g., resolveConversation, escalateConversation) to perform actions based on user intent (e.g., "I want to talk to a human").

5. Error Tracking & Observability

• Sentry Integration: Configured for full-stack visibility. It captures frontend errors, backend API failures, and provides "Session Replay" to help developers reproduce user issues.
• Convex-Sentry Integration: Backend errors are piped into Sentry, providing backend context (function names, user identity) alongside frontend breadcrumbs.

6. UI/UX Components

• Shadcn UI & KBO UI: The project utilizes Shadcn for base components and KBO UI for specialized AI chat components (e.g., AIConversation, AIInput, MessageContent).
• Infinite Scroll: A custom useInfiniteScroll hook manages paginated data fetching, triggered by intersection observers.
• Theming: A custom global theme is applied via globals.css, optimized for a clean, professional "customer support" aesthetic.

---

Synthesis/Conclusion

The "Echo" platform is a blueprint for a modern 2025 B2B SaaS product. By leveraging a monorepo architecture, it separates the operator's dashboard from the customer-facing widget while sharing core business logic. The combination of Convex for real-time state, Clerk for secure multi-tenancy, and AI SDK for intelligent agent orchestration creates a production-ready system. The project emphasizes "production-grade" features like error tracking (Sentry), infinite scrolling, and secure tool calling, providing a scalable foundation for any AI-powered customer support business.