feat(surveys): implement account setup survey functionality

- Added new database migration to create survey-related tables for storing questions and responses.
- Developed SurveyController to handle fetching and submitting survey data.
- Created survey API routes for account setup, including endpoints for retrieving the survey and submitting responses.
- Implemented frontend components for displaying the survey and capturing user responses, integrating with Redux for state management.
- Enhanced localization files to include survey-related text for multiple languages.
- Added validation middleware for survey submissions to ensure data integrity.

worklenz-backend/database/migrations/release-v2.1.4/20250724000000-add-survey-tables.sql

@@ -0,0 +1,93 @@
+-- Migration: Add survey tables for account setup questionnaire
+-- Date: 2025-07-24
+-- Description: Creates tables to store survey questions and user responses for account setup flow
+
+BEGIN;
+
+-- Create surveys table to define different types of surveys
+CREATE TABLE IF NOT EXISTS surveys (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name VARCHAR(255) NOT NULL,
+    description TEXT,
+    survey_type VARCHAR(50) DEFAULT 'account_setup' NOT NULL, -- 'account_setup', 'onboarding', 'feedback'
+    is_active BOOLEAN DEFAULT TRUE NOT NULL,
+    created_at TIMESTAMP DEFAULT now() NOT NULL,
+    updated_at TIMESTAMP DEFAULT now() NOT NULL
+);
+
+-- Create survey_questions table to store individual questions
+CREATE TABLE IF NOT EXISTS survey_questions (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    survey_id UUID REFERENCES surveys(id) ON DELETE CASCADE NOT NULL,
+    question_key VARCHAR(100) NOT NULL, -- Used for localization keys
+    question_type VARCHAR(50) NOT NULL, -- 'single_choice', 'multiple_choice', 'text'
+    is_required BOOLEAN DEFAULT FALSE NOT NULL,
+    sort_order INTEGER DEFAULT 0 NOT NULL,
+    options JSONB, -- For choice questions, store options as JSON array
+    created_at TIMESTAMP DEFAULT now() NOT NULL,
+    updated_at TIMESTAMP DEFAULT now() NOT NULL
+);
+
+-- Create survey_responses table to track user responses to surveys
+CREATE TABLE IF NOT EXISTS survey_responses (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    survey_id UUID REFERENCES surveys(id) ON DELETE CASCADE NOT NULL,
+    user_id UUID REFERENCES users(id) ON DELETE CASCADE NOT NULL,
+    is_completed BOOLEAN DEFAULT FALSE NOT NULL,
+    started_at TIMESTAMP DEFAULT now() NOT NULL,
+    completed_at TIMESTAMP,
+    created_at TIMESTAMP DEFAULT now() NOT NULL,
+    updated_at TIMESTAMP DEFAULT now() NOT NULL
+);
+
+-- Create survey_answers table to store individual question answers
+CREATE TABLE IF NOT EXISTS survey_answers (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    response_id UUID REFERENCES survey_responses(id) ON DELETE CASCADE NOT NULL,
+    question_id UUID REFERENCES survey_questions(id) ON DELETE CASCADE NOT NULL,
+    answer_text TEXT,
+    answer_json JSONB, -- For multiple choice answers stored as array
+    created_at TIMESTAMP DEFAULT now() NOT NULL,
+    updated_at TIMESTAMP DEFAULT now() NOT NULL
+);
+
+-- Add performance indexes
+CREATE INDEX IF NOT EXISTS idx_surveys_type_active ON surveys(survey_type, is_active);
+CREATE INDEX IF NOT EXISTS idx_survey_questions_survey_order ON survey_questions(survey_id, sort_order);
+CREATE INDEX IF NOT EXISTS idx_survey_responses_user_survey ON survey_responses(user_id, survey_id);
+CREATE INDEX IF NOT EXISTS idx_survey_responses_completed ON survey_responses(survey_id, is_completed);
+CREATE INDEX IF NOT EXISTS idx_survey_answers_response ON survey_answers(response_id);
+
+-- Add constraints
+ALTER TABLE survey_questions ADD CONSTRAINT survey_questions_sort_order_check CHECK (sort_order >= 0);
+ALTER TABLE survey_questions ADD CONSTRAINT survey_questions_type_check CHECK (question_type IN ('single_choice', 'multiple_choice', 'text'));
+
+-- Add unique constraint to prevent duplicate responses per user per survey
+ALTER TABLE survey_responses ADD CONSTRAINT unique_user_survey_response UNIQUE (user_id, survey_id);
+
+-- Add unique constraint to prevent duplicate answers per question per response
+ALTER TABLE survey_answers ADD CONSTRAINT unique_response_question_answer UNIQUE (response_id, question_id);
+
+-- Insert the default account setup survey
+INSERT INTO surveys (name, description, survey_type, is_active) VALUES 
+('Account Setup Survey', 'Initial questionnaire during account setup to understand user needs', 'account_setup', true)
+ON CONFLICT DO NOTHING;
+
+-- Get the survey ID for inserting questions
+DO $$
+DECLARE
+    survey_uuid UUID;
+BEGIN
+    SELECT id INTO survey_uuid FROM surveys WHERE survey_type = 'account_setup' AND name = 'Account Setup Survey' LIMIT 1;
+    
+    -- Insert survey questions
+    INSERT INTO survey_questions (survey_id, question_key, question_type, is_required, sort_order, options) VALUES
+    (survey_uuid, 'organization_type', 'single_choice', true, 1, '["freelancer", "startup", "small_medium_business", "agency", "enterprise", "other"]'),
+    (survey_uuid, 'user_role', 'single_choice', true, 2, '["founder_ceo", "project_manager", "software_developer", "designer", "operations", "other"]'),
+    (survey_uuid, 'main_use_cases', 'multiple_choice', true, 3, '["task_management", "team_collaboration", "resource_planning", "client_communication", "time_tracking", "other"]'),
+    (survey_uuid, 'previous_tools', 'text', false, 4, null),
+    (survey_uuid, 'how_heard_about', 'single_choice', false, 5, '["google_search", "twitter", "linkedin", "friend_colleague", "blog_article", "other"]')
+    ON CONFLICT DO NOTHING;
+END $$;
+
+COMMIT;

