Skip to content

Policy Template Versioning Architecture

Overview

GetCimple's policy versioning system enables us to continuously improve policy templates while customers maintain their configurations and implementation progress. The system uses a configuration-over-customization model that eliminates merge conflicts and provides automatic updates.

Key Innovation: Locked best-practice content + configurable parameters = Zero-conflict updates

Architectural Decision: Configuration vs Customization

The Core Choice

We had to decide: Do we let customers fully customize policy content, or do we limit them to configuration?

Decision: Configuration-based policies with locked content

Rationale

Option A: Full Customization (Rejected)

Model: Customers can edit any part of the policy

❌ Problems:

  • Merge conflicts when we release updates
  • Three-way diff required (our v1.0 → their customized v1.0 → our v1.1)
  • Complex UI for resolving conflicts
  • Can't guarantee compliance if content is modified
  • High support burden
  • Customers may introduce errors

Option B: Configuration-Based (Selected)

Model: Core content is locked, customers configure parameters

✅ Benefits:

  • Zero merge conflicts (reapply configuration = auto-merge)
  • Simple UI (just configure new parameters)
  • Compliance guarantee (we control content)
  • Fast updates (minutes not hours)
  • Customers trust expert-maintained content
  • Aligns with industry practice (Vanta, Drata, Secureframe)

Real-World Validation

How policies are created today:

  1. Hire consultant ($5k-20k) → Use their template, fill in specifics
  2. Download ISO/NIST template → Configure for organization
  3. Write from scratch → Almost nobody does this

Insight: Companies already use locked templates from experts. We're providing the same model as a service.

System Architecture

High-Level Flow

┌─────────────────────────────────────────────────────────────┐
│                      GetCimple Maintains                     │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ Policy Templates                                       │ │
│  │ ├── v1.0 (Released Jan 2025)                          │ │
│  │ ├── v1.1 (Released Jun 2025) ← New version           │ │
│  │ └── v2.0 (Released Dec 2025)                          │ │
│  │                                                        │ │
│  │ Content:                                               │ │
│  │ • Locked sections (best practice text)                │ │
│  │ • Variable definitions                                │ │
│  │ • Parameter definitions (dropdowns, ranges)           │ │
│  │ • Optional section definitions                        │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              ↓
                    Update Detection
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                      Customer Policies                       │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ Active: Access Control Policy v1.0                     │ │
│  │ Configuration:                                         │ │
│  │   variables: {company_name: "Acme", ciso: "Jane"}     │ │
│  │   parameters: {password_length: 14, frequency: "Q"}   │ │
│  │   sections: ["cloud", "contractors"]                  │ │
│  │   addenda: "Our implementation timeline..."           │ │
│  │ Progress: 40% complete                                │ │
│  └────────────────────────────────────────────────────────┘ │
│                              ↓                               │
│              Notification: "Update available"                │
│                              ↓                               │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ Draft: Access Control Policy v1.1                      │ │
│  │ Auto-merged configuration:                             │ │
│  │   ✓ Variables preserved                                │ │
│  │   ✓ Parameters preserved (where still valid)           │ │
│  │   ✓ Sections preserved (where still exist)             │ │
│  │   ✓ Addenda preserved                                  │ │
│  │   ⚠️ New parameters: Need review                       │ │
│  └────────────────────────────────────────────────────────┘ │
│                              ↓                               │
│                   Customer reviews & approves                │
│                              ↓                               │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ Active: Access Control Policy v1.1 ✓                   │ │
│  │ Archived: v1.0 (Jan-Jun 2025)                          │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Component Architecture

┌──────────────────────────────────────────────────────────┐
│                     API Layer                            │
│                                                          │
│  GET  /api/policies/updates          → Check updates    │
│  POST /api/policies/{id}/draft       → Create draft     │
│  PATCH /api/policies/{id}/draft      → Update config    │
│  POST /api/policies/{id}/draft/approve → Activate       │
└──────────────────────────────────────────────────────────┘
                         ↓
