NexaSupport AI

NexaSupport AI is a multi-tenant customer support SaaS foundation with a Next.js dashboard, Express REST API, Socket.IO messaging, Prisma/PostgreSQL data model, Redis-ready infrastructure, RBAC, knowledge-base retrieval hooks, AI provider abstraction, and an embeddable chat widget.

Development demo credentials:

• Email: owner@nexasupport.dev
• Password: Password123!
• These credentials are development-only seed data.

Features

• Organization onboarding and owner registration API structure
• Role-based access control for OWNER, ADMIN, AGENT, and VIEWER
• Dashboard shell with overview, inbox, tickets, customers, knowledge base, analytics, team, automations, integrations, and settings
• Live inbox UI with AI-labeled messages, internal-note composer, customer profile, and handoff reason
• Socket.IO event handlers for conversation rooms, typing, and new messages
• Embeddable Shadow DOM widget at /widget.js and demo at /widget-demo
• Mock AI provider fallback when OPENAI_API_KEY is missing
• Prisma schema covering the requested production entities and tenant indexes
• Docker Compose for web, API, PostgreSQL, and Redis
• Supertest/Vitest coverage for auth and mock AI behavior

Screenshots

Landing Page

Dashboard Overview

Live Inbox

Architecture

flowchart LR
  Customer[Customer website] --> Widget[Shadow DOM widget]
  Widget --> API[Express API]
  Agent[Support dashboard] --> Web[Next.js app]
  Web --> API
  Web <--> Socket[Socket.IO]
  Widget <--> Socket
  API --> Prisma[Prisma ORM]
  Prisma --> Postgres[(PostgreSQL)]
  API --> Redis[(Redis)]
  API --> AI[AI provider]
  AI --> KB[Knowledge base retrieval]

Loading

Message Flow

sequenceDiagram
  participant C as Customer
  participant W as Widget
  participant A as API
  participant S as Socket.IO
  participant D as Dashboard
  C->>W: Sends message
  W->>A: POST /api/v1/conversations
  A->>S: Emits conversation:created
  S->>D: Updates inbox
  D->>S: message:send
  S->>W: message:new

Loading

AI Retrieval Flow

flowchart TD
  Q[Customer question] --> R[Retrieve org-scoped KB articles]
  R --> P[Build prompt with tenant context]
  P --> M{OPENAI_API_KEY?}
  M -->|Yes| O[OpenAIProvider]
  M -->|No| Mock[MockAIProvider]
  O --> G[Reply + confidence]
  Mock --> G
  G --> H{Confidence below threshold?}
  H -->|Yes| Hand[Human handoff]
  H -->|No| Send[Send AI answer]

Loading

Human Handoff

flowchart LR
  Trigger[Low confidence, negative sentiment, urgent keyword, or human request] --> Stop[Stop AI auto-response]
  Stop --> Mark[Mark waiting for agent]
  Mark --> Notify[Notify available agents]
  Notify --> Assign[Round-robin or manual assignment]
  Assign --> Summary[Show AI summary and reason]

Loading

Tech Stack

• Web: Next.js App Router, TypeScript, Tailwind CSS, React Hook Form, Zod, TanStack Query, Recharts, Lucide React
• API: Node.js, Express, TypeScript, REST, Socket.IO, Zod, Pino, Helmet, rate limiting
• Data: PostgreSQL, Prisma ORM, Redis
• AI: AIProvider interface with MockAIProvider and OpenAIProvider structure
• Tests: Vitest and Supertest
• Infra: Docker Compose and GitHub Actions

Local Setup

cp .env.example .env
npm install
npm run db:generate
npm run typecheck
npm test
npm run dev

Open:

• Web: http://localhost:3000 or http://localhost:3001 if port 3000 is already in use
• API health: http://localhost:4000/api/v1/health
• API docs: http://localhost:4000/docs
• Widget demo: http://localhost:3000/widget-demo

Docker Setup

cp .env.example .env
docker compose up --build

Run migrations/seeding locally after Postgres is available:

npm run db:push
npm run db:seed

Environment Variables

See .env.example for DATABASE_URL, REDIS_URL, JWT secrets, OpenAI settings, web/API URLs, upload provider, S3, and SMTP fields.

Folder Structure

apps/web        Next.js dashboard, public help center, widget demo
apps/api        Express API, services, routes, middleware, socket handlers
packages/shared Shared schemas, roles, permissions, API contracts
packages/ui     Shared React primitives
prisma          Database schema and seed script
docker          Production Dockerfiles
docs            Socket and API documentation

Current Phase Status

Phase 1 is implemented with a runnable monorepo foundation, health endpoint, Docker Compose, base frontend, API structure, Socket.IO, Prisma schema, seed script, CI, and initial tests.

The remaining phases should deepen persistence-backed implementations for every UI workflow: onboarding, full conversation repositories, widget sessions, ticket lifecycle, KB editor/search, OpenAI calls, analytics queries, team management, automations, file upload storage, and Playwright E2E.

Security Notes

• Backend permission middleware validates protected actions.
• Tenant-owned Prisma models include organizationId and useful compound indexes.
• JWT secrets are required for production.
• Helmet, CORS, JSON size limits, rate limiting, and structured errors are enabled.
• The API must derive tenant access from authenticated membership when persistence-backed repositories are expanded.

License

MIT