Structural Topology & Domain Modeling

The Forms Builder domain structures its tactical model around two complementary hierarchies: the declarative component composition tree (representing the structural presentation and validation rules of a form) and the tactical Domain-Driven Design (DDD) aggregate hierarchy governing authoring, versioning, draft state persistence, and submission processing.

---

1. Declarative Component Hierarchy

A form schema is organized as a strictly typed hierarchical tree:

Form Blueprint (Administrative Aggregate)
└── Form Schema Version (Structural Definition Aggregate)
    ├── Page / Step (1..N)
    │   ├── Layout Section (1..N)
    │   │   ├── Field Control Definition (1..N)
    │   │   │   ├── Field Key (Unique String Identifier)
    │   │   │   ├── Control Type (Text, Number, Date, Select, Matrix, etc.)
    │   │   │   ├── Presentation Properties (Label, Placeholder, Help Text)
    │   │   │   ├── Validation Descriptors (Required, Regex, Min/Max)
    │   │   │   └── Conditional Visibility Expression (DAG Node Reference)
    │   │   └── Child Sub-Fields (For Matrix / Repeater Controls)
    │   └── Step Skip / Branching Directives
    └── Schema-Level Dependency Graph (Directed Acyclic Graph)

Component Hierarchy Explained

Component	Level	Architectural Responsibility
Form Blueprint	Aggregate Root	Owns administrative settings, form codes, tenant assignment, access restrictions, and global submission quotas.
Form Schema Version	Aggregate Root	Encapsulates the complete, self-contained structural blueprint for a specific release version, maintaining full dependency graphs.
Page / Step	Internal Entity	Represents an isolated view in a paginated sequence, defining step headers and terminal branching logic.
Layout Section	Internal Entity	Groups fields within a page into visual columns, accordion cards, or fieldsets.
Field Control	Internal Entity	The primary unit of input capture, bound to a unique FieldKey and an immutable ControlType.
Validation Descriptor	Value Object	Encapsulates immutable constraints governing legal input values for a control.

---

2. Aggregate Roots & Tactical Architecture

The tactical model isolates responsibilities into four sovereign Aggregate Roots:

flowchart TD
    subgraph BlueprintBoundary["Blueprint & Governance Boundary"]
        FBP["FormBlueprint (Aggregate Root)"]
        AP["AccessPolicy (Value Object)"]
        QP["QuotaPolicy (Value Object)"]

        FBP --> AP
        FBP --> QP
    end

    subgraph SchemaBoundary["Schema Structure & Logic Boundary"]
        FSV["FormSchemaVersion (Aggregate Root)"]
        FP["FormPage (Entity)"]
        LS["LayoutSection (Entity)"]
        FCD["FieldControlDefinition (Entity)"]
        VRD["ValidationRuleDescriptor (Value Object)"]
        DAG["DependencyDagGraph (Value Object)"]

        FSV --> FP
        FP --> LS
        LS --> FCD
        FCD --> VRD
        FSV --> DAG
    end

    subgraph DraftBoundary["User Ingestion & Draft Boundary"]
        SDS["SubmissionDraftSession (Aggregate Root)"]
        EA["EphemeralAnswerMap (Value Object)"]
        SC["SubmitterContext (Value Object)"]

        SDS --> EA
        SDS --> SC
    end

    subgraph SubmissionBoundary["Final Submission & Forensic Boundary"]
        FS["FormSubmission (Aggregate Root)"]
        AM["ValidatedAnswerMap (Value Object)"]
        RH["ResponseHash (Value Object)"]
        VP["ValidationProof (Value Object)"]

        FS --> AM
        FS --> RH
        FS --> VP
    end

    FBP -->|Manages Versions| FSV
    FSV -->|Hydrates Schema To| SDS
    SDS -->|Atomically Submits As| FS
    FS -->|Bound To Version| FSV

---

3. Detailed Aggregate Specifications

Aggregate Root 1: FormBlueprint