┌──────────────────────────────────────────────────────────┐
│                  Business Logic Layer                    │
│                                                          │
│  ┌─────────────────────────────────────────────────────┐│
│  │ Update Detection Service                            ││
│  │ • Query: customer version < latest version?         ││
│  │ • Returns: List of available updates                ││
│  └─────────────────────────────────────────────────────┘│
│                                                          │
│  ┌─────────────────────────────────────────────────────┐│
│  │ Auto-Merge Service                                  ││
│  │ • Takes: Current config + New template              ││
│  │ • Returns: Merged config with review items          ││
│  │ • Logic: Reapply values where keys match            ││
│  └─────────────────────────────────────────────────────┘│
│                                                          │
│  ┌─────────────────────────────────────────────────────┐│
│  │ Progress Mapping Service                            ││
│  │ • Takes: Old progress + New template sections       ││
│  │ • Returns: Mapped progress (by section ID)          ││
│  └─────────────────────────────────────────────────────┘│
│                                                          │
│  ┌─────────────────────────────────────────────────────┐│
│  │ Validation Service                                  ││
│  │ • Validates config against template definitions     ││
│  │ • Checks parameter ranges, required fields          ││
│  │ • Post-MVP: Dependency validation                   ││
│  └─────────────────────────────────────────────────────┘│
└──────────────────────────────────────────────────────────┘
                         ↓
┌──────────────────────────────────────────────────────────┐
│                    Data Layer                            │
│                                                          │
│  ┌──────────────────────┐  ┌─────────────────────────┐  │
│  │ policy_templates     │  │ customer_policy_        │  │
│  │                      │  │ instances               │  │
│  │ • current_version    │  │                         │  │
│  │ • locked_content     │  │ • active_version        │  │
│  │ • variable_defs      │  │ • configuration         │  │
│  │ • parameter_defs     │  │ • draft_version         │  │
│  │ • section_defs       │  │ • draft_configuration   │  │
│  └──────────────────────┘  └─────────────────────────┘  │
│                                                          │
│  ┌──────────────────────────────────────────────────────┐│
│  │ policy_version_archives                              ││
│  │ • Audit trail of previous versions                   ││
│  │ • active_from / active_until dates                   ││
│  └──────────────────────────────────────────────────────┘│
└──────────────────────────────────────────────────────────┘

Configuration Model Deep Dive

Policy Structure

Every policy template consists of four configuration layers:

1. Locked Content [NOT EDITABLE]

## Password Requirements

All user accounts at {{company_name}} must use passwords of at
least {{password_length}} characters. Passwords must be changed
every {{password_expiry_days}} days.

This requirement aligns with Essential Eight Maturity Level 2
for authentication hardening.

Characteristics:

  • Maintained by GetCimple compliance experts
  • Updated to reflect regulatory changes
  • Markdown with {{variable}} placeholders
  • Maps to compliance frameworks (E8, ISO 27001)

2. Variables [TEXT SUBSTITUTION]

{
  "company_name": "Acme Corporation",
  "ciso_name": "Jane Smith",
  "tool_name": "Okta"
}

Characteristics:

  • Simple key-value pairs
  • Always preserved during updates
  • Used for organization-specific names/tools

3. Parameters [BOUNDED CONFIGURATION]

{
  "password_length": 14, // Range: 12-16
  "password_expiry_days": 90, // Range: 60-180
  "review_frequency": "quarterly" // Options: monthly/quarterly/annually
}

Characteristics:

  • Bounded selections within best practices
  • Dropdowns, number ranges, dates
  • Smart migration: preserve if still valid, use default if not

4. Optional Sections [TOGGLE ON/OFF]

{
  "enabled_sections": ["cloud", "contractors", "byod"]
}

Characteristics:

  • Enable/disable based on applicability
  • Examples: Cloud services, Contractors, Remote work
  • Only kept if still exist in new version

5. Company-Specific Addenda [FREEFORM]

## Our Implementation Timeline

Phase 1 (Q1 2025): All administrative accounts
Phase 2 (Q2 2025): All user accounts

## Approved Exceptions

Legacy system X: To be migrated by Q3 2025

Characteristics:

  • Markdown freeform text
  • Rendered as formal appendix to policy
  • Always preserved during updates
  • Escape hatch for company context

Auto-Merge Algorithm

How Updates Work Without Conflicts

function autoMerge(
  oldConfig: Configuration,
  newTemplate: Template
): MergedConfiguration {
  return {
    // 1. Variables: Always carry forward (simple)
    variables: oldConfig.variables,

    // 2. Parameters: Smart migration
    parameters: mergeParameters(
      oldConfig.parameters,
      newTemplate.parameter_definitions
    ),

    // 3. Sections: Filter to still-valid
    enabled_sections: oldConfig.enabled_sections.filter(
      (sectionId) => newTemplate.section_definitions[sectionId] !== undefined
    ),

    // 4. Addenda: Always preserve
    company_addenda: oldConfig.company_addenda,
  }
}

function mergeParameters(old, newDefs) {
  const merged = {}

  for (const [key, definition] of Object.entries(newDefs)) {
    if (old[key] !== undefined && isValidValue(old[key], definition)) {
      // Parameter exists and still valid → keep it
      merged[key] = old[key]
    } else {
      // Parameter new or invalid → use default
      merged[key] = definition.default
    }
  }

  return merged
}