worklenz-backend/src/controllers/survey-controller.ts

@@ -0,0 +1,167 @@
+import { IWorkLenzRequest } from "../interfaces/worklenz-request";
+import { IWorkLenzResponse } from "../interfaces/worklenz-response";
+import { ServerResponse } from "../models/server-response";
+import WorklenzControllerBase from "./worklenz-controller-base";
+import HandleExceptions from "../decorators/handle-exceptions";
+import { ISurveySubmissionRequest } from "../interfaces/survey";
+import db from "../config/db";
+
+export default class SurveyController extends WorklenzControllerBase {
+  @HandleExceptions()
+  public static async getAccountSetupSurvey(req: IWorkLenzRequest, res: IWorkLenzResponse): Promise<IWorkLenzResponse> {
+    const q = `
+      SELECT 
+        s.id,
+        s.name,
+        s.description,
+        s.survey_type,
+        s.is_active,
+        COALESCE(
+          json_agg(
+            json_build_object(
+              'id', sq.id,
+              'survey_id', sq.survey_id,
+              'question_key', sq.question_key,
+              'question_type', sq.question_type,
+              'is_required', sq.is_required,
+              'sort_order', sq.sort_order,
+              'options', sq.options
+            ) ORDER BY sq.sort_order
+          ) FILTER (WHERE sq.id IS NOT NULL), 
+          '[]'
+        ) AS questions
+      FROM surveys s
+      LEFT JOIN survey_questions sq ON s.id = sq.survey_id
+      WHERE s.survey_type = 'account_setup' AND s.is_active = true
+      GROUP BY s.id, s.name, s.description, s.survey_type, s.is_active
+      LIMIT 1;
+    `;
+
+    const result = await db.query(q);
+    const [survey] = result.rows;
+
+    if (!survey) {
+      return res.status(200).send(new ServerResponse(false, null, "Account setup survey not found"));
+    }
+
+    return res.status(200).send(new ServerResponse(true, survey));
+  }
+
+  @HandleExceptions()
+  public static async submitSurveyResponse(req: IWorkLenzRequest, res: IWorkLenzResponse): Promise<IWorkLenzResponse> {
+    const userId = req.user?.id;
+    const body = req.body as ISurveySubmissionRequest;
+
+    if (!userId) {
+      return res.status(200).send(new ServerResponse(false, null, "User not authenticated"));
+    }
+
+    if (!body.survey_id || !body.answers || !Array.isArray(body.answers)) {
+      return res.status(200).send(new ServerResponse(false, null, "Invalid survey submission data"));
+    }
+
+    // Check if user has already submitted a response for this survey
+    const existingResponseQuery = `
+      SELECT id FROM survey_responses 
+      WHERE user_id = $1 AND survey_id = $2;
+    `;
+    const existingResult = await db.query(existingResponseQuery, [userId, body.survey_id]);
+
+    let responseId: string;
+
+    if (existingResult.rows.length > 0) {
+      // Update existing response
+      responseId = existingResult.rows[0].id;
+      
+      const updateResponseQuery = `
+        UPDATE survey_responses 
+        SET is_completed = true, completed_at = NOW(), updated_at = NOW()
+        WHERE id = $1;
+      `;
+      await db.query(updateResponseQuery, [responseId]);
+
+      // Delete existing answers
+      const deleteAnswersQuery = `DELETE FROM survey_answers WHERE response_id = $1;`;
+      await db.query(deleteAnswersQuery, [responseId]);
+    } else {
+      // Create new response
+      const createResponseQuery = `
+        INSERT INTO survey_responses (survey_id, user_id, is_completed, completed_at)
+        VALUES ($1, $2, true, NOW())
+        RETURNING id;
+      `;
+      const responseResult = await db.query(createResponseQuery, [body.survey_id, userId]);
+      responseId = responseResult.rows[0].id;
+    }
+
+    // Insert new answers
+    if (body.answers.length > 0) {
+      const answerValues: string[] = [];
+      const params: any[] = [];
+      
+      body.answers.forEach((answer, index) => {
+        const baseIndex = index * 4;
+        answerValues.push(`($${baseIndex + 1}, $${baseIndex + 2}, $${baseIndex + 3}, $${baseIndex + 4})`);
+        
+        params.push(
+          responseId,
+          answer.question_id,
+          answer.answer_text || null,
+          answer.answer_json ? JSON.stringify(answer.answer_json) : null
+        );
+      });
+
+      const insertAnswersQuery = `
+        INSERT INTO survey_answers (response_id, question_id, answer_text, answer_json)
+        VALUES ${answerValues.join(', ')};
+      `;
+
+      await db.query(insertAnswersQuery, params);
+    }
+
+    return res.status(200).send(new ServerResponse(true, { response_id: responseId }));
+  }
+
+  @HandleExceptions()
+  public static async getUserSurveyResponse(req: IWorkLenzRequest, res: IWorkLenzResponse): Promise<IWorkLenzResponse> {
+    const userId = req.user?.id;
+    const surveyId = req.params.survey_id;
+
+    if (!userId) {
+      return res.status(200).send(new ServerResponse(false, null, "User not authenticated"));
+    }
+
+    const q = `
+      SELECT 
+        sr.id,
+        sr.survey_id,
+        sr.user_id,
+        sr.is_completed,
+        sr.started_at,
+        sr.completed_at,
+        COALESCE(
+          json_agg(
+            json_build_object(
+              'question_id', sa.question_id,
+              'answer_text', sa.answer_text,
+              'answer_json', sa.answer_json
+            )
+          ) FILTER (WHERE sa.id IS NOT NULL),
+          '[]'
+        ) AS answers
+      FROM survey_responses sr
+      LEFT JOIN survey_answers sa ON sr.id = sa.response_id
+      WHERE sr.user_id = $1 AND sr.survey_id = $2
+      GROUP BY sr.id, sr.survey_id, sr.user_id, sr.is_completed, sr.started_at, sr.completed_at;
+    `;
+
+    const result = await db.query(q, [userId, surveyId]);
+    const [response] = result.rows;
+
+    if (!response) {
+      return res.status(200).send(new ServerResponse(false, null, "Survey response not found"));
+    }
+
+    return res.status(200).send(new ServerResponse(true, response));
+  }
+}

