Use Case 008: Configuration Version Control and Rollback

Overview

Property	Value
Use Case ID	UC-008
Use Case Name	Configuration Version Control and Rollback
Module	Configuration Management - Version Control
Priority	High
Status	Implemented
Version	1.0
Last Updated	January 30, 2026

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

Actor	Description	Role
Administrator	System administrator managing configurations	Primary
Configuration Manager	Automated system managing applications	Primary
System	Application Manager platform	Supporting
Database	PostgreSQL storing version history	Supporting
Audit Service	Service logging configuration changes	Supporting

Preconditions

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

Postconditions

Success Postconditions

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

Failure Postconditions

Original configuration remains unchanged
No partial versions created
Error logged with detailed diagnostic information
User notified of failure with actionable message
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, 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

Administrator Initiates Configuration Edit
- User navigates to configuration file in web UI
- System loads current configuration content
- System displays editor with syntax highlighting
Administrator Makes Changes
- User modifies configuration values
- User adds optional change description/comment
- User clicks "Save" or "Save & Deploy" button
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)
System Acquires Write Lock
- Acquire exclusive lock on configuration file record
- Prevent concurrent modifications
- Set lock timeout to 30 seconds
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
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
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)
System Updates Current Configuration
- Update ConfigFile record with new content
- Update LastModifiedAt timestamp
- Update LastModifiedBy user reference
- Increment version counter
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)
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 from v8 to v5? This will create 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, 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, RollbackFromVersion=8, 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:

Administrator navigates to version history
Administrator selects target version to rollback to
System displays version content preview
Administrator clicks "Rollback" button
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
Administrator confirms rollback
System validates:
- Target version exists and is accessible
- User has rollback permissions
- Target configuration is valid (schema check)
- No concurrent modifications in progress
System creates new version with content from target version
System marks new version as rollback (IsRollback = true)
System updates current configuration
System logs rollback in audit trail
System notifies affected applications (if webhooks configured)
System returns success with new version number
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, change stats, affected keys, both full contents API->>Web: Return comparison (JSON) Web->>Admin: Display split-view diff editor Note over Web,Admin: Left: Version 5 (older) Right: Version 8 (newer) Highlight: Added (green), Removed (red), Modified (yellow) Admin->>Web: Review changes Admin->>Web: Optionally rollback to v5

Steps:

Administrator opens version history
Administrator selects two versions to compare (checkboxes or UI selection)
System validates selection (must be exactly 2 versions)
System fetches both version contents from database
System determines older and newer version

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
   }
 }

System calculates statistics:
- Lines added: 2
- Lines removed: 2
- Lines unchanged: 45
- Keys modified: 2 (database.host, database.maxConnections)
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
Administrator reviews changes
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:

Two users edit the same configuration simultaneously
User A saves first, creating version N+1
User B attempts to save (still based on version N)
System detects version mismatch:
- User B's base version: N
- Current version in database: N+1

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"]
  }
}

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
User selects resolution strategy
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:

New version created successfully
System checks if retention policy is configured
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)
System queries current version count for this file
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
System calculates versions eligible for pruning
If archiving enabled:
- Move version records to ConfigFileVersionArchive table
- Update archivedAt timestamp
- Preserve all metadata and content
If archiving disabled:
- Soft delete: Set IsDeleted = true, DeletedAt = now
- Preserve record in database (for audit compliance)
System logs retention action in audit trail
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:

User saves configuration with errors
System performs syntax validation (step 3):
- JSON: Valid JSON structure
- YAML: Valid YAML structure
- XML: Well-formed XML
If syntax invalid:
- Return 400 Bad Request
- Include parse error details with line/column number
- Highlight error location in editor
- No version created
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
If schema invalid:
- Return 400 Bad Request with field-level errors
- Highlight invalid fields in editor
- Provide correction suggestions
- No version created
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
If rules violated:
- Return 400 Bad Request with rule descriptions
- Explain why validation failed
- Suggest corrections
- No version created
User corrects errors and resubmits
Process repeats until validation passes

Business Rules

Rule ID	Description	Enforcement
BR-001	Every configuration change creates a new version automatically	API business logic + database triggers
BR-002	Version numbers are sequential integers starting from 1	Database sequence + API logic
BR-003	Version content must be immutable after creation	Database constraints + API validation
BR-004	SHA-256 hash calculated and stored for every version	API business logic
BR-005	Rollback creates a new version (no in-place reversion)	API business logic
BR-006	Minimum 10 versions retained even with aggressive retention policy	Retention policy enforcement
BR-007	Version comparison requires both versions to exist and be accessible	API validation
BR-008	Concurrent modifications prevented via optimistic locking	Database row locking + version check
BR-009	Maximum version history: 1000 versions per file (then archiving)	Retention policy
BR-010	Diff generation limited to versions with <100KB content each	API performance limit
BR-011	Version descriptions limited to 500 characters	Data annotation + API validation
BR-012	Deleted versions moved to archive, not permanently removed	Soft delete + archival
BR-013	Rollback requires explicit user confirmation	UI confirmation dialog
BR-014	Version content size limited to 10MB	API validation

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 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

Metric	Target	Critical Threshold
Version creation time	< 200ms	< 1 second
Version history query (20 items)	< 300ms	< 1 second
Diff generation (< 10KB files)	< 500ms	< 2 seconds
Diff generation (< 100KB files)	< 2 seconds	< 5 seconds
Rollback operation time	< 1 second	< 3 seconds
Concurrent version operations	50/second	25/second
Version storage per file	< 50MB for 1000 versions	< 100MB
Database query time (version fetch)	< 100ms	< 500ms

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

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

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

Revision History

Version	Date	Author	Changes
1.0	2026-01-30	System Analyst	Initial use case documentation

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

Use Case 008: Configuration Version Control and Rollback

Overview

Description

Actors

Preconditions

Postconditions

Success Postconditions

Failure Postconditions

Triggers

Basic Flow (Happy Path)

Detailed Steps

Alternative Flows

Alt Flow 1: Rollback to Previous Version

Alt Flow 2: Compare Two Versions

Alt Flow 3: Version Conflict During Save

Alt Flow 4: Version Retention Policy Applied

Alt Flow 5: Invalid Configuration Detected on Save

Business Rules

Data Requirements

ConfigFileVersion Schema

Version Comparison Result

Rollback Request

Rollback Response

User Interface

Version History View

Diff Viewer (Side-by-Side Comparison)

Rollback Confirmation Dialog

Version Details Modal

API Endpoints

Get Version History

Get Specific Version Content

Compare Two Versions

Rollback to Previous Version

Create Manual Version Snapshot

Performance Requirements

Security Considerations

Version Audit Trail

Rollback Permissions

Version Content Security

Data Integrity

Access Control

Testing Scenarios

Test Case 1: Automatic Version Creation on Save

Test Case 2: Version History Pagination

Test Case 3: Compare Two Versions

Test Case 4: Successful Rollback

Test Case 5: Rollback Validation Failure

Test Case 6: Concurrent Version Creation Conflict

Test Case 7: Version Retention Policy Applied

Test Case 8: Diff Generation for Large Files

Test Case 9: Version Content Hash Validation

Test Case 10: Manual Version Snapshot

Monitoring and Analytics

Key Metrics to Track

Alerts

Dashboards

Related Use Cases

Notes and Assumptions

Revision History