convez.ai
PluginAutomaçãoAvançado
PuriphatXXVII

SmartDesk AI

PuriphatXXVII/SmartDesk-AI

Chatbot RAG embarcável que responde baseado na sua documentação com fonte

Ver no GitHub
BomPluginScore · de 0 a 100

SaaS multi-tenant com chatbot alimentado por RAG que transforma documentação em agente de suporte 24/7. Oferece busca vetorial com pgvector, escalação para humanos com handoff em tempo real, citação de fontes e analytics completo, tudo embarcável com um único script tag.

Instalação

$npx convez-ai PuriphatXXVII/SmartDesk-AI

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 2 meses
Versão
—
Issues abertas
3
Contribuidores
1

Casos de uso

  • Automação de atendimento ao cliente reduzindo tickets repetitivos
  • Implementação de suporte 24/7 sem expansão de equipe
  • Integração de FAQ inteligente em websites e aplicações

Veredito

Projeto maduro e bem-arquitetado que implementa um padrão enterprise (RAG + handoff humano + analytics) com stack moderno. Código limpo com testes, CI/CD e documentação clara — viável como referência ou base para produtos similares em production.

README

A tradução para o português deste README ainda está na fila.

🤖 SmartDesk AI

Turn your documentation into a 24/7 AI support agent.

Multi-tenant SaaS — a RAG-powered support chatbot you embed with one <script> tag: real-time streaming chat, source-cited answers, live human handoff, analytics, and webhooks.

🌐 Try the live demo →

Live demo CI Security Scan Tests License: MIT

Next.js React TypeScript FastAPI PostgreSQL pgvector

🌐 Live demo · 📜 Architecture · 🗺️ Roadmap · 🔒 Security · 🚀 Deploy guide


🎯 What is this?

Businesses spend a fortune answering the same customer questions over and over — most of which are already documented somewhere. SmartDesk AI lets any business upload their docs, FAQ, or help center and instantly get an embeddable chatbot that:

  • 💬 Answers naturally using RAG (Retrieval-Augmented Generation) — grounded in the company's own content, with source citations (no hallucinated answers)
  • 👥 Escalates to a human automatically when the AI's confidence is low — and the agent replies appear in the customer's widget live
  • 📊 Surfaces top questions, satisfaction, and where the AI struggles via an analytics dashboard
  • 🔌 Fires webhooks so teams can wire alerts into Slack / LINE / their own systems

It's the kind of product Intercom Fin or Zendesk AI offer — built from scratch as a full-stack reference implementation.


✅ What's built (and working)

This is a feature-complete MVP — every capability below is implemented, wired end-to-end, and covered by a green CI pipeline (40 backend tests, lint, security scans).

AreaHighlights
Auth & tenancyClerk JWT auth · auto-provisioned orgs · strict per-org data isolation (with tests)
KnowledgeUpload PDF / DOCX / TXT / MD / HTML → parse → chunk → Voyage embeddings → pgvector
RAG engineVector similarity search + Claude answers grounded in retrieved chunks, with citations & a confidence score
Embeddable widgetOne <script> tag · vanilla TS · ~8 KB · WebSocket streaming · markdown rendering · typing indicator · per-tab history
Human handoffLow-confidence chats auto-flag · agents reply from the dashboard · replies pushed to the widget in real time
AnalyticsLive dashboard — conversations, auto-resolved %, avg confidence, satisfaction, daily trend
ConversationsFull transcript view, status filters, agent reply + resolve
WebhooksHMAC-SHA256-signed outbound events (conversation.started, message.low_confidence, conversation.handoff)
PolishLight/dark theme · bilingual UI (EN/TH) · responsive · accessible
SecurityCSP/HSTS headers · rate limiting · prompt-injection & PII guards · JWT verification (JWKS)

🚀 Live in production — frontend on Vercel, backend on Railway, Postgres + pgvector on Supabase, Redis on Upstash, auth on Clerk. Try it now →


✨ Features by audience

👩‍💼 Business owners — knowledge upload, widget customization (color/position/persona), analytics, conversations inbox, human takeover, webhook integrations.

👤 End users — embeddable streaming chat widget, source-cited answers, optional name capture, mobile-friendly, replies in the customer's own language.

🛠️ Developers — REST + WebSocket API, HMAC-signed webhooks, one-line embed snippet, fully typed codebase.


🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         End-user browser                          │
│  ┌──────────────────┐         ┌─────────────────────────────┐    │
│  │  Customer site   │ ◄────── │  SmartDesk widget (vanilla)  │   │
│  │  + one <script>  │         │  WebSocket streaming chat    │   │
│  └──────────────────┘         └──────────────┬──────────────┘    │
└────────────────────────────────────────────────┼─────────────────┘
                                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                     FastAPI backend (Python)                      │
