🚀 Synora — AI-Powered Business Automation Platform

Synora is a fully functional B2B omnichannel AI platform that enables businesses to deploy autonomous support copilot widgets that know their business inside and out. It handles text chats, real-time in-browser voice, and direct telephony calls right from your website, complete with hybrid RAG grounding citations, automated call sentiment analytics, dedicated leads CRM, and multi-tenant workspace collaboration.

---

🌟 Core Value Proposition

Synora empowers businesses to move beyond generic chatbots. By indexing company knowledge (websites, documentation, PDFs, and raw text), Synora generates a hardened embeddable widget that answers customer questions using state-of-the-art Hybrid Retrieval-Augmented Generation (RAG).

• Enterprise Grounding: High-precision hybrid search blending pgvector semantic embeddings with PostgreSQL tsvector full-text search and exact FAQ matching.
• Strict Anti-Hallucination Boundaries: Answers originate strictly from verified business documents. If facts are absent, the copilot honestly acknowledges the missing information and offers human escalation.
• Omnichannel Support: Unified across web chat, real-time browser voice (Vapi Web SDK), and native telephone numbers with automated AI post-call summaries.
• Built-in Leads CRM: Automatically qualifies incoming contacts, extracts business emails/phone numbers, scores buyer intent, and exports leads to RFC-4180 CSV.

---

✨ Key Features

1. 🧠 High-Precision Hybrid RAG Engine

• Multi-Format Ingestion: Ingest text, Markdown, documents, or scrape websites (with automated noise, navigation, and cookie banner stripping).
• First-Class FAQ Extraction: Automatically detects Q: and question headings during ingestion, storing questions and answers as prioritized ground-truth records.
• Hybrid Retrieval Fusion: Executes parallel semantic vector search (gemini-embedding-001, 768-dim) and PostgreSQL full-text keyword ranking (websearch_to_tsquery('english', ...)), fusing results using Reciprocal Rank Fusion (RRF $k=60$) with direct FAQ boosts.
• Contextual Query Rewriting: Dynamically resolves pronouns ("it", "that", "the pro plan") across multi-turn dialogues while eliminating query label pollution.
• Interactive Knowledge Drawer: Dashboard inspection allows operators to view chunk boundaries, verify extracted FAQ pairs, check token counts, and test real-time retrieval rankings in the RAG Simulator.

2. 🏷️ Visible Citations & Grounding Source Badges

• Transparent Evidence: Responses render clickable citation pills indicating exact grounding sources.
• Match Type Indicators: Displays whether an answer was derived via FAQ Match, Hybrid, Semantic, or Keyword search.

3. 🎙️ Triple-Mode Embed Widget

The embeddable customer widget (/embed) provides three seamless support modes:

1. Text Chat: Real-time grounded streaming chat with citation badges.
2. Voice Mode: In-browser, low-latency voice conversations powered by Vapi (<1,500ms voice RAG responses).
3. Phone Mode: Displays a dedicated telephone number for callers to reach the voice assistant over cellular networks.

4. 👥 Dedicated Leads & Visitors CRM

• Centralized Lead Directory (/dashboard/visitors): Track all prospects and customers captured across web chat and voice calls.
• AI Qualification: Automatic lead scoring (0–100), intent detection (pricing_inquiry, demo_request, etc.), and company details.
• RFC-4180 CSV Export: One-click download of all visitor and lead records formatted for HubSpot, Salesforce, or Excel.

5. 🤖 Gemini Structured Output Workflows

• Lead Qualification: Structured JSON extraction of buyer profiles and contact info.
• Automated Escalation Tickets: When an issue cannot be resolved or an operator is requested, Gemini generates a structured ticket with category, severity, and steps to reproduce.
• Call Analytics: Voice call transcripts are automatically analyzed for sentiment score ($-1.0$ to $+1.0$), churn risk (low, medium, high), and topic tags.

6. 🛡️ Multi-Tenant Workspace & Subscription Tier Guards

