Skip to main content

Legal Documents - Getting Started

Overview​

The Legal Documents Management System allows administrators to manage Terms of Service and Privacy Policy documents with user acceptance tracking, version control, and compliance audit trails.

This guide walks through setting up and using the system.

What You'll Learn​

  • How the legal documents system works
  • How to create and publish documents
  • How users accept terms
  • How to track and export acceptance records
  • Best practices for enforcement

Key Concepts​

Active Document​

Only one document version per type (terms or privacy) can be active at a time. This is the version users must accept.

Draft​

An unpublished document that can be edited. Once published, it becomes immutable.

Version​

Uses semantic versioning (1.0.0, 2.0.0, etc.):

  • 1.0.0 = First release
  • 1.1.0 = Minor update
  • 2.0.0 = Major change

Enforcement Type​

Two options for requiring acceptance:

  1. Immediate: Users blocked from platform until they accept (use for material changes)
  2. Grace Period: Users see dismissible banner; blocked after X days (use for minor updates)

Acceptance Record​

Each time a user accepts, we record:

  • User ID
  • Document version
  • Exact timestamp
  • IP address
  • User agent

Before You Start​

Make sure you have:

  • Admin account with email in whitelist
  • Access to /legal admin panel
  • Your Terms of Service document
  • Your Privacy Policy document

Step 1: Access the Admin Panel​

  1. Navigate to https://civstart.ventures/admin
  2. Sign in with your admin email
  3. Look for "Legal Docs" in the left sidebar (between Credit Config and Settings)
  4. Click to go to document list

Step 2: Create Your First Document​

Create Terms of Service​

  1. Click "Create Document" button
  2. Fill in the form:
    • Type: Select "Terms of Service"
    • Version: Enter 1.0.0
    • Title: "Terms of Service" or your preferred title
    • Content: Paste your full Terms of Service text
    • Effective Date: Select date when terms become effective
    • Enforcement:
      • Toggle "Require Immediate Acceptance" ✓ (for first version)
  3. Click "Save & Publish"
  4. Document is now active and required for all users

Create Privacy Policy​

Repeat the same steps but:

  • Type: Select "Privacy Policy"
  • Content: Paste your Privacy Policy

Step 3: Verify Publishing​

  1. You should see both documents in the list view
  2. Both should show "Active" badge (green)
  3. Click on each to verify content displays correctly

Step 4: Test as User​

Create Test Account​

  1. Sign out as admin
  2. Sign up as a new user
  3. You should see "Terms of Service & Privacy Policy" modal
  4. Read both tabs
  5. Check the agreement checkbox
  6. Click "Accept Terms"
  7. You should be granted access

Check Settings​

  1. Go to /settings page
  2. Scroll to "Legal Agreements" section
  3. You should see:
    • ✓ Terms of Service v1.0.0 - Current
    • ✓ Privacy Policy v1.0.0 - Current
  4. Click "Review" to verify you can open modal again

Step 5: Monitor Acceptances​

View Acceptance Logs​

  1. Admin panel → Legal Docs → Acceptances (or click "Acceptances" link)
  2. You should see the test user you just created
  3. Shows:
    • User email
    • Document type
    • Version accepted
    • Acceptance timestamp
    • IP address (if captured)

Export CSV​

  1. Still on Acceptances page
  2. Click "Export CSV" button
  3. Downloads terms-acceptance-YYYY-MM-DD.csv
  4. Can open in Excel, Google Sheets, etc.

Step 6: Update Documents (Later)​

When you need to update terms (e.g., next month):

Create New Version​

  1. Admin panel → Legal Docs
  2. Click "Create Document"
  3. Fill form:
    • Type: Terms of Service (same as before)
    • Version: 1.1.0 (increment minor version)
    • Content: Updated terms text
    • Enforcement: Choose immediate or grace period
  4. Click "Save & Publish"

What Happens​

  • Previous v1.0.0 automatically archived
  • New v1.1.0 becomes active
  • All users see modal on next login
  • Users must accept v1.1.0 to continue

Enforcement Strategies​

Immediate Acceptance​

Use for material changes (legal requirements, new restrictions):

✓ Require Immediate Acceptance
  Grace Period: [disabled]

User Experience:

  • Next login → Blocking modal
  • Cannot access platform until accepts
  • Accept → Granted access

Grace Period​

Use for minor updates (clarifications, wording changes):

☐ Require Immediate Acceptance
  Grace Period: 7 days

User Experience:

  • Next login → Dismissible banner
  • Can continue using platform
  • Banner shows deadline
  • After 7 days → Modal becomes blocking

Best Practices​

Versioning​

Initial launch     → 1.0.0
Minor updates      → 1.1.0, 1.2.0
Major changes      → 2.0.0, 3.0.0

Enforcement​

  • Immediate: Legal requirement, policy change, new restrictions
  • Grace Period: Formatting, clarification, wording improvement

Communication​

Before publishing major updates:

  1. Notify users via email
  2. Explain what changed
  3. Link to new version
  4. Set clear deadline if grace period

Audit​

Regularly check acceptance rates:

  1. Go to document details
  2. Click "Analytics" tab
  3. Check acceptance rate %
  4. Follow up if acceptance rate is below 95%

Common Tasks​

View Document Details​

  1. Admin → Legal Docs
  2. Click on document card
  3. See:
    • Full content
    • Enforcement settings
    • Analytics (if published)
    • Recent acceptances

Edit Document (Draft Only)​

  1. Admin → Legal Docs
  2. Click document → Click "Edit" button
  3. Update content
  4. Click "Save Draft"
  5. Not published yet - users don't see it
  6. Later: Click "Publish"

Cannot Edit Published Document?​

This is intentional for audit trail.

Solution: Create new version

  1. Click document → Click "Duplicate"
  2. Edit new version
  3. Publish new version
  4. Old version automatically archived

Remove from Active​

Cannot "unpublish" a document.

Solution: Publish a new empty version (rarely needed)

  • Not recommended for compliance reasons
  • Keeps audit trail intact

Troubleshooting​

  • Check /legal/status API returns needsAcceptance: true
  • Verify user's version doesn't match active version
  • Verify document is marked isActive: true in database
  • Admin sidebar may need to reload
  • Clear browser cache
  • Check your email is in admin whitelist

CSV Export empty​

  • Check filters aren't too restrictive
  • Verify documents have been published
  • Check date range if filtering

Acceptance not recorded​

  • Check network request to /legal/accept succeeds
  • Verify user is authenticated
  • Check database document_acceptances table

Advanced Features​

Analytics​

  • View acceptance rates per document
  • See exactly how many users accepted
  • Track trends over time
  • Inform compliance efforts

Audit Trail​

  • Every acceptance recorded with timestamp
  • IP address captured (for security)
  • User agent stored (for device tracking)
  • Immutable once accepted

CSV Export​

  • Download all acceptance records
  • Useful for compliance audits
  • GDPR/legal requirement documentation
  • Filter by type, date, email

Next Steps​

  1. ✓ Create your initial documents
  2. ✓ Test as a user
  3. ✓ Check Settings page shows legal section
  4. ✓ Review acceptance logs
  5. ✓ Practice exporting CSV

Getting Help​

Summary​

You now have a complete legal documents management system:

✓ Create, edit, and publish terms/privacy policy ✓ Track user acceptances with audit trail ✓ Export compliance records ✓ Manage versions with flexibility ✓ Choose enforcement strategy per update

The system ensures users affirmatively accept your terms and maintains a complete audit trail for compliance purposes.

Happy documenting! 📄✨