Why This Works

No conflicts possible because:

  1. Locked content can't conflict (customer never edited it)
  2. Variables are simple key-value (always preserve)
  3. Parameters are bounded (validate and default if needed)
  4. Sections are toggles (filter to valid IDs)
  5. Addenda is freeform (always append)

Result: 100% automatic merge success rate

Update Workflow States

State Machine

┌─────────────┐
│   Active    │  Customer using v1.0
│   v1.0      │  Board-approved, implementing
└──────┬──────┘
       │
       │ We release v1.1
       ↓
┌─────────────┐
│  Notified   │  Dashboard: "Update available"
│             │  Customer can review anytime
└──────┬──────┘
       │
       │ Customer clicks "Review Update"
       ↓
┌─────────────┐
│  Draft      │  Auto-merged draft created
│  Created    │  v1.0 still active, v1.1 in draft
└──────┬──────┘
       │
       │ Customer configures new parameters
       ↓
┌─────────────┐
│  Reviewing  │  Customer reviews changes
│             │  Can edit draft configuration
└──────┬──────┘
       │
       │ Customer takes to board
       ↓
┌─────────────┐
│  Approved   │  Board approves v1.1
│             │  Ready to activate
└──────┬──────┘
       │
       │ System activates draft
       ↓
┌─────────────┐  ┌─────────────┐
│   Active    │  │  Archived   │
│   v1.1      │  │  v1.0       │
│             │  │ (Jan-Jun 25)│
└─────────────┘  └─────────────┘

Database States

-- State 1: Active v1.0, no draft
active_template_version = '1.0'
draft_template_version = NULL
status = 'implementing'

-- State 2: Active v1.0, draft v1.1 in progress
active_template_version = '1.0'
draft_template_version = '1.1'
draft_configuration = {...}
status = 'implementing'

-- State 3: v1.1 activated, v1.0 archived
active_template_version = '1.1'
draft_template_version = NULL
status = 'approved'

-- Archive entry created:
INSERT INTO policy_version_archives (
  template_version = '1.0',
  active_from = '2025-01-15',
  active_until = '2025-06-15'
)

Implementation Progress Mapping

Challenge

When updating from v1.0 to v1.1:

  • v1.0 had 8 sections, 40% complete overall
  • v1.1 has 10 sections (2 new, 8 unchanged)
  • How do we map progress?

Solution: Section ID Matching

interface ProgressItem {
  section_id: string // 'password_requirements'
  status: 'not_started' | 'in_progress' | 'completed'
  progress_percentage: number
  evidence_ids: string[]
}

function mapProgress(
  oldProgress: ProgressItem[],
  newTemplate: Template
): ProgressItem[] {
  const newSections = newTemplate.locked_content.sections

  return newSections.map((section) => {
    const oldItem = oldProgress.find((p) => p.section_id === section.id)

    if (oldItem) {
      // Section exists in both versions → carry forward
      return oldItem
    } else {
      // New section → start from scratch
      return {
        section_id: section.id,
        status: 'not_started',
        progress_percentage: 0,
        evidence_ids: [],
      }
    }
  })
}

Result

v1.0 Progress:
├── purpose: 100% ✓
├── scope: 100% ✓
├── password_requirements: 60% →
└── mfa_requirements: 0%

v1.1 Progress (after mapping):
├── purpose: 100% ✓ (carried forward)
├── scope: 100% ✓ (carried forward)
├── password_requirements: 60% → (carried forward)
├── mfa_requirements: 0% (carried forward)
├── biometric_auth: 0% [NEW]
└── session_management: 0% [NEW]

Security & Multi-Tenancy

Row Level Security (RLS)

-- Organizations can only see their own policies
CREATE POLICY org_isolation ON customer_policy_instances
  FOR ALL
  USING (organization_id = current_setting('app.current_organization_id')::UUID);

Data Isolation

Organization A                Organization B
├── Policy Instance 1         ├── Policy Instance 10
│   Template: Access Control  │   Template: Access Control
│   Version: 1.0              │   Version: 1.1
│   Config: {their data}      │   Config: {their data}
└── Policy Instance 2         └── Policy Instance 11
    Template: Incident Resp       Template: BYOD Policy

Key Principle: Template is shared, configuration is isolated

Performance Considerations

Update Detection Query

-- Optimized with compound index
CREATE INDEX idx_customer_policies_updates
  ON customer_policy_instances(template_id, active_template_version);

