Encuestum documentation

Encuestum is a multi-tenant survey and assessment platform. A creator builds a form in the visual editor, distributes it with the access model they need, and reads the results — while AI optionally generates the questions and grades the open answers. Everything runs on your server, against your own AI key.

The editor and question types

The visual editor is drag-and-drop with live preview and ready-made templates (NPS, feedback, event sign-up, course evaluation, quiz…). It autosaves as you go, so you never lose work.

There are 14 question types:

• Text, paragraph, email
• Single / multiple choice, dropdown
• Scale / NPS with 6 presentations (numbers, rectangles, color gradient, stars, smileys, colored smileys)
• Yes / no, image-choice, matrix (grid), ranking
• Date, file upload, and video answer (webcam recording, Typeform-style)

Group questions into sections (Google-Forms-style pages or Typeform-style covers), and drive the flow with conditional logic (show based on another answer), branching / skip (jump to a section or finish based on an answer) and piping ({question} inside the text).

AI: generate and grade (bring-your-own-key)

Encuestum does not ship an AI key — you use your own. It is provider-agnostic: any OpenAI-compatible endpoint (OpenRouter, OpenAI, Together, a local LLM…).

Generate questions

Produce a set of questions from a topic, or from a document / markdown you paste or upload.

Grade open answers

A hybrid engine — deterministic rubric + LLM — returns score, verdict, feedback, cited evidence, needs_review and injection_flag, with a double pass.

Provider management

Add AI providers (OpenAI / OpenRouter / custom endpoint) per organization or globally, list models live, and track consumption (tokens and approx. cost) per call.

Works without a key

Everything else keeps running, including deterministic grading of closed questions. Only LLM rubric grading, insights and question generation go inactive.

Local LLM (Ollama)

Point ENCUESTUM_LLM_BASE_URL at http://localhost:11434/v1 and set ENCUESTUM_ALLOW_PRIVATE_OUTBOUND=true to grade with a model on your own machine.

Distribution and access control

Each survey gets a public page at /s/{slug} (SurveyJS in the browser) with an editable custom link, a QR code, iframe embed, prefill links (?field=value) and save-and-resume.

There are 3 access modes per survey:

Mode	Who can answer	Notes
Public	Anyone with the link	Optional proof-of-work captcha against bots.
PIN	Anyone with the shared code	A single passphrase gates the survey.
Allow-list	Emails you admit	Each person gets a unique code (to enter and to view their result) and a magic link by email.

Scheduling: set an open and a close date/time (in the server timezone, ENCUESTUM_TIMEZONE) or a response quota; before opening the survey cannot be answered, and you can reopen a closed one with one click. An optional, self-hosted proof-of-work captcha (no third parties, no keys, invisible to the respondent) stops response spam on public surveys.

Custom status screens: the “analyzing” screen (while the AI grades) and the “closed” screen are fully customizable — title, message, emoji, background image or color, text color and spinner. No blank pages.

Design in another league

A design panel gives you one-click themes (light and dark), survey dark mode, a Google Fonts picker, accent / background / text colors, glass cards (color + opacity + blur), per-question containers, screen transitions (fade, slide, zoom, flip, blur), alignment, button color and shadow, images (cover, logo, background with opacity, per-question), embedded video and background music — plus per-question styling (individual transparency and alignment).

Conversational (chat) mode

A Typebot-style chat engine over the same render: one question at a time, answers as quick-reply chips, a “typing…” indicator, auto-advance and bubbles. It comes with 9 one-click skins (Encuestum, WhatsApp, Telegram, iMessage, Messenger, Slack, Discord, Terminal, Minimal) and a configurable bot identity (avatar + name + status).

The thank-you screen is fully customizable too: confetti, chosen icon/emoji/image, layouts (card / minimal / hero), your own colors, tokens (Thanks, {name}!), CTA buttons, social share (WhatsApp / X / LinkedIn) and a countdown redirect — and in chat mode, it closes as the bot’s last bubble.

Exams and education

Exam mode with integrity controls: shuffle questions and options, time limit and attempts. Add a review queue with manual override, a gradebook (per-student grade sheet) and a printable certificate on pass.

Results and analytics

• A Summary panel with per-question charts (bars, NPS histogram with average, open answers, files / videos).
• A conversion funnel: views → started → completed, showing where people drop off.
• CSV / Excel export, survey duplication, email notifications on new responses, HMAC-signed webhooks for Zapier / Google Sheets / Make, and per-response deletion (GDPR).

The platform

Encuestum is multi-tenant: organizations with owner / admin / member roles, invitations, password reset and email verification. Each organization can claim its own subdomain (acme.yourdomain.com) with branding, there is a super-admin panel, and the interface ships in 7 languages (English, Español, Français, Português, Italiano, 中文, 日本語).

File uploads (videos, attachments) can go directly to Cloudflare R2 / S3 with a presigned URL — the browser uploads straight to the bucket and the server never buffers the large file. To view them, the app streams them same-origin (with Range support for video seeking): the bucket stays private, its path never reaches the browser, and response files are visible only to members of the organization.

Multi-tenant hardening

Keep ENCUESTUM_ALLOW_PRIVATE_OUTBOUND=false on a shared, multi-tenant deployment so webhooks and LLM base URLs cannot reach internal IPs. Set ENCUESTUM_TRUST_PROXY=true only when you are actually behind your own proxy, so rate limiting reads the real client IP.

Architecture

Encuestum is a FastAPI + SQLModel + Alembic backend (SQLite by default, or Postgres) and a Next.js 16 (App Router) + SurveyJS + Tailwind frontend, packaged as a single all-in-one image (nginx + Next + FastAPI). The backend grades with a hybrid engine (grading.py), talks to any OpenAI-compatible provider (llm.py), guards against SSRF on webhooks and LLM URLs (net_guard.py), and stores assets locally or on R2/S3 with presigned URLs (storage.py). Sessions are signed JWTs in httpOnly cookies; passwords use bcrypt; multi-tenant isolation is test-verified against cross-organization IDOR.