# Overview (https://survey.dimah.dev/docs)



dimah-survey adds a server-owned lifecycle around
[SurveyJS](https://surveyjs.io/) JSON. It publishes survey definitions, creates
durable response drafts, and validates each submission against the exact
definition that response started with.

It does not replace SurveyJS. Your application still owns the renderer,
Creator, authentication, database migrations, and UI.

<Callout>
  The central guarantee is simple: publishing a new survey never changes an
  existing `response.definition`.
</Callout>

## The lifecycle [#the-lifecycle]

<Flow
  label="One response"
  steps="[
  { name: &#x22;Author&#x22;, kind: &#x22;data&#x22;, note: &#x22;Creator writes draftJson&#x22; },
  { name: &#x22;Publish&#x22;, kind: &#x22;server&#x22;, note: &#x22;Promote publishedJson&#x22; },
  { name: &#x22;Start&#x22;, kind: &#x22;server&#x22;, note: &#x22;Freeze response.definition&#x22; },
  { name: &#x22;Fill&#x22;, kind: &#x22;client&#x22;, note: &#x22;SurveyJS renders the snapshot&#x22; },
  { name: &#x22;Submit&#x22;, kind: &#x22;server&#x22;, note: &#x22;Validate the same snapshot&#x22; },
]"
/>

`draftJson` is the editable document. `publishedJson` is the document new
responses may start. At start, the server copies `publishedJson` into
`response.definition`; every save and submit stays attached to that copy.

## Clear ownership [#clear-ownership]

| Owner            | Responsibilities                                                              |
| ---------------- | ----------------------------------------------------------------------------- |
| SurveyJS         | Survey schema, `Model`, `<Survey>`, Creator, and question behavior            |
| Your application | Authentication, authorization, migrations, file storage, and UI               |
| dimah-survey     | Publish, collection policy, response snapshots, drafts, and submit validation |

The backend exposes two isolated audiences over one shared `SurveyStore`:

| Audience | Intended caller          | Capabilities                                                                |
| -------- | ------------------------ | --------------------------------------------------------------------------- |
| Fill     | Respondents              | Read published JSON; start, save, submit, abandon, and reopen responses     |
| Editor   | Trusted application code | Edit and publish surveys, change settings, and read full response snapshots |

The fill audience always requires a guard. The editor audience has a separate
guard and route, so respondent traffic never gains authoring access.

## Start here [#start-here]

<Cards>
  <Card title="Quickstart" href="/docs/quickstart" description="Build the smallest working Next.js integration." />

  <Card title="Response lifecycle" href="/docs/responses" description="Follow snapshot, partial save, submit, and reopen." />

  <Card title="Server integration" href="/docs/integration" description="Mount fill and editor handlers in your runtime." />

  <Card title="Is it the right fit?" href="/docs/comparison" description="Compare ownership with SurveyJS alone and hosted products." />
</Cards>

Machine-readable entry points are available at [llms.txt](https://survey.dimah.dev/llms.txt) and
[llms-full.txt](https://survey.dimah.dev/llms-full.txt). Every docs URL also has a Markdown twin by
adding `.md`.