worklenz-backend/src/interfaces/survey.ts

@@ -0,0 +1,37 @@
+export interface ISurveyQuestion {
+  id: string;
+  survey_id: string;
+  question_key: string;
+  question_type: 'single_choice' | 'multiple_choice' | 'text';
+  is_required: boolean;
+  sort_order: number;
+  options?: string[];
+}
+
+export interface ISurvey {
+  id: string;
+  name: string;
+  description?: string;
+  survey_type: 'account_setup' | 'onboarding' | 'feedback';
+  is_active: boolean;
+  questions?: ISurveyQuestion[];
+}
+
+export interface ISurveyAnswer {
+  question_id: string;
+  answer_text?: string;
+  answer_json?: string[];
+}
+
+export interface ISurveyResponse {
+  id?: string;
+  survey_id: string;
+  user_id?: string;
+  is_completed: boolean;
+  answers: ISurveyAnswer[];
+}
+
+export interface ISurveySubmissionRequest {
+  survey_id: string;
+  answers: ISurveyAnswer[];
+}

worklenz-backend/src/middlewares/validators/survey-submission-validator.ts

@@ -0,0 +1,56 @@
+import { NextFunction } from "express";
+import { IWorkLenzRequest } from "../../interfaces/worklenz-request";
+import { IWorkLenzResponse } from "../../interfaces/worklenz-response";
+import { ServerResponse } from "../../models/server-response";
+import { ISurveySubmissionRequest } from "../../interfaces/survey";
+
+export default function surveySubmissionValidator(req: IWorkLenzRequest, res: IWorkLenzResponse, next: NextFunction): IWorkLenzResponse | void {
+  const body = req.body as ISurveySubmissionRequest;
+
+  if (!body) {
+    return res.status(200).send(new ServerResponse(false, null, "Request body is required"));
+  }
+
+  if (!body.survey_id || typeof body.survey_id !== 'string') {
+    return res.status(200).send(new ServerResponse(false, null, "Survey ID is required and must be a string"));
+  }
+
+  if (!body.answers || !Array.isArray(body.answers)) {
+    return res.status(200).send(new ServerResponse(false, null, "Answers are required and must be an array"));
+  }
+
+  // Validate each answer
+  for (let i = 0; i < body.answers.length; i++) {
+    const answer = body.answers[i];
+    
+    if (!answer.question_id || typeof answer.question_id !== 'string') {
+      return res.status(200).send(new ServerResponse(false, null, `Answer ${i + 1}: Question ID is required and must be a string`));
+    }
+
+    // At least one of answer_text or answer_json should be provided
+    if (!answer.answer_text && !answer.answer_json) {
+      return res.status(200).send(new ServerResponse(false, null, `Answer ${i + 1}: Either answer_text or answer_json is required`));
+    }
+
+    // Validate answer_text if provided
+    if (answer.answer_text && typeof answer.answer_text !== 'string') {
+      return res.status(200).send(new ServerResponse(false, null, `Answer ${i + 1}: answer_text must be a string`));
+    }
+
+    // Validate answer_json if provided
+    if (answer.answer_json && !Array.isArray(answer.answer_json)) {
+      return res.status(200).send(new ServerResponse(false, null, `Answer ${i + 1}: answer_json must be an array`));
+    }
+
+    // Validate answer_json items are strings
+    if (answer.answer_json) {
+      for (let j = 0; j < answer.answer_json.length; j++) {
+        if (typeof answer.answer_json[j] !== 'string') {
+          return res.status(200).send(new ServerResponse(false, null, `Answer ${i + 1}: answer_json items must be strings`));
+        }
+      }
+    }
+  }
+
+  return next();
+}