• Organization Scoping: Scalekit multi-user organizations share the same chatbots, knowledge bases, and conversations seamlessly via tenantScope.
• Tier Quota Guards (lib/tier-limits.ts): Enforces resource limits across Free (5 sources, 100 msgs), Pro (50 sources, 5k msgs, 5 seats), and Enterprise (1,000 sources, 100k msgs, 50 seats).
• Subscription Dashboard (/dashboard/pricing): Live usage progress meters and functional tier upgrading.

---

🛠️ Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router), React 19
Language	TypeScript, Node.js
Styling & UI	Tailwind CSS v4, Radix UI, Lucide Icons
Database	PostgreSQL (Neon serverless) with Drizzle ORM
Vector Engine	pgvector (768-dim embeddings, cosine distance)
AI / LLM	Google Gemini 2.5 Flash, gemini-embedding-001 (via LangChain)
Voice AI	Vapi (@vapi-ai/web, @vapi-ai/server-sdk)
Auth & B2B SaaS	Scalekit (SSO, OAuth, Multi-Tenant Team Invites)
Secrets Management	AWS Secrets Manager (@aws-sdk/client-secrets-manager)
Validation	Zod v3
Deployment	Docker & Docker Compose

---

🗄️ Database Schema Overview

Synora's database is managed via Drizzle ORM (db/schema.ts):

1. user — Synced user accounts.
2. metadata — Core business information and website URLs.
3. knowledge — Parent knowledge sources with processing status.
4. knowledgeChunks — Chunk-level passages, headings, FAQ pairs, token counts, tsvector search vectors, and 768-dim pgvector embeddings.
5. sections — Specialized chatbot personas with tone, allowed topics, and blocked topics.
6. chatBotMetadata — Appearance configuration, Vapi assistant/phone IDs, and auto-generated webhook_secret.
7. teamMembers — Scalekit organization member roles and invite statuses.
8. visitors — Prospects captured via chat and voice with lead scores, intent, and companies.
9. conversation — Chat and voice sessions with Vapi call IDs, AI summaries, sentiment scores, churn risks, and escalation ticket details.
10. messages — Back-and-forth conversation turn history.
11. subscriptions — Organization subscription tiers (free, pro, enterprise) and active status.
12. plugins — BYOK integrations mapped to AWS Secrets Manager.

---

🚀 Getting Started

Prerequisites

• Node.js 20+
• PostgreSQL database with pgvector enabled (e.g. Neon.tech)
• Google Gemini API Key (GOOGLE_API_KEY)
• Scalekit Credentials (SCALEKIT_ENVIRONMENT_URL, SCALEKIT_CLIENT_ID, SCALEKIT_CLIENT_SECRET)
• AWS Account Credentials (for Secrets Manager)
• Vapi Account Credentials (optional, for Voice AI)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd synora

2. Install dependencies:

   npm install

3. Configure Environment Variables: Create a .env file in the root directory:

   DATABASE_URL=postgresql://user:password@host/dbname?sslmode=require
   GOOGLE_API_KEY=your_gemini_api_key
   SCALEKIT_ENVIRONMENT_URL=https://your-org.scalekit.com
   SCALEKIT_CLIENT_ID=your_client_id
   SCALEKIT_CLIENT_SECRET=your_client_secret
   JWT_SECRET=your_jwt_secret
   NEXT_PUBLIC_URL=http://localhost:3000

4. Apply Database Migrations:

   npm run db:push

5. Start Development Server:

   npm run dev

   Open http://localhost:3000 to access the Synora dashboard.

---

🧪 Verification & Testing

Synora includes a multi-tier automated test suite:

# 1. Strict TypeScript compilation check (0 errors)
npm run typecheck

# 2. Run full 67-test Opaque-Box E2E regression suite
npx tsx scripts/run-e2e.ts

# 3. Run RAG, Context Provision & Structured Output test suite
node --env-file=.env node_modules/tsx/dist/cli.mjs scripts/test-rag-and-context.ts

---

🐳 Docker Deployment

To build and run via Docker Compose:

docker-compose up --build -d

---

🛡️ License

Licensed under the MIT License.