-- Query executes in <10ms even with 10k policies
SELECT COUNT(*)
FROM customer_policy_instances
WHERE active_template_version < (
  SELECT current_version FROM policy_templates WHERE template_id = $1
);

Configuration Storage

JSONB Benefits:

  • Flexible schema for MVP
  • Fast queries with GIN indexes
  • Can add fields without migrations
  • Supports partial updates

Post-MVP Optimization:

  • Could normalize heavily-queried fields
  • Add materialized views for analytics
  • But MVP JSONB is perfectly fine

MVP vs Post-MVP Features

MVP (Essential)

✅ Template versioning (current_version field) ✅ Update detection (version comparison) ✅ Auto-merge logic (reapply configuration) ✅ Dashboard notifications ✅ Simple review UI (changelog + new parameter config) ✅ Progress mapping (section ID matching) ✅ Archive previous versions

Post-MVP (Enhancements)

❌ Sophisticated diff viewer (side-by-side comparison) ❌ Email notifications (just dashboard for MVP) ❌ Policy health dashboard (outdated warnings) ❌ Complex validation rules (parameter dependencies) ❌ "Detach from template" escape hatch ❌ Deprecated section migration workflows ❌ Separate template_versions table (MVP uses single table)

Why This Must Be MVP

The Version Debt Trap

Without versioning from day one:

Day 1:  Customer adopts Access Control Policy
        → Stored without template_version field
        → Just "Access Control Policy" in database

Day 30: We improve policy content
        → Can't tell which version customer has
        → Can't provide targeted update

Day 60: 50 customers using various unknown versions
        → Data migration nightmare
        → Manual customer outreach required
        → Trust damage

With versioning from day one:

Day 1:  Customer adopts Access Control Policy v1.0
        → Stored: template_id + template_version: "1.0"

Day 30: We release v1.1
        → Query: WHERE template_version < '1.1'
        → Automatic notification to affected customers

Day 60: 50 customers: 30 on v1.0, 20 on v1.1
        → Clear audit trail
        → Targeted communications
        → Smooth update path

We're Selling Managed Compliance

Without updates: We're a document generator With updates: We're a compliance platform

The ability to improve policies continuously is core to the value proposition.

Risks & Mitigations

Risk 1: Template Content Errors

Impact: High - Liability if policy is wrong Mitigation:

  • Rigorous internal review process
  • External compliance expert review
  • Start with well-vetted templates (ISO 27001, E8)
  • Version numbers allow rollback

Risk 2: Configuration Model Too Restrictive

Impact: Medium - Some customers need more Mitigation:

  • MVP: "Company Addenda" provides escape hatch
  • Post-MVP: "Detach" for true edge cases
  • Target market (SMB/mid-market) rarely needs full customization

Risk 3: Progress Mapping Edge Cases

Impact: Low - Incorrectly mapped progress Mitigation:

  • Conservative approach (only map exact section ID matches)
  • Clear UI showing what was carried forward
  • Manual override if needed

Future Enhancements

Phase 2: Advanced Features

Sophisticated Diff Viewer:

  • Side-by-side comparison
  • Highlight additions/deletions/modifications
  • Jump to changes navigation

Email Notifications:

  • Critical updates: Immediate email
  • Best practice: Weekly digest
  • Customizable notification preferences

Policy Health Dashboard:

  • Organization-wide policy compliance score
  • "12 of 13 policies up to date (92%)"
  • Red/yellow/green indicators

Validation Rules:

  • Parameter dependencies ("Biometric auth requires password_length ≥ 14")
  • Section prerequisites ("Cloud section requires Network section")
  • Custom validation logic

Phase 3: Enterprise Features

Detach from Template:

  • Full control for edge cases
  • Warning about losing updates
  • Rich text editor
  • Separate "Custom Policies" section

Template Versioning Table:

  • Full version history in separate table
  • Diff between any two versions
  • Rollback capability

Advanced Analytics:

  • Update adoption rates
  • Time-to-adopt metrics
  • Most-skipped updates
  • Customer segmentation

Conclusion

The configuration-based policy versioning system is foundational to GetCimple's value proposition. By choosing configuration over customization, we've created a system that is:

✅ Simple - Customers configure, not rewrite ✅ Fast - Updates take minutes, not hours ✅ Reliable - Zero merge conflicts guaranteed ✅ Compliant - Expert-maintained content ✅ Scalable - Supports thousands of customers with one template update

This must be MVP because we're selling managed compliance, not document generation. The alternative (version debt) would create technical debt and trust damage that's difficult to recover from.

The lean MVP scope (simple UI, dashboard-only notifications, basic validation) gets us 80% of the value with 20% of the effort, while establishing the correct data foundation from day one.