# Introduction (https://form.dimah.dev/docs)



**dimah-form** is a backend-first questionnaire engine. It freezes the form definition onto every response, validates answers against that snapshot, and gives React a thin fill-session hook. It does not render fields, ship widgets, or own your auth.

<Flow
  label="System Data Flow"
  steps="[
  {
    name: &#x22;React Client&#x22;,
    kind: &#x22;client&#x22;,
    note: &#x22;useFormResponse + your widgets&#x22;,
  },
  {
    name: &#x22;HTTP Handler&#x22;,
    kind: &#x22;server&#x22;,
    note: &#x22;dimahForm() + your guard&#x22;,
  },
  { name: &#x22;Persistence&#x22;, kind: &#x22;data&#x22;, note: &#x22;Snapshots and responses&#x22; },
]"
/>

***

## When to use it [#when-to-use-it]

Use it when you need typed questionnaires with drafts and server-side validation, and you already have a design system.

Skip it if you want a form renderer, a visual builder, or hosted survey SaaS.

The problems it is built around:

1. **Schema drift** — an admin can change a live form while someone is still filling a draft. dimah-form validates against the snapshot taken at start, not the live definition.
2. **Drafts** — respondents leave, switch devices, or drop packets. Drafts save incrementally, with `updatedAt` compare-and-swap so two tabs do not silently overwrite each other.
3. **Headless validation** — you render with Tailwind, shadcn/ui, or plain HTML. The server still checks required visible fields against the frozen snapshot.

***

## Packages [#packages]

```
@dimah-form/core
        ↓
@dimah-form/server  ←  @dimah-form/db (optional)
        │
@dimah-form/react
```

| Package                  | Where                    | What you import it for                                                             |
| :----------------------- | :----------------------- | :--------------------------------------------------------------------------------- |
| **`@dimah-form/core`**   | Shared                   | Protocol types, field validators, error codes. Server and React both depend on it. |
| **`@dimah-form/server`** | Node / Edge              | `dimahForm()`, HTTP adapters, `form.api`, `memoryAdapter()`.                       |
| **`@dimah-form/react`**  | Browser (`"use client"`) | `createFormClient()`, `useFormResponse()`, field helpers.                          |
| **`@dimah-form/db`**     | Server                   | Optional. Production SQL adapter via FumaDB.                                       |

***

## How to read these docs [#how-to-read-these-docs]

Start with the **Quickstart** if you want a working Next.js form. Read **Architecture** and **Snapshots** when you need the model, not just the copy-paste.

<Cards>
  <Card title="Quickstart" href="/docs/quickstart" description="Install, define a form, mount the handler, and render a fill UI." />

  <Card title="Architecture" href="/docs/architecture" description="Package boundaries, data flow, and the request pipeline." />

  <Card title="Forms" href="/docs/forms" description="defineForm, field rules, showWhen, and $Infer." />

  <Card title="React Client" href="/docs/react" description="useFormResponse: visibility, drafts, and submit." />
</Cards>

After that, pick the layer you are implementing:

* **Client** — [React](https://form.dimah.dev/docs/react) and [Widgets](https://form.dimah.dev/docs/widgets)
* **Backend** — [Server](https://form.dimah.dev/docs/server), [Database](https://form.dimah.dev/docs/database), [Auth](https://form.dimah.dev/docs/auth)
* **Extending** — [Custom Fields](https://form.dimah.dev/docs/custom-fields) and [Plugins](https://form.dimah.dev/docs/plugins)
* **Reference** — [Configuration](https://form.dimah.dev/docs/configuration), [Field Types](https://form.dimah.dev/docs/field-types), [Protocol](https://form.dimah.dev/docs/protocol), [Errors](https://form.dimah.dev/docs/errors)