Use Case 008: Configuration Version Control and Rollback

Overview

Description

This use case describes the comprehensive version control system for configuration files within the Application Manager. The system automatically creates versioned snapshots of configuration files whenever changes are made, maintains a complete audit trail of modifications, enables comparison between versions (diff), and provides the ability to roll back to previous configurations. This functionality is critical for maintaining configuration integrity, supporting compliance requirements, enabling safe experimentation, and providing disaster recovery capabilities.

Actors

Preconditions

1. Application Manager is running and accessible
2. Configuration Manager module is enabled
3. Database schema includes ConfigFileVersion table
4. User has appropriate permissions to view/modify configurations
5. Target configuration file exists in the system
6. Storage capacity available for version history
7. Audit logging is enabled

Postconditions

Success Postconditions

1. New version created with complete snapshot of configuration content
2. Version metadata recorded (author, timestamp, change description)
3. Previous version preserved with unique version number
4. Diff between versions calculated and stored
5. Version accessible for future comparison or rollback
6. Audit trail updated with version creation event
7. Version retention policy applied (if configured)
8. File integrity checksums calculated and stored

Failure Postconditions

1. Original configuration remains unchanged
2. No partial versions created
3. Error logged with detailed diagnostic information
4. User notified of failure with actionable message
5. Database transaction rolled back

Triggers

• User saves changes to a configuration file
• API client calls PUT/PATCH on configuration endpoint
• Automated configuration update (e.g., deployment pipeline)
• Administrator requests manual version creation
• Scheduled configuration backup
• Configuration import operation

Basic Flow (Happy Path)

sequenceDiagram
    actor Admin as Administrator
    participant Web as Web UI
    participant API as Configuration API
    participant VCS as Version Control Service
    participant DB as Database
    participant Storage as File Storage
    participant Audit as Audit Service

    Admin->>Web: Edit configuration file
    Web->>Admin: Display configuration editor
    
    Admin->>Web: Make changes and click Save
    Web->>API: PUT /api/v1/config-files/{fileId}
    
    API->>DB: Begin transaction
    API->>DB: Lock configuration file record
    
    API->>VCS: Create version before update
    VCS->>DB: Get current file content
    DB->>VCS: Return current content
    
    VCS->>VCS: Calculate content hash (SHA-256)
    VCS->>VCS: Determine next version number
    VCS->>VCS: Generate diff from previous version
    
    VCS->>DB: Insert ConfigFileVersion record
    Note over VCS,DB: Includes: version number, content,<br/>hash, author, timestamp, description
    DB->>VCS: Version created successfully
    
    VCS->>Storage: Store version content (optional)
    Storage->>VCS: Content stored
    
    API->>DB: Update current configuration file
    DB->>API: Configuration updated
    
    API->>Audit: Log version creation event
    Audit->>API: Event logged
    
    API->>DB: Commit transaction
    DB->>API: Transaction committed
    
    API->>Web: 200 OK (updated config + version info)
    Web->>Admin: Show success message with version number
    
    Note over Admin,Web: Administrator can now view version history
    
    Admin->>Web: Click "View Version History"
    Web->>API: GET /api/v1/config-files/{fileId}/versions
    API->>DB: Query version history
    DB->>API: Return version list
    API->>Web: Return versions (paginated)
    Web->>Admin: Display version timeline
    
    Admin->>Web: Select two versions to compare
    Web->>API: GET /api/v1/config-files/{fileId}/versions/compare
    API->>VCS: Generate diff between versions
    VCS->>DB: Fetch both version contents
    DB->>VCS: Return version contents
    VCS->>VCS: Calculate unified diff
    VCS->>API: Return diff result
    API->>Web: Return diff (JSON format)
    Web->>Admin: Display side-by-side diff viewer

Detailed Steps

1. Administrator Initiates Configuration Edit

   • User navigates to configuration file in web UI
   • System loads current configuration content
   • System displays editor with syntax highlighting

2. Administrator Makes Changes

   • User modifies configuration values
   • User adds optional change description/comment
   • User clicks "Save" or "Save & Deploy" button

3. System Validates Changes

   • Validate JSON/YAML/XML syntax (format-specific)
   • Check for required configuration keys
   • Validate data types and value constraints
   • Verify no circular dependencies
   • Check file size limits (max 10MB per file)

4. System Acquires Write Lock

   • Acquire exclusive lock on configuration file record
   • Prevent concurrent modifications
   • Set lock timeout to 30 seconds

5. System Creates Version Snapshot

   • Retrieve current configuration content
   • Determine next version number (sequential integer)
   • Calculate SHA-256 hash of content
   • Record current timestamp (UTC)
   • Capture user ID and username
   • Store optional change description

6. System Generates Diff

   • Compare new content with previous version
   • Generate unified diff format (similar to git diff)
   • Calculate change statistics (lines added/removed/modified)
   • Identify affected configuration keys
   • Store diff data with version record

7. System Persists Version

   • Insert ConfigFileVersion record with:
     • FileId (foreign key to ConfigFile)
     • VersionNumber (sequential, unique per file)
     • Content (full configuration snapshot)
     • ContentHash (SHA-256)
     • CreatedBy (user ID)
     • CreatedAt (UTC timestamp)
     • ChangeDescription (user-provided or auto-generated)
     • DiffFromPrevious (unified diff)
     • SizeInBytes (content size)
     • LinesCount (total lines)
     • IsRollback (false for normal versions)