• Role: Sovereign custodian of administrative settings, form identity, and publishing lifecycle.
• Root Entity: FormBlueprint (Identified by FormBlueprintId).
• Attributes:
  • BlueprintCode: Immutable, human-readable slug (e.g., vendor_kyc_2026).
  • Title and Description: Localized administrative titles.
  • Category: Domain grouping (e.g., HR_Intake, Compliance_Audit, Customer_Feedback).
  • ActivePublishedVersionId: Pointer to the currently live FormSchemaVersion.
• Value Objects:
  • AccessPolicy: Defines who may access the form (Public, AuthenticatedUsersOnly, RoleRestricted, SingleUseTokenOnly).
  • QuotaPolicy: Defines usage caps, containing MaxSubmissionsAllowed (optional integer limit) and ExpirationTimestamp (optional UTC cutoff).

---

Aggregate Root 2: FormSchemaVersion

• Role: Transaction boundary for structural form definitions, field components, and mathematical logic graphs.
• Root Entity: FormSchemaVersion (Identified by SchemaVersionId, references FormBlueprintId).
• Attributes:
  • MajorVersion and MinorVersion: Semantic version tokens (e.g., 2.1).
  • PublicationStatus: Formal lifecycle state (Draft, ActivePublished, Deprecated, Archived).
  • FrozenTimestamp: The exact moment the version became immutable upon receiving its first live submission.
• Internal Entities:
  • FormPage: Represents a discrete wizard step, ordered by sequence index.
  • LayoutSection: Groups fields with presentation grid layout configurations (1 to 4 columns).
  • FieldControlDefinition: Defines an input element. Contains FieldKey, Label, ControlType (TextInput, NumericInput, DatePicker, SingleSelect, MultiSelectCheckboxes, FileUpload, DigitalSignature, ComputedFormula, MatrixTable), default values, and placeholder text.
• Value Objects:
  • ValidationRuleDescriptor: Immutable constraint collection, including IsRequired, MinLength, MaxLength, RegexPattern, MinNumericValue, MaxNumericValue, AllowedMimeTypes, and MaxUploadBytes.
  • DependencyDagGraph: An adjacency map representing all field-to-field and field-to-page conditional expressions, validated for strict acyclicity.
  • FormulaExpression: Mathematical or string expression defining computed fields (e.g., round(field_weight / (field_height * field_height), 2)).

---

Aggregate Root 3: SubmissionDraftSession

• Role: Coordinates progressive user responses, autosave persistence, and step-level navigation state.
• Root Entity: SubmissionDraftSession (Identified by DraftSessionId).
• Attributes:
  • SchemaVersionId: The exact schema version against which the draft was opened.
  • CurrentStepIndex: Zero-indexed integer indicating the user’s active page.
  • LastAutosavedAt: UTC timestamp of the most recent save.
  • ExpirationTimestamp: Date when abandoned drafts are automatically purged.
• Value Objects:
  • SubmitterContext: Captures submitter metadata (SubmitterId, ClientIpAddress, UserAgent, TenantId).
  • EphemeralAnswerMap: An unverified, work-in-progress key-value store of user answers. Values stored in the draft session are explicitly considered unverified until final submission.

---

Aggregate Root 4: FormSubmission

• Role: The authoritative, permanently sealed historical record of a completed response.
• Root Entity: FormSubmission (Identified by SubmissionId).
• Attributes:
  • FormBlueprintId: Identifies the parent form concept.
  • SchemaVersionId: Identifies the exact frozen schema version used.
  • SubmissionTimestamp: Authoritative UTC clock time of final validation.
  • SubmissionStatus: Final processing state (Validated, ProcessedByDownstream, FlaggedAudit).
• Value Objects:
  • ValidatedAnswerMap: Fully verified, type-safe dictionary of answers matching active, visible fields.
  • ComputedFieldsSnapshot: Cached outputs of all formula controls evaluated at the moment of submission.
  • ResponseHash: Cryptographic SHA-256 digest computed across the sorted canonical JSON representation of the answer map.
  • ValidationProof: Detailed execution log verifying that every validation rule and DAG condition was satisfied at submission time.