Forms Builder - Operational Workflows & State Machines
Form authoring lifecycle, multi-step draft progression, DAG evaluation cycle, and state transition tables for the Forms Builder domain.
The Forms Builder domain operates through controlled state machines that govern how form schemas are authored, validated, published, and deprecated, as well as how respondents navigate multi-step drafts and finalize submissions.
1. Schema Authoring & Version Lifecycle
A form schema progresses through a unidirectional lifecycle ensuring that active forms remain stable while permitting continuous design iteration:
stateDiagram-v2
[*] --> Draft: Administrator Creates / Clones Version
Draft --> Validating: Publish Request Triggered
Validating --> Draft: Cycle Detected / Validation Error
Validating --> ActivePublished: DAG Validated & Zero Cycles Confirmed
ActivePublished --> Deprecated: Superceded by Newer Version
ActivePublished --> Archived: Blueprint Decommissioned
Deprecated --> Archived: All Retention Windows Expired
Archived --> [*]
Schema Version State Transitions
| Current State | Target State | Trigger / Action | Guard Conditions | Primary Actor | Domain Event Emitted |
|---|---|---|---|---|---|
[*] | Draft | Designer creates new blueprint or clones an existing frozen schema | Blueprint code is unique; authoring permissions verified | Form Designer | FormSchemaDraftCreated |
Draft | Validating | Designer clicks “Publish Version” | At least one page and one valid input field exist | Form Designer | FormSchemaValidationInitiated |
Validating | ActivePublished | System finishes cycle detection and structural verification | Dependency graph is acyclic; all validation descriptors are sound | Schema Validation Engine | FormSchemaPublished |
Validating | Draft | System discovers an invalid dependency or structural error | Cycle detected or invalid regex descriptor found | Schema Validation Engine | FormSchemaValidationFailed |
ActivePublished | Deprecated | A newer schema version for the same blueprint is published | Newer version achieves ActivePublished state | System Orchestrator | FormSchemaDeprecated |
ActivePublished | Archived | Administrator shuts down the form permanently | Blueprint decommission requested; in-flight drafts notified | Form Administrator | FormSchemaArchived |
Deprecated | Archived | Formal retention period passes with zero active draft sessions | No open draft sessions remain bound to this version | Lifecycle Daemon | FormSchemaArchived |
2. Submitter Response & Multi-Step Draft Progression
Respondents interact with multi-step forms through a persistent draft state machine:
flowchart TD
Start["User Opens Form URL"] --> CheckPolicy{"Access & Quota Valid?"}
CheckPolicy -->|No: Quota / Expired| Deny["Halt: Show Expiration / Quota Screen"]
CheckPolicy -->|Yes: Access Granted| InitDraft["Initialize SubmissionDraftSession"]
InitDraft --> StepView["Render Current Page / Step"]
StepView --> UserInput["User Inputs Answers"]
UserInput --> DagEval["Client-Side DAG Evaluation<br/>(Visibility & Formulas Updated)"]
DagEval --> AutosaveTrigger{"Autosave Triggered?<br/>(Time / Step Navigation)"}
AutosaveTrigger -->|Yes| SaveDraft["Persist Answers to Draft Session"]
AutosaveTrigger -->|No| NextStep{"User Navigates Next?"}
SaveDraft --> NextStep
NextStep -->|Forward Page| StepGate{"Current Step Valid?"}
StepGate -->|Fails| ShowErrors["Display Inline Errors"]
ShowErrors --> UserInput
StepGate -->|Passes| BranchLogic{"Skip Logic Present?"}
BranchLogic -->|Jump Ahead| JumpPage["Navigate to Target Page"]
BranchLogic -->|Sequential| NextPage["Navigate to Step (N+1)"]
JumpPage --> StepView
NextPage --> StepView
NextStep -->|Final Submit Clicked| ServerValidation["Authoritative Server-Side Validation"]
ServerValidation --> Result{"Exhaustive Validation Pass?"}
Result -->|Fails| ReturnErrors["Return Field Error Map to User"]
ReturnErrors --> UserInput
Result -->|Passes| PurgeHidden["Purge Conditionally Concealed Answers"]
PurgeHidden --> HashSealing["Generate SHA-256 Response Hash"]
HashSealing --> CommitSubmission["Commit FormSubmission Aggregate"]
CommitSubmission --> EmitEvent["Emit FormSubmissionValidated Event"]
EmitEvent --> TerminateDraft["Purge Draft Session & Display Confirmation"]
3. Submission Draft Session State Transitions
| Current State | Target State | Trigger / Action | Guard Conditions | Primary Actor | Domain Event Emitted |
|---|---|---|---|---|---|
[*] | SessionInitiated | User loads active form URL or opens invitation token | Form is ActivePublished; quota not reached; not expired | Submitter | FormDraftSessionStarted |
SessionInitiated | DraftProgress | Submitter enters values or triggers autosave | Session token valid; payload size within boundaries | Submitter Client | FormDraftStepSaved |
DraftProgress | DraftProgress | Submitter navigates between pages or periodically saves | Step answers conform to minimum client requirements | Submitter Client | FormDraftStepSaved |
DraftProgress | Submitted | Submitter submits final step and server validation passes | All required active fields valid; response hash sealed | Server Validation Engine | FormSubmissionValidated |
DraftProgress | Expired | Inactivity window exceeds session retention (e.g., 30 days) | Current timestamp > session expiration timestamp | Expiration Daemon | FormDraftSessionExpired |
DraftProgress | Terminated | Blueprint quota is filled by another concurrent user | Target blueprint transitions to QuotaExhausted | System Concurrency Manager | FormDraftSessionTerminated |
4. Directed Acyclic Graph (DAG) Runtime Evaluation Workflow
At both runtime client display and authoritative server ingestion, conditional visibility and calculations are resolved through an exact topological evaluation workflow:
flowchart LR
A["Field Input Change<br/>(e.g., has_dependents = True)"] --> B["Locate DAG Dependents<br/>in Dependency Adjacency Map"]
B --> C["Topologically Order<br/>Affected Dependent Nodes"]
C --> D["Evaluate Visibility Expressions<br/>Against Current Answers"]
D --> E{"Visibility State Changed?"}
E -->|Becomes Visible| F["Enable Controls & Apply Required Rules"]
E -->|Becomes Concealed| G["Disable Controls & Mark for Data Purging"]
F --> H["Evaluate Computed Formulas<br/>(e.g., total_score = sum(...))"]
G --> H
H --> I["Update Downstream Dependents<br/>Recursively Along DAG Edges"]
I --> J["Render Final Visual State<br/>or Finalize Server Validation"]
Dynamic Evaluation Invariants
- Topological Order Execution: If Field $C$ depends on Field $B$, and Field $B$ depends on Field $A$, changes to Field $A$ strictly trigger evaluation of $B$ first, followed by $C$.
- Short-Circuit Protection: If a parent Layout Section evaluates to hidden, all contained child fields are automatically treated as concealed without evaluating their individual conditional logic expressions.