8. System Updates Current Configuration

   • Update ConfigFile record with new content
   • Update LastModifiedAt timestamp
   • Update LastModifiedBy user reference
   • Increment version counter

9. System Logs Audit Event

   • Create audit log entry:
     • Event type: "ConfigurationVersionCreated"
     • File ID and file path
     • Version number
     • User ID and username
     • Timestamp
     • Change description
     • Content hash
     • Diff summary (lines changed)

10. System Releases Lock and Returns Success

    • Release configuration file lock
    • Commit database transaction
    • Return 200 OK with updated configuration and version info
    • Web UI displays success message with version number

Alternative Flows

Alt Flow 1: Rollback to Previous Version

sequenceDiagram
    actor Admin as Administrator
    participant Web as Web UI
    participant API as Configuration API
    participant VCS as Version Control Service
    participant DB as Database
    participant Audit as Audit Service
    participant App as Target Application

    Admin->>Web: Navigate to version history
    Web->>API: GET /api/v1/config-files/{fileId}/versions
    API->>DB: Query versions
    DB->>API: Return version list
    API->>Web: Return versions
    Web->>Admin: Display version timeline
    
    Admin->>Web: Select version v5 (previous)
    Web->>Admin: Show version details and content preview
    
    Admin->>Web: Click "Rollback to this version"
    Web->>Admin: Show confirmation dialog
    Note over Web,Admin: "Are you sure you want to rollback<br/>from v8 to v5? This will create<br/>a new version (v9) with v5's content."
    
    Admin->>Web: Confirm rollback
    Web->>API: POST /api/v1/config-files/{fileId}/rollback
    Note over Web,API: Body: { targetVersionNumber: 5,<br/>reason: "Reverting problematic changes" }
    
    API->>DB: Begin transaction
    API->>VCS: Execute rollback
    
    VCS->>DB: Fetch target version (v5) content
    DB->>VCS: Return v5 content
    
    VCS->>DB: Get current version (v8) for diff
    DB->>VCS: Return v8 content
    
    VCS->>VCS: Generate rollback diff (v8 -> v5)
    VCS->>VCS: Calculate next version number (v9)
    
    VCS->>DB: Create new version (v9) with v5 content
    Note over VCS,DB: Mark as IsRollback=true,<br/>RollbackFromVersion=8,<br/>RollbackToVersion=5
    DB->>VCS: Version v9 created
    
    VCS->>DB: Update ConfigFile with v5 content
    DB->>VCS: Configuration updated
    
    VCS->>Audit: Log rollback event
    Audit->>VCS: Event logged
    
    API->>DB: Commit transaction
    API->>Web: 200 OK (rollback successful)
    Web->>Admin: "Rolled back to version 5 (now v9)"
    
    opt Notify Application
        API->>App: POST /webhook/config-updated
        App->>API: 200 OK - will reload config
    end
    
    Admin->>Web: Verify configuration
    Web->>API: GET /api/v1/config-files/{fileId}
    API->>Web: Return current config (v9 = v5 content)
    Web->>Admin: Display current configuration

Steps:

1. Administrator navigates to version history
2. Administrator selects target version to rollback to
3. System displays version content preview
4. Administrator clicks "Rollback" button
5. System displays confirmation dialog with:
   • Current version number
   • Target version number
   • Version age and author
   • Preview of changes that will be reversed
   • Warning about creating new version
6. Administrator confirms rollback
7. System validates:
   • Target version exists and is accessible
   • User has rollback permissions
   • Target configuration is valid (schema check)
   • No concurrent modifications in progress
8. System creates new version with content from target version
9. System marks new version as rollback (IsRollback = true)
10. System updates current configuration
11. System logs rollback in audit trail
12. System notifies affected applications (if webhooks configured)
13. System returns success with new version number
14. Web UI displays confirmation and current config

Alt Flow 2: Compare Two Versions

sequenceDiagram
    actor Admin as Administrator
    participant Web as Web UI
    participant API as Configuration API
    participant VCS as Version Control Service
    participant DB as Database

    Admin->>Web: View version history
    Web->>API: GET /api/v1/config-files/{fileId}/versions
    API->>DB: Query versions
    DB->>API: Return versions
    API->>Web: Return version list
    Web->>Admin: Display version timeline with checkboxes
    
    Admin->>Web: Select version 5 (checkbox)
    Admin->>Web: Select version 8 (checkbox)
    Admin->>Web: Click "Compare Selected Versions"
    
    Web->>API: GET /api/v1/config-files/{fileId}/versions/compare?v1=5&v2=8
    
    API->>VCS: Generate comparison
    VCS->>DB: Fetch version 5 content
    VCS->>DB: Fetch version 8 content
    DB->>VCS: Return both version contents
    
    VCS->>VCS: Parse configuration format
    VCS->>VCS: Generate unified diff
    VCS->>VCS: Generate side-by-side diff
    VCS->>VCS: Identify changed keys
    VCS->>VCS: Calculate statistics
    
    VCS->>API: Return comparison result
    Note over VCS,API: Includes: unified diff,<br/>change stats, affected keys,<br/>both full contents
    
    API->>Web: Return comparison (JSON)
    
    Web->>Admin: Display split-view diff editor
    Note over Web,Admin: Left: Version 5 (older)<br/>Right: Version 8 (newer)<br/>Highlight: Added (green),<br/>Removed (red), Modified (yellow)
    
    Admin->>Web: Review changes
    Admin->>Web: Optionally rollback to v5

Steps:

1. Administrator opens version history
2. Administrator selects two versions to compare (checkboxes or UI selection)
3. System validates selection (must be exactly 2 versions)
4. System fetches both version contents from database
5. System determines older and newer version
6. System generates unified diff (like git diff):

   --- Version 5 (2026-01-20 10:30:00)
   +++ Version 8 (2026-01-30 14:45:00)
   @@ -10,7 +10,7 @@
    {
      "database": {
   -    "host": "localhost",
   +    "host": "db.production.com",
        "port": 5432,
   -    "maxConnections": 50
   +    "maxConnections": 100
      }
    }
   

7. System calculates statistics:
   • Lines added: 2
   • Lines removed: 2
   • Lines unchanged: 45
   • Keys modified: 2 (database.host, database.maxConnections)
8. System renders side-by-side diff in web UI:
   • Left panel: older version
   • Right panel: newer version
   • Color highlighting: green (added), red (removed), yellow (modified)
   • Synchronized scrolling
9. Administrator reviews changes
10. Administrator can optionally export diff or rollback

Alt Flow 3: Version Conflict During Save

flowchart TD
    A[User A edits config v5] --> B[User B edits same config v5]
    B --> C[User A saves first]
    C --> D[System creates v6 from A's changes]
    D --> E[User B attempts to save]
    E --> F{Check current version}
    F -->|Current is v6, User B has v5| G[Conflict detected]
    G --> H[Return 409 Conflict]
    H --> I[Display conflict resolution UI]
    I --> J{User B chooses}
    J -->|Force overwrite| K[Create v7 with B's changes]
    J -->|Merge manually| L[Show 3-way merge tool]
    J -->|Cancel| M[Discard B's changes]
    L --> N[User resolves conflicts]
    N --> O[Create v7 with merged content]

Steps:

1. Two users edit the same configuration simultaneously
2. User A saves first, creating version N+1
3. User B attempts to save (still based on version N)
4. System detects version mismatch:
   • User B's base version: N
   • Current version in database: N+1
5. System returns 409 Conflict response:

   {
     "error": "VersionConflict",
     "message": "Configuration was modified by another user",
     "yourBaseVersion": 5,
     "currentVersion": 6,
     "conflictingChanges": {
       "modifiedBy": "User A",
       "modifiedAt": "2026-01-30T14:30:00Z",
       "affectedKeys": ["database.host", "cache.ttl"]
     }
   }
   

6. Web UI displays conflict resolution options:
   • Option 1: View changes and merge manually
     • Display 3-way diff: base (v5), User A's version (v6), User B's version
     • Allow manual conflict resolution
     • Create new version with merged content
   • Option 2: Overwrite with my changes
     • Warning: "This will discard User A's changes"
     • Require confirmation
     • Create new version with User B's content
   • Option 3: Discard my changes
     • Reload current version (v6)
     • User B's unsaved changes lost
7. User selects resolution strategy
8. System proceeds based on selection

Alt Flow 4: Version Retention Policy Applied

flowchart TD
    A[New version created] --> B[Check retention policy]
    B --> C{Policy enabled?}
    C -->|No| D[Keep all versions]
    C -->|Yes| E{Check version count}
    E --> F{Exceeds limit?}
    F -->|No| G[Keep all versions]
    F -->|Yes| H[Identify versions to prune]
    H --> I[Apply retention rules]
    I --> J[Keep: Latest N versions]
    I --> K[Keep: All versions < 7 days old]
    I --> L[Keep: Versions marked as important]
    I --> M[Keep: Versions tagged for compliance]
    J --> N[Calculate eligible for deletion]
    K --> N
    L --> N
    M --> N
    N --> O[Archive or soft delete]
    O --> P{Archive option enabled?}
    P -->|Yes| Q[Move to archive storage]
    P -->|No| R[Soft delete from active table]
    Q --> S[Update audit log]
    R --> S

Steps:

1. New version created successfully
2. System checks if retention policy is configured
3. If policy enabled, system retrieves policy rules:
   • keepLatestCount: Keep most recent N versions (default: 50)
   • keepDaysRecent: Keep all versions younger than N days (default: 30)
   • keepMinimum: Always keep at least N versions (default: 10)
   • archiveOldVersions: Move to archive instead of delete (default: true)
4. System queries current version count for this file
5. If version count exceeds limits, system identifies candidates for pruning:
   • Exclude versions within keepDaysRecent
   • Exclude latest keepLatestCount versions
   • Exclude versions marked as IsImportant
   • Exclude versions tagged for compliance retention
6. System calculates versions eligible for pruning
7. If archiving enabled:
   • Move version records to ConfigFileVersionArchive table
   • Update archivedAt timestamp
   • Preserve all metadata and content
8. If archiving disabled:
   • Soft delete: Set IsDeleted = true, DeletedAt = now
   • Preserve record in database (for audit compliance)
9. System logs retention action in audit trail
10. System returns pruning summary (optional notification to admins)

Alt Flow 5: Invalid Configuration Detected on Save

flowchart TD
    A[User saves configuration] --> B[Syntax validation]
    B --> C{Valid syntax?}
    C -->|No| D[Return 400 - Syntax Error]
    C -->|Yes| E[Schema validation]
    E --> F{Matches schema?}
    F -->|No| G[Return 400 - Schema Violation]
    F -->|Yes| H[Business rules validation]
    H --> I{Passes rules?}
    I -->|No| J[Return 400 - Rule Violation]
    I -->|Yes| K[Create version and save]
    
    D --> L[Display syntax error with line number]
    G --> M[Display missing/invalid fields]
    J --> N[Display rule violation details]
    
    L --> O[User corrects and resubmits]
    M --> O
    N --> O
    O --> A

Steps:

1. User saves configuration with errors
2. System performs syntax validation (step 3):
   • JSON: Valid JSON structure
   • YAML: Valid YAML structure
   • XML: Well-formed XML
3. If syntax invalid:
   • Return 400 Bad Request
   • Include parse error details with line/column number
   • Highlight error location in editor
   • No version created
4. System performs schema validation:
   • Check required fields present
   • Validate data types (string, number, boolean, array, object)
   • Check value constraints (min, max, pattern, enum)
   • Validate nested structure
5. If schema invalid:
   • Return 400 Bad Request with field-level errors
   • Highlight invalid fields in editor
   • Provide correction suggestions
   • No version created
6. System performs business rules validation:
   • Check referential integrity (referenced IDs exist)
   • Validate cross-field dependencies
   • Check constraint rules (e.g., startDate < endDate)
   • Verify no circular references
7. If rules violated:
   • Return 400 Bad Request with rule descriptions
   • Explain why validation failed
   • Suggest corrections
   • No version created
8. User corrects errors and resubmits
9. Process repeats until validation passes

Business Rules

Data Requirements

ConfigFileVersion Schema

{
  "Id": "uuid-v4",
  "ConfigFileId": "uuid-v4 (foreign key to ConfigFile)",
  "VersionNumber": "integer (sequential, unique per file, starting at 1)",
  "Content": "text (full configuration snapshot)",
  "ContentHash": "string (SHA-256 hash, 64 chars)",
  "ContentFormat": "enum (JSON, YAML, XML, TOML, INI)",
  "SizeInBytes": "integer (content size in bytes)",
  "LinesCount": "integer (total lines in content)",
  "DiffFromPrevious": "text (unified diff format, nullable for v1)",
  "LinesAdded": "integer (diff stats)",
  "LinesRemoved": "integer (diff stats)",
  "LinesModified": "integer (diff stats)",
  "CreatedBy": "uuid-v4 (user ID, foreign key)",
  "CreatedByUsername": "string (denormalized for performance)",
  "CreatedAt": "datetime (UTC)",
  "ChangeDescription": "string (optional, max 500 chars)",
  "IsRollback": "boolean (true if created by rollback operation)",
  "RollbackFromVersion": "integer (nullable, source version number)",
  "RollbackToVersion": "integer (nullable, target version number)",
  "IsImportant": "boolean (flag to prevent pruning)",
  "Tags": "string[] (labels: production, hotfix, tested, etc.)",
  "IsDeleted": "boolean (soft delete flag)",
  "DeletedAt": "datetime (UTC, nullable)",
  "ArchivedAt": "datetime (UTC, nullable)"
}

Version Comparison Result

{
  "fileId": "uuid-v4",
  "fileName": "string",
  "filePath": "string",
  "olderVersion": {
    "versionNumber": 5,
    "createdBy": "john.doe",
    "createdAt": "2026-01-20T10:30:00Z",
    "contentHash": "abc123...",
    "sizeInBytes": 2048
  },
  "newerVersion": {
    "versionNumber": 8,
    "createdBy": "jane.smith",
    "createdAt": "2026-01-30T14:45:00Z",
    "contentHash": "def456...",
    "sizeInBytes": 2156
  },
  "statistics": {
    "linesAdded": 5,
    "linesRemoved": 3,
    "linesModified": 2,
    "linesUnchanged": 45,
    "totalChangePercent": 15.38
  },
  "unifiedDiff": "string (diff output in unified format)",
  "affectedKeys": [
    "database.host",
    "database.maxConnections",
    "cache.ttl"
  ],
  "sideBySideContent": {
    "older": "string (full content of version 5)",
    "newer": "string (full content of version 8)"
  }
}

Rollback Request

{
  "targetVersionNumber": 5,
  "reason": "string (required, explanation for rollback)",
  "skipValidation": false,
  "notifyApplications": true,
  "createBackup": true
}

Rollback Response

{
  "success": true,
  "currentVersion": 9,
  "rolledBackFrom": 8,
  "rolledBackTo": 5,
  "createdAt": "2026-01-30T15:00:00Z",
  "performedBy": "admin@example.com",
  "reason": "Reverting problematic changes",
  "newVersionHash": "xyz789...",
  "notifiedApplications": [
    "fee-manager",
    "value-manager"
  ],
  "message": "Successfully rolled back to version 5. New version 9 created."
}

User Interface

Version History View

┌────────────────────────────────────────────────────────────────┐
│  Configuration File: database-config.json                      │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                                │
│  Current Version: 8                                            │
│  Last Modified: Jan 30, 2026 14:45 UTC by jane.smith          │
│                                                                │
│  [View History] [Edit Configuration] [Export]                 │
└────────────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────────────┐
│  📜 Version History                                            │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                                │
│  Filter: [All Versions ▼] [Last 30 Days ▼] [All Users ▼]     │
│  Compare: [Select two versions to compare]                    │
│                                                                │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │ ☐ Version 8 • Current • Jan 30, 2026 14:45              │ │
│  │    👤 jane.smith                                         │ │
│  │    📝 Updated database connection pool settings          │ │
│  │    📊 +5 lines, -3 lines                                 │ │
│  │    [View] [Compare] [Download]                           │ │
│  │                                                           │ │
│  │ ☐ Version 7 • Jan 30, 2026 10:15                        │ │
│  │    👤 john.doe                                           │ │
│  │    📝 Changed host to production server                  │ │
│  │    📊 +2 lines, -2 lines                                 │ │
│  │    [View] [Compare] [Rollback]                           │ │
│  │                                                           │ │
│  │ ☐ Version 6 • Jan 29, 2026 16:30                        │ │
│  │    👤 admin                                              │ │
│  │    📝 Increased max connections limit                    │ │
│  │    📊 +1 lines, -1 lines                                 │ │
│  │    [View] [Compare] [Rollback]                           │ │
│  │                                                           │ │
│  │ ☐ Version 5 • Jan 20, 2026 10:30 • ⭐ Important         │ │
│  │    👤 john.doe                                           │ │
│  │    📝 Stable production configuration                    │ │
│  │    🏷️  Tags: production, tested, stable                │ │
│  │    📊 +12 lines, -5 lines                                │ │
│  │    [View] [Compare] [Rollback]                           │ │
│  │                                                           │ │
│  │ ☐ Version 4 • Jan 19, 2026 15:20                        │ │
│  │    👤 jane.smith                                         │ │
│  │    📝 Temporary testing configuration                    │ │
│  │    📊 +3 lines, -8 lines                                 │ │
│  │    [View] [Compare] [Rollback]                           │ │
│  │                                                           │ │
│  │ ↺ Version 3 • Jan 18, 2026 09:45 • Rollback            │ │
│  │    👤 admin                                              │ │
│  │    📝 Rolled back from v2 to v1 due to errors           │ │
│  │    📊 Restored previous state                            │ │
│  │    [View] [Compare]                                      │ │
│  └──────────────────────────────────────────────────────────┘ │
│                                                                │
│  [Load More Versions] (showing 6 of 8 total)                  │
└────────────────────────────────────────────────────────────────┘

Diff Viewer (Side-by-Side Comparison)

┌────────────────────────────────────────────────────────────────┐
│  Comparing Versions: Version 5 vs Version 8                    │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                                │
│  Version 5 (Jan 20, 2026)     │  Version 8 (Jan 30, 2026)    │
│  by john.doe                   │  by jane.smith               │
│  ─────────────────────────────┼──────────────────────────────│
│  {                             │  {                           │
│    "database": {               │    "database": {             │
│      "host": "localhost",      │      "host": "prod.db.com",  │ ◄ Modified
│      "port": 5432,             │      "port": 5432,           │
│      "username": "admin",      │      "username": "admin",    │
│      "maxConnections": 50,     │      "maxConnections": 100,  │ ◄ Modified
│                                │      "timeout": 30000,       │ ◄ Added
│    },                          │    },                        │
│    "cache": {                  │    "cache": {                │
│      "enabled": true,          │      "enabled": true,        │
│      "ttl": 3600               │      "ttl": 7200             │ ◄ Modified
│    },                          │    },                        │
│    "logging": {                │    "logging": {              │
│      "level": "info",          │      "level": "debug",       │ ◄ Modified
│      "console": true           │      "console": true,        │
│                                │      "file": "/var/log.txt"  │ ◄ Added
│    }                           │    }                         │
│  }                             │  }                           │
│  ─────────────────────────────┼──────────────────────────────│
│                                                                │
│  📊 Change Summary:                                            │
│      • 5 lines added    • 3 lines removed    • 2 modified     │
│      • Affected keys: database.host, database.maxConnections, │
│        database.timeout, cache.ttl, logging.level,            │
│        logging.file                                           │
│                                                                │
│  [⬅ Rollback to Version 5] [Export Diff] [Close]             │
└────────────────────────────────────────────────────────────────┘

Rollback Confirmation Dialog

┌────────────────────────────────────────────────────────────────┐
│  ⚠️  Confirm Configuration Rollback                            │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                                │
│  You are about to rollback the configuration:                 │
│                                                                │
│  📄 File: database-config.json                                │
│  📌 Current Version: 8 (Jan 30, 2026 14:45)                   │
│  ⬅  Target Version: 5 (Jan 20, 2026 10:30)                   │
│                                                                │
│  This will:                                                    │
│  ✓ Create a new version (9) with version 5's content          │
│  ✓ Keep all existing versions in history                      │
│  ✓ Update the active configuration immediately                │
│  ✓ Notify connected applications of the change                │
│  ✓ Create an audit trail entry                                │
│                                                                │
│  ⚠️  Warning: This action cannot be undone automatically.      │
│     You can rollback again if needed.                          │
│                                                                │
│  Changes that will be reversed:                               │
│  • database.host: prod.db.com → localhost                     │
│  • database.maxConnections: 100 → 50                          │
│  • database.timeout: removed                                  │
│  • cache.ttl: 7200 → 3600                                     │
│  • logging.level: debug → info                                │
│  • logging.file: removed                                      │
│                                                                │
│  Reason for rollback (required):                              │
│  ┌────────────────────────────────────────────────────────┐   │
│  │ Production issues with new connection pool settings    │   │
│  └────────────────────────────────────────────────────────┘   │
│                                                                │
│  ☑ Notify applications of configuration change                │
│  ☑ Create backup before rollback                              │
│                                                                │
│  [Cancel]  [Confirm Rollback]                                 │
└────────────────────────────────────────────────────────────────┘

Version Details Modal

┌────────────────────────────────────────────────────────────────┐
│  Version 5 Details                                       [✕]   │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                                │
│  📋 Metadata                                                   │
│  ─────────────────────────────────────────────────────────    │
│  Version Number:      5                                        │
│  Created:             Jan 20, 2026 10:30:45 UTC               │
│  Created By:          john.doe (John Doe)                     │
│  Description:         Stable production configuration          │
│  Content Hash:        abc123def456789... (SHA-256)            │
│  Size:                2,048 bytes (45 lines)                   │
│  Format:              JSON                                     │
│  Tags:                production, tested, stable               │
│  Is Important:        Yes ⭐                                   │
│                                                                │
│  📊 Change Statistics                                          │
│  ─────────────────────────────────────────────────────────    │
│  Lines Added:         12                                       │
│  Lines Removed:       5                                        │
│  Lines Modified:      3                                        │
│  Lines Unchanged:     25                                       │
│  Total Change:        44.4%                                    │
│                                                                │
│  🔍 Content Preview                                            │
│  ─────────────────────────────────────────────────────────    │
│  ┌────────────────────────────────────────────────────────┐   │
│  │ {                                                      │   │
│  │   "database": {                                        │   │
│  │     "host": "localhost",                               │   │
│  │     "port": 5432,                                      │   │
│  │     "username": "admin",                               │   │
│  │     "maxConnections": 50                               │   │
│  │   },                                                   │   │
│  │   "cache": {                                           │   │
│  │     "enabled": true,                                   │   │
│  │     "ttl": 3600                                        │   │
│  │   }                                                    │   │
│  │ }                                                      │   │
│  └────────────────────────────────────────────────────────┘   │
│                                                                │
│  [Download Full Content] [Compare with Current]               │
│  [Rollback to This Version] [Copy Hash] [Close]               │
└────────────────────────────────────────────────────────────────┘

API Endpoints

Get Version History

Endpoint: GET /api/v1/config-files/{fileId}/versions

Authentication: Required (Bearer token or API key)

Query Parameters:

• page (integer, default: 1) - Page number for pagination
• pageSize (integer, default: 20, max: 100) - Items per page
• fromDate (datetime, optional) - Filter versions created after date
• toDate (datetime, optional) - Filter versions created before date
• createdBy (string, optional) - Filter by user ID or username
• includeRollbacks (boolean, default: true) - Include rollback versions
• orderBy (enum: versionNumber|createdAt, default: versionNumber) - Sort field
• orderDirection (enum: asc|desc, default: desc) - Sort direction

Success Response: 200 OK

{
  "fileId": "550e8400-e29b-41d4-a716-446655440000",
  "fileName": "database-config.json",
  "currentVersion": 8,
  "totalVersions": 8,
  "page": 1,
  "pageSize": 20,
  "totalPages": 1,
  "versions": [
    {
      "id": "version-id-8",
      "versionNumber": 8,
      "createdBy": "jane.smith",
      "createdByName": "Jane Smith",
      "createdAt": "2026-01-30T14:45:00Z",
      "changeDescription": "Updated database connection pool settings",
      "contentHash": "def456...",
      "sizeInBytes": 2156,
      "linesCount": 48,
      "linesAdded": 5,
      "linesRemoved": 3,
      "isRollback": false,
      "isImportant": false,
      "tags": []
    },
    {
      "id": "version-id-7",
      "versionNumber": 7,
      "createdBy": "john.doe",
      "createdByName": "John Doe",
      "createdAt": "2026-01-30T10:15:00Z",
      "changeDescription": "Changed host to production server",
      "contentHash": "ghi789...",
      "sizeInBytes": 2050,
      "linesCount": 46,
      "linesAdded": 2,
      "linesRemoved": 2,
      "isRollback": false,
      "isImportant": false,
      "tags": []
    }
  ]
}

Error Responses:

404 Not Found - File not found

{
  "error": "FileNotFound",
  "message": "Configuration file not found",
  "fileId": "550e8400-e29b-41d4-a716-446655440000"
}

Get Specific Version Content

Endpoint: GET /api/v1/config-files/{fileId}/versions/{versionNumber}

Authentication: Required

Success Response: 200 OK

{
  "fileId": "550e8400-e29b-41d4-a716-446655440000",
  "fileName": "database-config.json",
  "versionNumber": 5,
  "createdBy": "john.doe",
  "createdByName": "John Doe",
  "createdAt": "2026-01-20T10:30:45Z",
  "changeDescription": "Stable production configuration",
  "contentHash": "abc123def456...",
  "contentFormat": "JSON",
  "sizeInBytes": 2048,
  "linesCount": 45,
  "content": "{\n  \"database\": {\n    \"host\": \"localhost\",\n    ...\n  }\n}",
  "diffFromPrevious": "--- Version 4\n+++ Version 5\n@@ -10,7 +10,7 @@\n...",
  "isRollback": false,
  "rollbackFromVersion": null,
  "rollbackToVersion": null,
  "isImportant": true,
  "tags": ["production", "tested", "stable"]
}

Compare Two Versions

Endpoint: GET /api/v1/config-files/{fileId}/versions/compare

Authentication: Required

Query Parameters:

• v1 (integer, required) - First version number (typically older)
• v2 (integer, required) - Second version number (typically newer)
• format (enum: unified|sideBySide|json, default: json) - Diff format

Success Response: 200 OK

{
  "fileId": "550e8400-e29b-41d4-a716-446655440000",
  "fileName": "database-config.json",
  "olderVersion": {
    "versionNumber": 5,
    "createdBy": "john.doe",
    "createdAt": "2026-01-20T10:30:00Z",
    "contentHash": "abc123...",
    "sizeInBytes": 2048
  },
  "newerVersion": {
    "versionNumber": 8,
    "createdBy": "jane.smith",
    "createdAt": "2026-01-30T14:45:00Z",
    "contentHash": "def456...",
    "sizeInBytes": 2156
  },
  "statistics": {
    "linesAdded": 5,
    "linesRemoved": 3,
    "linesModified": 2,
    "linesUnchanged": 45,
    "totalChangePercent": 15.38
  },
  "unifiedDiff": "--- Version 5 (2026-01-20 10:30:00)\n+++ Version 8 (2026-01-30 14:45:00)\n@@ -10,7 +10,7 @@\n   \"database\": {\n-    \"host\": \"localhost\",\n+    \"host\": \"prod.db.com\",\n     \"port\": 5432,\n...",
  "affectedKeys": [
    "database.host",
    "database.maxConnections",
    "database.timeout",
    "cache.ttl",
    "logging.level",
    "logging.file"
  ],
  "detailedChanges": [
    {
      "key": "database.host",
      "type": "modified",
      "oldValue": "localhost",
      "newValue": "prod.db.com"
    },
    {
      "key": "database.maxConnections",
      "type": "modified",
      "oldValue": 50,
      "newValue": 100
    },
    {
      "key": "database.timeout",
      "type": "added",
      "oldValue": null,
      "newValue": 30000
    }
  ]
}

Error Responses:

400 Bad Request - Invalid parameters

{
  "error": "InvalidParameters",
  "message": "Both v1 and v2 parameters are required",
  "details": {
    "v1": "missing",
    "v2": "provided"
  }
}

404 Not Found - Version not found

{
  "error": "VersionNotFound",
  "message": "One or both versions not found",
  "requestedVersions": [5, 99],
  "availableVersions": [1, 2, 3, 4, 5, 6, 7, 8]
}

Rollback to Previous Version

Endpoint: POST /api/v1/config-files/{fileId}/rollback

Authentication: Required (requires 'config:write' permission)

Request Body:

{
  "targetVersionNumber": 5,
  "reason": "Production issues with new connection pool settings",
  "skipValidation": false,
  "notifyApplications": true,
  "createBackup": true
}

Success Response: 200 OK

{
  "success": true,
  "fileId": "550e8400-e29b-41d4-a716-446655440000",
  "fileName": "database-config.json",
  "currentVersion": 9,
  "rolledBackFrom": 8,
  "rolledBackTo": 5,
  "createdAt": "2026-01-30T15:00:00Z",
  "performedBy": "admin@example.com",
  "reason": "Production issues with new connection pool settings",
  "newVersionHash": "xyz789...",
  "notifiedApplications": [
    {
      "applicationId": "fee-manager",
      "applicationName": "Fee Manager",
      "notificationStatus": "success",
      "notificationTimestamp": "2026-01-30T15:00:01Z"
    },
    {
      "applicationId": "value-manager",
      "applicationName": "Value Manager",
      "notificationStatus": "success",
      "notificationTimestamp": "2026-01-30T15:00:01Z"
    }
  ],
  "backupCreated": true,
  "backupLocation": "/backups/database-config-backup-20260130-150000.json",
  "message": "Successfully rolled back to version 5. New version 9 created."
}

Error Responses:

403 Forbidden - Insufficient permissions

{
  "error": "InsufficientPermissions",
  "message": "User does not have permission to rollback configurations",
  "requiredPermission": "config:write"
}

404 Not Found - Version not found

{
  "error": "VersionNotFound",
  "message": "Target version 99 does not exist",
  "fileId": "550e8400-e29b-41d4-a716-446655440000",
  "availableVersions": [1, 2, 3, 4, 5, 6, 7, 8]
}

409 Conflict - Concurrent modification

{
  "error": "ConcurrentModification",
  "message": "Configuration was modified during rollback operation",
  "currentVersion": 9,
  "expectedVersion": 8,
  "suggestion": "Please refresh and retry rollback"
}

Create Manual Version Snapshot

Endpoint: POST /api/v1/config-files/{fileId}/versions/snapshot

Authentication: Required

Request Body:

{
  "description": "Manual backup before major changes",
  "markAsImportant": true,
  "tags": ["pre-deployment", "backup", "production"]
}

Success Response: 201 Created

{
  "id": "version-id-9",
  "fileId": "550e8400-e29b-41d4-a716-446655440000",
  "versionNumber": 9,
  "createdBy": "admin",
  "createdAt": "2026-01-30T15:30:00Z",
  "description": "Manual backup before major changes",
  "contentHash": "manual123...",
  "sizeInBytes": 2156,
  "isImportant": true,
  "tags": ["pre-deployment", "backup", "production"],
  "message": "Manual snapshot created successfully"
}

Performance Requirements

Security Considerations

Version Audit Trail

• Every version creation logged with full user context
• Rollback operations logged with justification
• Version access (read) operations logged for sensitive configs
• Audit trail immutable and tamper-evident
• Audit retention policy separate from version retention

Rollback Permissions

• Rollback requires explicit 'config:rollback' permission
• Critical configurations require additional approval workflow
• Production environment rollbacks logged and alerted
• Multi-factor authentication required for production rollbacks (optional)

Version Content Security

• Sensitive data in versions encrypted at rest
• API tokens and passwords masked in version history UI
• Version content access requires 'config:read' permission
• Deleted versions remain accessible to auditors only
• Export operations logged and rate-limited

Data Integrity

• SHA-256 hash verification on version retrieval
• Hash mismatch triggers integrity violation alert
• Version content immutability enforced at database level
• Checksums validated on rollback operations
• Corruption detection and automatic notification

Access Control

• Version history visible only to authorized users
• Role-based access control (RBAC) for version operations
• Sensitive configurations have restricted version access
• Version comparison requires read access to both versions
• API rate limiting: 100 version operations per user per minute

Testing Scenarios

Test Case 1: Automatic Version Creation on Save

Given: User edits configuration file
When: User saves changes
Then: New version created automatically, version number incremented, hash calculated
Verify: Version record in database, content snapshot stored, diff generated, audit log entry created

Test Case 2: Version History Pagination

Given: Configuration file with 100 versions
When: User requests version history with page=1, pageSize=20
Then: Most recent 20 versions returned, pagination metadata included
Verify: Correct versions returned, proper sorting (newest first), total count accurate

Test Case 3: Compare Two Versions

Given: Two different versions of a configuration file
When: User requests comparison between v5 and v8
Then: Unified diff generated, statistics calculated, affected keys identified
Verify: Diff accurate, line counts correct, all changes captured

Test Case 4: Successful Rollback

Given: Current version is v8, target rollback version is v5
When: User initiates rollback with valid reason
Then: New version v9 created with v5 content, audit log updated, applications notified
Verify: Current config matches v5, new version marked as rollback, notification delivered

Test Case 5: Rollback Validation Failure

Given: Target rollback version contains invalid configuration
When: User attempts rollback without skipping validation
Then: Rollback rejected with validation error
Verify: Current configuration unchanged, error message descriptive, no version created

Test Case 6: Concurrent Version Creation Conflict

Given: Two users editing same configuration simultaneously
When: User B saves after User A has already saved
Then: 409 Conflict returned to User B
Verify: User B's changes not lost, conflict resolution options presented, version integrity maintained

Test Case 7: Version Retention Policy Applied

Given: Configuration has 60 versions, policy limits to 50
When: New version created
Then: Oldest eligible versions archived or deleted per policy
Verify: Version count at or below limit, important versions retained, audit log updated

Test Case 8: Diff Generation for Large Files

Given: Configuration file with 10,000 lines
When: User compares two large versions
Then: Diff generated within performance threshold or partial diff returned
Verify: Response time acceptable, memory usage reasonable, user notified if truncated

Test Case 9: Version Content Hash Validation

Given: Version stored in database
When: Version content retrieved
Then: Hash recalculated and compared with stored hash
Verify: Hash matches, integrity confirmed, corruption detected if mismatch

Test Case 10: Manual Version Snapshot

Given: User wants to create backup before major changes
When: User creates manual snapshot with description and tags
Then: New version created without changing current config
Verify: Version marked as important, tags applied, retention policy respects flag

Monitoring and Analytics

Key Metrics to Track

• Version Creation Rate: Versions created per hour/day/week
• Average Versions Per File: Total versions / Total files
• Rollback Frequency: Number of rollback operations per day
• Rollback Success Rate: Successful rollbacks / Total rollback attempts
• Diff Generation Time: Average time to generate diffs (by file size)
• Version Storage Growth: Storage consumed by versions over time
• Version Pruning Activity: Versions archived/deleted per retention policy
• Concurrent Modification Conflicts: Number of version conflicts per day
• Most Rolled-Back Files: Files with highest rollback frequency
• Version History Query Performance: Average query response time

Alerts

• Rollback failure rate > 5% in 1 hour
• Version storage exceeds 80% of allocated quota
• Hash validation failure (data corruption detected)
• Concurrent modification conflict rate > 10% in 1 hour
• Version creation latency > 2 seconds (95th percentile)
• Excessive rollback activity (> 10 rollbacks in 1 hour)
• Version retention policy failing to execute
• Large file diff generation timeout (> 10 seconds)

Dashboards

• Version Activity Dashboard:
  • Timeline of version creations
  • Rollback operations over time
  • Top users by version activity
  • Most frequently modified files
• Storage Dashboard:
  • Version storage usage by file
  • Total versions vs archived versions
  • Storage growth trend
  • Retention policy effectiveness
• Performance Dashboard:
  • Version operation latency (p50, p95, p99)
  • Diff generation performance by file size
  • Database query performance
  • API endpoint response times

Related Use Cases

• UC-007: Configuration File Management and Editing
• UC-009: Configuration Deployment and Application Notification
• UC-010: Configuration Import and Export
• UC-011: Configuration Validation and Schema Management
• UC-012: Configuration Audit Trail and Compliance Reporting
• UC-013: Configuration Backup and Disaster Recovery

Notes and Assumptions

1. Immutable Versions: Once created, version content cannot be modified (only metadata like tags)
2. Sequential Versioning: Version numbers are sequential integers starting at 1, unique per file
3. Rollback Creates New Version: Rollback never modifies existing versions, always creates new one
4. Storage Considerations: Version content stored in database for fast access; optionally archived to object storage (S3, Azure Blob) for old versions
5. Retention Policy Flexibility: Policy configurable per file, file category, or globally
6. Diff Algorithm: Uses standard unified diff algorithm (similar to git diff)
7. Large File Handling: Files > 100KB may have diff generation deferred or truncated
8. Concurrent Access: Optimistic locking with version number check prevents conflicts
9. Compliance: Version history supports regulatory requirements (SOC 2, GDPR, HIPAA)
10. Future Enhancement: Git-like branching/merging for complex configuration workflows

Revision History

Document Owner: Platform Architecture Team
Stakeholders: Product Management, Engineering, Operations, Compliance
Review Cycle: Quarterly or as needed for major changes