Data Model

Entities

┌──────────┐       ┌────────────────┐       ┌──────────────┐
│  forms   │───1:N─│ form_versions  │       │  webhooks    │
└────┬─────┘       └────────────────┘       └──────┬───────┘
     │                                             │
     │ 1:N                                         │ 1:N
     │                                             │
┌────▼─────┐                              ┌────────▼────────┐
│ sessions │                              │ webhook_deliveries│
└────┬─────┘                              └─────────────────┘
     │ 1:1
┌────▼────────┐
│ submissions │
└─────────────┘

forms

Core form entity. Each form has a slug, status, and current version.

Column	Type	Description
id	TEXT	Primary key, e.g. form_abc123
name	TEXT	Human-readable name
slug	TEXT	URL-safe identifier, unique per project
description	TEXT	Optional description
status	TEXT	draft, published, or archived
current_version_id	TEXT	FK to form_versions.id
created_at	TEXT	ISO 8601
updated_at	TEXT	ISO 8601

form_versions

Immutable snapshots of a form definition at publish time. Versioning is checksum-based: publishing a form reuses the last version if the definition hasn’t changed.

Column	Type	Description
id	TEXT	Primary key, e.g. ver_xyz789
form_id	TEXT	FK to forms.id
version	INTEGER	Monotonic version number
definition	TEXT	JSON blob of the full form definition
checksum	TEXT	SHA-256 of the definition for dedup
created_at	TEXT	ISO 8601

Checksum-based dedup

When publish() is called with an unchanged definition, the existing version is reused. This means:

• Consecutive publishes of identical definitions don’t create new versions.
• form_versions.version skips numbers when a checksum is reused.
• Submission data always references the correct form_version_id for audit.

sessions

Note

Sessions table is planned. The schema below reflects the target design.

Column	Type	Description
id	TEXT	Primary key, e.g. sess_xyz789
form_id	TEXT	FK to forms.id
status	TEXT	created, open, submitted, expired
prefill	TEXT	JSON blob of prefill values
metadata	TEXT	JSON blob of arbitrary metadata
expires_at	TEXT	ISO 8601
created_at	TEXT	ISO 8601

submissions

Note

Submissions table is planned. The schema below reflects the target design.

Column	Type	Description
id	TEXT	Primary key, e.g. sub_def456
form_id	TEXT	FK to forms.id
form_version_id	TEXT	FK to form_versions.id
session_id	TEXT	FK to sessions.id
answers	TEXT	JSON blob of field id → value
partial	INTEGER	0 or 1
submitted_at	TEXT	ISO 8601

webhooks and webhook_deliveries

Note

Webhook tables are planned. The schema below reflects the target design.

Column (webhooks)	Type	Description
id	TEXT	Primary key
url	TEXT	HTTPS endpoint
events	TEXT	JSON array of event types
secret_hash	TEXT	Hashed HMAC secret
active	INTEGER	0 or 1
created_at	TEXT	ISO 8601

Column (webhook_deliveries)	Type	Description
id	TEXT	Primary key
webhook_id	TEXT	FK to webhooks.id
event_id	TEXT	The event being delivered
status	TEXT	pending, success, failed
attempt	INTEGER	Retry attempt number
response_code	INTEGER	HTTP status from the target
created_at	TEXT	ISO 8601