Full-stack FAQ portal with semantic vector search, AI-powered community moderation, and an expert promotion layer. Built to handle 1 million registered users.
GitHub: https://github.com/vicharanashala/crowd-source-faq
Full reference: docs/ · Contributing · Code of Conduct · License
Automate the FAQ lifecycle end-to-end. Zero people in the loop. Reduce the operational FAQ culture.
Every question a user has has been asked before — and most will be asked again. The right answer should be there before the user finishes typing. The platform achieves this through four zero-touch pillars:
The platform is the operator. People handle exceptions, not the steady state.
Samagama (internally “Yaksha FAQ Portal”) turns an organisation’s accumulated conversations into a searchable, self-maintaining FAQ. It combines hybrid vector + keyword search with a community Q&A board and a fully automated ingestion pipeline that pulls transcripts from Zoom, extracts Q&A with AI, and indexes them for retrieval in seconds.
Built for organisations whose community generates more questions than a human team can answer — student cohorts, open-source projects, internal forums, customer-success communities. Target scale: 1 million registered users with constant conversational input.
See docs/ARCHITECTURE.md for the architecture deep-dive and docs/PIPELINES.md for pipeline internals.
| Layer | Technologies |
|---|---|
| Frontend | React 18, Vite, TypeScript, Tailwind CSS, Framer Motion, Axios, Recharts, React Router 6, Vitest |
| Backend | Node.js, Express 4, TypeScript (ESM), Mongoose 8, JWT, bcryptjs, Helmet, CORS, Morgan, Multer, Zod, express-rate-limit, dotenv, OpenAI SDK, Vitest |
| Database & Storage | MongoDB Atlas (with Vector Search), Upstash Redis (optional), LRU cache, Cloudinary |
| Search & AI | Xenova/transformers (768-dim local embeddings), Atlas Vector Search, $text search, Reciprocal Rank Fusion |
| AI Providers | Anthropic, OpenAI, XAI, MiniMax (per-pipeline configurable) |
| DevOps | Sentry, Ngrok (local webhook tunnel), Twilio (SMS), SMTP, Vitest |
./run.sh # Full-stack runner: env setup, ngrok, backend + frontend
run.sh prompts for MONGODB_URI and JWT_SECRET on first run, then saves them to apps/backend/.env.local. The script will not overwrite existing values. Session logs are written to logs/session_*.txt.
Eight flagship capabilities define this platform:
ZoomInsight (admin-reviewed) and TranscriptKnowledge (auto-approved, immediately vector-searchable). Includes retry + dead-letter queue for failed meetings and admin backfill for historical meetings. See docs/PIPELINES.md#4-zoom-ingestion-pipeline.correct (≥0.80), drift_detected (0.60–0.79), contradiction (<0.60), or stale. Flagged FAQs land in /admin/faqs/review with reviewStatus='pending_review', flagType='auto', and an incremented reviewCycle. See docs/PIPELINES.md#2-faq-audit-pipeline.freshness_tier (evergreen / seasonal / volatile) and a per-tier review interval. A daily cron auto-flags FAQs whose last-verified date exceeds the interval, opening a peer-review window on /admin/faqs/review. Anyone can vote still_accurate / needs_update; the threshold auto-verifies, otherwise it escalates to a moderator. FreshnessBadge on the public FAQ card surfaces verified-vs-under-review status. See docs/PIPELINES.md#7-faq-freshness-pipeline./golden) sorted by SP spend, anonymous to non-admin viewers. Toggleable from /admin/features.Batch (cohort, term, program). A first-class Category model replaces the old free-text field. Guests land on /explore/select to pick a batch, then browse the public FAQ at /faq with no account required. Admin can create/archive batches and promote FAQs between them. See docs/BATCH_MANAGEMENT_PLAN.md.internet, camera, microphone, device, power, other) has an admin-editable schema of context fields (text, textarea, number, date, boolean, dropdown). Admins add, edit, reorder, or archive fields from /admin/support/categories without redeploying. The frontend renders dynamic inputs from the live schema. See docs/SCHEMA_DRIVEN_CONTEXT_PLAN.md.isDeleted=true, deletedAt timestamp, name becomes Deleted User, email is rewritten to a non-routable placeholder, password is replaced with a random UUID to break login. All posts, comments, votes, reputation logs, and audit trail entries remain intact — preserving referential integrity, attribution history, and regulatory compliance.Other capabilities: semantic hybrid search, community Q&A board, reputation system + badges + leaderboard, SpillTheTea event-driven notifications, per-user Zoom OAuth, RAG-powered /ask-ai assistant with image + file attachments, soft user lifecycle, experimental feature flags, support tickets (troubleshoot → admin triage → resolution).
The admin panel at /admin (mounted at /api/admin/*) provides telemetry, moderation, and operational control. Key areas:
ModerationLog; every reputation change (+2 upvote, +5 accepted answer, -2/-5 on removal) recorded in ReputationLogPipelineResult collection (30-day TTL) for both auto-answer and audit outcomes; Zoom health endpoint reports OAuth/API circuit state, cache hit rate, failing-meetings count, dead-letter count, pending-retry count; Prometheus metrics at /api/metrics (search latency, cache hits, RAG duration, queue depth)For the full admin route map and per-page behaviour, see docs/ARCHITECTURE.md.
The user-facing app (/, /faq, /community, /saved, /account, /leaderboard) gives authenticated users full participation in the knowledge loop:
/api/search (public), semantic suggestions at /api/search/suggest, category browsing/saved, nested comment threads with optimistic UI, accept-answer (locks verified/expert comments from edit), edit/delete own comments, share via clipboard, report and flag-outdatedpost_answered, post_deleted, etc.), per-event-type settings, email + SMS delivery/ask-ai (5/day anonymous quota via localStorage, unlimited for authenticated users), sources cited, accepts file and image attachments (max 4 files, 10 MB each) — images sent as vision input, text files inlined into the prompt/account, manual .vtt / .txt / raw-text upload, last-synced status card, no admin requiredFor per-route behaviour and field schemas, see docs/ARCHITECTURE.md.
Crowd Source FAQ/
├── apps/
│ ├── backend/ # Express + TypeScript API
│ └── frontend/ # React + Vite SPA
├── docs/ # Full documentation
└── run.sh # Local dev runner (env setup, ngrok, backend + frontend)
Required: MONGODB_URI, JWT_SECRET
Optional: at least one AI provider key (ANTHROPIC_API_KEY / OPENAI_API_KEY / XAI_API_KEY / MINIMAX_API_KEY), Zoom OAuth credentials, CLOUDINARY_*, SENTRY_DSN, Twilio + SMTP for notifications, UPSTASH_REDIS_*
See docs/ARCHITECTURE.md#10-env-variables-reference for the full list.
MIT © 2026 vicharanashala