OS
OpenSurvey

OpenSurvey Documentation

Complete guide to the OpenSurvey platform architecture, features, and API.

Introduction

OpenSurvey is a modern, open-source survey platform designed for high-scale data collection and complex logic requirements. It bridges the gap between simple form builders and enterprise research tools, offering a developer-first approach to survey management.

High Performance

Built on Next.js 14 and Supabase for edge-ready performance.

Visual Builder

Drag-and-drop interface with real-time preview.

Enterprise Security

Row Level Security (RLS) and tenant isolation by default.

Data Ownership

Full control over your data with Postgres + Prisma.

Architecture

OpenSurvey follows a modular, monorepo-style architecture split between the Engine (Backend/Dashboard) and the Respondent functionality.

  • Engine (`/engine`): The administrative dashboard for creating surveys, managing workspaces, and viewing analytics. Authenticated via Supabase Auth + JWT.
  • Respondent View: The public-facing survey interface. Optimized for speed and mobile responsiveness.
  • API Layer (`/api`): RESTful endpoints secured by tenant-scoped middleware.

Tech Stack

Frontend

  • Next.js 14 (App Router)
  • React 18
  • Tailwind CSS
  • Framer Motion

Backend

  • Supabase (Postgres)
  • Prisma ORM
  • Next.js API Routes
  • Edge Runtime

Infrastructure

  • Vercel / Docker
  • Redis (Optional)
  • Stripe (Billing)

Logic Engine

The core of OpenSurvey is its advanced logic engine (`SurveyLogicEngine`). It handles complex branching, score calculations, and variable piping.

Display Logic

Questions can be hidden or shown based on previous answers. The engine evaluates conditions recursively. Supported operators: equals, not_equals, contains, greater_than.

Skip Logic

Define "Jump to" actions. E.g., "If Answer is Yes, Skip to Question 5". This overrides the default linear flow.

Question Types

Multiple Choice
Text Input
Matrix / Grid
Rating / NPS
File Upload
Date / Time
Dropdown
Ranking

Dynamic Variables

Pipe answers from previous questions into subsequent question titles or descriptions using the {{variable_name}} syntax. The backend automatically resolves these variables during the survey session.

// Example Variable Usage "title": "Hi {{contact_name}}, how was your visit to {{store_location}}?"

Multi-Tenancy

OpenSurvey uses a strict tenant isolation model. Each workspace is a separate tenant with its own data partition.

  • Workspace Subdomains: workspace.opensurvey.cloud routing.
  • Data Isolation: All database queries are scoped by tenantId.
  • Role-Based Access: Granular permissions for Team Members vs Admins.

Billing & Stripe Integration

Native integration with Stripe Customer Portal for subscription management. Support for tiered plans (Free, Pro, Enterprise). Webhooks automatically sync subscription status to the local database.

Start Building

Ready to deploy your first survey?