│  ┌─────────────┐ ┌─────────────┐ ┌──────────────────────────┐    │
│  │ Auth (Clerk)│ │ WebSocket   │ │  RAG pipeline            │    │
│  │ middleware  │ │ chat + hub  │ │  1. embed query (Voyage) │    │
│  └─────────────┘ └─────────────┘ │  2. vector search        │    │
│  ┌─────────────┐ ┌─────────────┐ │  3. build cited context  │    │
│  │ Ingestion   │ │ Analytics + │ │  4. Claude (streamed)    │    │
│  │ pipeline    │ │ webhooks    │ │  5. confidence + handoff │    │
│  └─────────────┘ └─────────────┘ └──────────────────────────┘    │
└──────┬──────────────────────────────────────┬────────────────────┘
       ▼                                      ▼
┌──────────────────┐               ┌─────────────────────────────┐
│  PostgreSQL      │               │  Anthropic Claude (answers) │
│  + pgvector      │               │  + Voyage AI (embeddings)   │
└──────────────────┘               └─────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                 Next.js 16 dashboard (App Router)                 │
│   Owner/agent UI — knowledge, analytics, conversations, widget    │
└─────────────────────────────────────────────────────────────────┘

See docs/ARCHITECTURE.md for the full deep dive.


🛠️ Tech stack

LayerTechnology
FrontendNext.js 16 (App Router) · React 19 · TypeScript · Tailwind v4 · Clerk auth · TanStack Query · Zustand
WidgetVanilla TypeScript · Rollup (~8 KB bundle, zero runtime deps)
BackendFastAPI · Pydantic v2 · SQLAlchemy 2 · Alembic
DatabasePostgreSQL 16 + pgvector (in-database vector search)
AIAnthropic Claude claude-sonnet-4-6 (answers) · Voyage AI voyage-3.5-lite (multilingual embeddings)
AuthClerk (multi-tenant, OAuth, JWT/JWKS)
RealtimeWebSocket streaming + in-process pub/sub hub for agent → widget delivery
SecurityRate limiting (SlowAPI) · CSP/HSTS middleware · prompt-injection & PII guards · HMAC-signed webhooks
CI/CDGitHub Actions · Docker · Dependabot · CodeQL · Gitleaks
HostingVercel (frontend) · Railway (backend, Docker) · Supabase (Postgres + pgvector) · Upstash (Redis) · Clerk (auth)

🔒 See docs/SECURITY.md for the full threat model (STRIDE), defenses, and dependency policy.


🚀 Quick start

Option A — zero-dependency dev (no Docker, no keys)

Runs against SQLite + an in-memory rate limiter; embeddings fall back to a deterministic stub and Claude returns a canned answer — so the full UI and upload → retrieve → answer loop works with no external services.

git clone https://github.com/PuriphatXXVII/SmartDesk-AI.git
cd SmartDesk-AI

# --- Backend ---
cd backend
python -m venv .venv
.venv\Scripts\activate            # Windows  (source .venv/bin/activate on macOS/Linux)
pip install -e ".[dev]"
cp .env.example .env              # SQLite + memory:// — no Postgres needed
uvicorn app.main:app --reload

# --- Frontend (new terminal) ---
cd frontend
npm install
cp .env.example .env.local        # Clerk optional — the UI runs in "demo mode"
npm run dev

Option B — full RAG stack (Docker)

docker compose up -d postgres redis     # pgvector + Redis
cd backend && alembic upgrade head       # create tables
# add real CLERK_*, ANTHROPIC_API_KEY, and VOYAGE_API_KEY to .env, then run as above

See CONTRIBUTING.md for the full dev workflow.


🗺️ Roadmap

WeekMilestoneStatus
1Auth (Clerk), multi-tenant DB, dashboard skeleton, CI/CD✅ Done
2Knowledge ingestion: PDF/DOCX/URL → chunk → embed → pgvector✅ Done
3RAG chat with streaming + embeddable WebSocket widget✅ Done
4Conversations view + analytics dashboard (real data)✅ Done
5Human handoff · realtime agent→widget · webhooks · isolation tests✅ Done
6Production deploy — Vercel · Railway · Supabase · Upstash · Clerk (live)✅ Done

🎉 All six milestones shipped — the app is live at smart-desk-ai-lyart.vercel.app.

See docs/ROADMAP.md for week-by-week deliverables.


📁 Project structure

SmartDesk-AI/
├── frontend/          # Next.js 16 dashboard + marketing site
├── backend/           # FastAPI service (multi-tenant, RAG, WebSocket, webhooks)
├── widget/            # Embeddable vanilla-TS chat widget (~8 KB)
├── docs/              # Architecture, roadmap, security, deployment
├── .github/           # CI, security scans, Dependabot
└── docker-compose.yml # Local Postgres + pgvector + Redis

📊 Why this project

A single, cohesive system that demonstrates:

  • Full-stack ownership — frontend, backend, database, widget, and DevOps
  • Applied AI — RAG, vector search, streaming LLM responses, multilingual embeddings, grounded answers with citations
  • System design — multi-tenant SaaS, real-time WebSockets + pub/sub, background ingestion
  • Production engineering — auth, security hardening, rate limiting, CI/CD, security scanning, 40 tests
  • Product thinking — a real problem (customer support), real roles, real metrics

📝 License

MIT — see LICENSE. Vulnerability reporting in SECURITY.md.

Built by Puriphat Srikamnoi · Portfolio

Ver o original no GitHub

Bom para

Relacionados