Skip to main content
Version: Isle Royale (2.5.0)

Data Model

Before using ToughClicks, it's helpful to understand a portion of our data model. Specifically, the relationship between Packets, Documents, and Versions.

Relationships​

Understanding how entities relate to each other is crucial for working with ToughClicks:

  • Packets have many Documents
  • Documents have many Packets
  • Documents have many Versions
  • Versions have one Document

Document Versions​

Versions have some important fields you should know:

State​

A version can be in one of two states:

  • DRAFT - The version is still being edited and is not yet available for users to accept
  • PUBLISHED - The version is live and can be presented to users for acceptance
Version Immutability

Once a version is published, it cannot be edited or deleted. This is a critical feature that ensures the integrity of legal acceptances - you cannot change the terms after someone has agreed to them.

Version Number​

The version number follows a {MAJOR}.{MINOR} format:

  • Major version - Incremented for significant changes that typically require re-acceptance
  • Minor version - Incremented for minor clarifications or non-material changes

Example:

  • 1.0 → 1.1 (minor update)
  • 1.1 → 2.0 (major update requiring re-acceptance)

Example Structure​

Here's a practical example of how these entities work together:

Client: "MyApp Inc"
├── Packet: "User Registration" (ID: abc-123)
│ ├── Document: "Terms of Service"
│ │ ├── Version 1.0 (PUBLISHED)
│ │ ├── Version 1.1 (PUBLISHED)
│ │ └── Version 2.0 (DRAFT)
│ └── Document: "Privacy Policy"
│ ├── Version 1.0 (PUBLISHED)
│ └── Version 1.1 (PUBLISHED)
└── Packet: "Marketing Consent" (ID: def-456)
└── Document: "Marketing Terms"
└── Version 1.0 (PUBLISHED)

Multi-Packet Scenarios​

With ToughClicks' multi-packet support, you can handle complex scenarios:

Required and Optional Packets​

// Required packet - must be accepted
Packet A: "Terms of Service" (required)
└── Document: "TOS v2.0"

// Optional packet - user can opt in
Packet B: "Marketing Communications" (optional)
└── Document: "Marketing Consent v1.0"

Different Display Methods​

// Scroll method - user must scroll through terms
Packet A: "Legal Terms"
└── Documents shown in scrollable container

// Individual method - separate checkbox for each doc
Packet B: "Preferences"
└── Each document has its own checkbox

// Group method - one checkbox for all docs
Packet C: "Quick Consent"
└── Single checkbox accepts all documents

Acceptance Records​

When a user accepts documents, ToughClicks creates immutable Acceptance records:

{
"signerId": "user@example.com",
"packetId": "abc-123",
"acceptances": [
{
"documentId": "doc-1",
"versionId": "ver-1.1",
"acceptedAt": "2025-10-04T10:30:00Z",
"ipAddress": "192.168.1.1",
"userAgent": "Mozilla/5.0..."
}
]
}

Best Practices​

  1. Version carefully - Since published versions are immutable, review thoroughly before publishing
  2. Use meaningful version numbers - Major changes should increment the major version
  3. Organize packets logically - Group related documents together
  4. Plan for re-acceptance - When updating to a new major version, plan how to handle requiring re-acceptance

Next Steps​