Skip to content
A
AskGPT
Docs/how it works

How it works (complete reference)

A full, technical walkthrough of the AskGPT platform — every major subsystem and exactly how it works, end to end.

Architecture at a glance

AskGPT is a Next.js 14 (App Router) application backed by four data services. The app handles the dashboard, public marketing pages, the embeddable widget, and all API routes.

  • →Next.js 14 + TypeScript — SSR, API routes, edge middleware
  • →MongoDB (Mongoose) — users, chatbots, conversations, appointments, complaints, rate-limit state
  • →Qdrant — vector search over embeddings (one collection per chatbot: chatbot_{id})
  • →Gemini (primary) + OpenAI (fallback) — embeddings and chat generation
  • →Stripe — subscriptions and credit packs; AWS S3 / MinIO — file storage; Brevo SMTP — email; Web Push (VAPID); Sentry — errors
Visitor ─▶ widget.js ─▶ /api/chatbots/{id}/chat (SSE) │ Mongo ◀── conversation ──────┤ Qdrant ◀── vector search ────┤ Gemini/OpenAI ◀── generate ──┘

Training pipeline (crawl → embed → index)

When you create a chatbot from a URL, an SSRF-hardened crawler discovers pages from the sitemap, extracts and chunks text, embeds each chunk, and stores the vectors in Qdrant plus the raw chunks in MongoDB.

URL ▶ sitemap discovery ▶ fetch pages (protocol+DNS+IP guarded) ▶ strip HTML ▶ chunk (~700 chars, 100 overlap) ▶ embed each chunk (gemini-embedding-001, 3072-dim) ▶ upsert to Qdrant + save KnowledgeChunk to Mongo ▶ status: ready
💡Training costs 10 credits per crawl job + 1 credit per chunk embedded. Re-training wipes old vectors/chunks before writing new ones.

Chat & retrieval (RAG)

Every visitor message runs the same retrieval-augmented flow. History is rebuilt from the server-side conversation record — the client-supplied history is ignored to prevent prompt-injection via forged turns.

POST /api/chatbots/{id}/chat 1. rate-limit (30/min per widget+IP) 2. reserve 1 credit atomically (gate: credits >= -50) 3. embed the message ▶ Qdrant top-6 (cosine >= 0.5) 4. build context + website hint + indexed-page list 5. (optional) one tool-calling round — actions/appointments 6. stream reply over SSE (Gemini/OpenAI) 7. save conversation + analytics; refund credit if aborted/errored 8. auto-flag a complaint if unresolved / customer unhappy
💡Knowledge-base text is wrapped in strict delimiters and 'defused' so scraped content can't act as instructions to the model.

Credits & billing

Credits are the platform's unit of usage, decremented from the chatbot owner's balance per AI action.

  • →Chat reply — 1 credit (reserved atomically, refunded on failure)
  • →Embedding — 1 credit; Site analysis — 10; FAQ generation — 5
  • →Overdraft floor: requests are allowed until the balance is below -50, then rejected with 402
  • →Stripe webhooks (idempotent) activate plans, add credit packs, and replenish monthly credits

AI Actions (Functions)

Actions let the assistant call your own REST API mid-conversation. You configure a base URL + auth header and define actions (name, description, path, method, parameters). During chat the model decides whether to call one.

  • →Single tool-calling round per message (Gemini function-calling / OpenAI tools)
  • →SSRF-hardened: host locked to your base URL, public HTTPS only, no redirects, 8s timeout
  • →Triggers: always / on user request / after lead captured / on human handoff
POST {baseUrl}{path} { "action": "<name>", "params": { ...AI args }, "session": { "visitorId", "lead" } }

Appointments (built-in scheduler)

Set weekly availability (timezone, slot length, lead time, window). The assistant offers free slots and books them via built-in actions, with confirmation emails to both sides.

  • →get_available_slots / book_appointment are offered as tools when booking is enabled
  • →Slots computed in your timezone, minus already-booked times; a unique index prevents double-booking
  • →Google Calendar two-way sync is on the roadmap

FAQs

Generate FAQ drafts from the indexed knowledge base, edit them, and promote the good ones into training.

  • →Generate reads real KnowledgeChunk content and drafts Q&A pairs
  • →Promote embeds the Q&A and upserts it into Qdrant, so it's retrieved during chat like crawled content
  • →Editing a promoted FAQ re-embeds it; removing/deleting takes it out of retrieval

Conversations & complaints

Every chat is stored and viewable in the Conversations tab with full history, lead details, IP/country, AI summary, tags, and sentiment.

  • →Email the full transcript to the customer; add admin-only internal notes (never seen by the AI/customer)
  • →Complaints auto-open when the bot couldn't answer or the customer sounded unhappy
  • →Complaints are managed on the Support page and notify the owner by email + push

Security & safety

Security is enforced across the stack.

  • →Auth — NextAuth session cookies + custom Bearer JWT, verified at the edge middleware; per-route tenant isolation
  • →Distributed rate limiting & login lockout — shared MongoDB TTL store (holds across replicas)
  • →SSRF hardening — crawler and action calls block private/loopback/internal IPs
  • →CSP with per-request nonce; per-chatbot CORS allowlist for the widget
  • →Secrets (2FA, Odoo credentials, action secrets) encrypted at rest (AES-256-GCM)
  • →Prompt-injection defenses — delimiter defusing + server-authoritative history
Account setup

Need more help?

Contact support and we'll get back to you within 24 hours.