Module 6

Survey System

Purpose#

Provides a configurable form builder for collecting structured field data — from farmer baseline profiles to environmental audits. Surveys work offline on mobile; data syncs when connectivity is restored.

Completion of a Farmer Baseline survey is one of the five EUDR compliance conditions — making the survey module a direct dependency of the EUDR Compliance module.

Survey types#

→Farmer Baseline (required for EUDR compliance condition)
→Annual Household Survey
→Farm Environmental Audit
→Spot Check
→Training Needs Assessment
→Custom (any user-defined purpose)

Question types#

Type	Description
`short_text`	Single-line text input.
`long_text`	Multi-line text area.
`number`	Numeric input with optional min/max validation.
`date`	Date picker.
`single_select`	Radio group — pick one option.
`multi_select`	Checkbox group — pick multiple options.
`yes_no`	Boolean toggle.
`gps_location`	Capture GPS coordinates.
`photo`	Camera or gallery photo upload.
`signature`	Captured on mobile touchscreen.
`section_header`	Visual divider — groups questions into sections.

Conditional logic#

Questions can have show/hide rules: "show this question only if question X equals Y". Conditional logic is evaluated client-side (in the form renderer) and works fully offline.

Rules are stored as a typed ConditionalLogic object in the question definition. The form renderer evaluates all rules on every field change.

Form versioning#

Surveys follow a draft → published lifecycle. Once published, a form version is immutable — responses can no longer be modified and the question set cannot change. Any edits require creating a new draft version.

State	Behaviour
draft	Editable. Can add, remove, and reorder questions. Cannot receive responses.
published	Immutable. Responses can be submitted. Cannot be edited — create a new draft instead.
archived	No new responses. Historical data preserved.

Package	Type	Key exports
`@repo/feature-surveys`	Backend	Services: survey-form, survey-version, survey-question, survey-assignment, survey-response, survey-analytics, survey-export, survey-photo
`@repo/feature-surveys-web`	Frontend	Survey builder, form renderer, analytics view, assignment manager

API routes#

Route	Notes
/api/surveys	CRUD for survey forms.
/api/survey-versions	Manage versions (draft → publish → archive).
/api/survey-questions	CRUD for questions within a draft version.
/api/survey-assignments	Assign forms to communities or farmers.
/api/survey-responses	Submit and retrieve responses.
/api/survey-analytics	Aggregate response statistics.
/api/survey-export	Export responses as CSV.
/api/survey-photos	Presigned R2 URL for photo upload.