worklenz-backend/src/routes/apis/index.ts

@@ -51,13 +51,14 @@ import roadmapApiRouter from "./gannt-apis/roadmap-api-router";
 import scheduleApiRouter from "./gannt-apis/schedule-api-router";
 import scheduleApiV2Router from "./gannt-apis/schedule-api-v2-router";
 import projectManagerApiRouter from "./project-managers-api-router";
+import surveyApiRouter from "./survey-api-router";
 
 import billingApiRouter from "./billing-api-router";
 import taskDependenciesApiRouter from "./task-dependencies-api-router";
 
 import taskRecurringApiRouter from "./task-recurring-api-router";
-
-import customColumnsApiRouter from "./custom-columns-api-router";
+
+import customColumnsApiRouter from "./custom-columns-api-router";
 
 const api = express.Router();
 
@@ -103,6 +104,7 @@ api.use("/roadmap-gannt", roadmapApiRouter);
 api.use("/roadmap-gannt", roadmapApiRouter);
 api.use("/schedule-gannt", scheduleApiRouter);
 api.use("/schedule-gannt-v2", scheduleApiV2Router);
+api.use("/project-managers", projectManagerApiRouter);
 api.use("/surveys", surveyApiRouter);
 
 api.get("/overview/:id", safeControllerFunction(OverviewController.getById));
@@ -115,6 +117,6 @@ api.use("/task-dependencies", taskDependenciesApiRouter);
 api.use("/task-dependencies", taskDependenciesApiRouter);
 
 api.use("/task-recurring", taskRecurringApiRouter);
-
-api.use("/custom-columns", customColumnsApiRouter);
+
+api.use("/custom-columns", customColumnsApiRouter);
 

worklenz-backend/src/routes/apis/survey-api-router.ts

@@ -0,0 +1,17 @@
+import express from "express";
+import SurveyController from "../../controllers/survey-controller";
+import surveySubmissionValidator from "../../middlewares/validators/survey-submission-validator";
+import safeControllerFunction from "../../shared/safe-controller-function";
+
+const surveyApiRouter = express.Router();
+
+// Get account setup survey with questions
+surveyApiRouter.get("/account-setup", safeControllerFunction(SurveyController.getAccountSetupSurvey));
+
+// Submit survey response
+surveyApiRouter.post("/responses", surveySubmissionValidator, safeControllerFunction(SurveyController.submitSurveyResponse));
+
+// Get user's survey response for a specific survey
+surveyApiRouter.get("/responses/:survey_id", safeControllerFunction(SurveyController.getUserSurveyResponse));
+
+export default surveyApiRouter;