Use Case 007: Configuration File Management

Overview

Description

This use case describes the comprehensive management of configuration files and folders within the Riptide Application Manager. The system provides a Unix-inspired hierarchical file structure for storing, organizing, and managing configuration files for applications, workflows, and services. Users can create, edit, move, rename, and delete configuration files and folders through a web-based interface with real-time validation, conflict detection, and version control capabilities.

Actors

Preconditions

1. Application Manager is running and accessible
2. User is authenticated with appropriate permissions
3. File system storage is properly configured and accessible
4. Validation rules are defined for supported file formats
5. Database contains configuration file metadata tables
6. Backup service is configured and operational

Postconditions

Success Postconditions

1. Configuration files and folders created/modified/deleted as requested
2. File metadata stored in database with version history
3. File validation completed and results stored
4. File content persisted to storage backend
5. Changes logged in audit trail
6. Dependent applications notified of configuration changes (if applicable)
7. Backups created for modified/deleted files

Failure Postconditions

1. Invalid operations rejected with descriptive error messages
2. No partial changes persisted (atomic operations)
3. Original state maintained if validation fails
4. Error details logged for troubleshooting
5. User notified of specific failure reasons

Triggers

• User clicks "New File" or "New Folder" button in UI
• User selects file to edit content
• User drags and drops files in tree view (move operation)
• User right-clicks file/folder and selects rename/delete
• User uploads configuration file from local system
• API client calls configuration management endpoints
• Scheduled job validates configuration files
• Application requests configuration file content

Basic Flow (Happy Path)

Detailed Steps

1. User Navigates to Configuration Management

   • User logs into Application Manager
   • User clicks "Configuration Files" in navigation menu
   • System displays hierarchical tree view of all folders and files
   • Root folders visible: /apps, /workflows, /services, /shared

2. User Creates New Folder

   • User right-clicks parent folder or clicks "New Folder" button
   • System displays folder creation dialog
   • User enters folder name (e.g., "fee-manager")
   • System validates folder name (alphanumeric, hyphens, underscores only)
   • System checks parent path + folder name doesn't exist
   • System creates folder metadata record
   • System refreshes tree view showing new folder

3. User Creates New Configuration File

   • User selects target folder in tree
   • User clicks "New File" button or right-clicks folder
   • System displays file creation dialog with fields:
     • File name (required)
     • File type/format dropdown (JSON, XML, YAML, TOML, Properties, Text)
     • Description (optional)
     • Tags (optional)
   • User enters filename (e.g., "database.json")
   • System validates filename and extension match
   • System constructs full path (folder path + filename)
   • System checks file doesn't already exist at path
   • System creates file metadata record with:
     • Unique ID (GUID)
     • Path (Unix-style: /apps/fee-manager/database.json)
     • Type/Format
     • Size (0 initially)
     • Created/Modified timestamps
     • Owner user ID
   • System creates empty file in storage backend
   • System opens file in editor pane

4. User Edits File Content

   • System displays code editor with syntax highlighting based on file type
   • User types or pastes configuration content
   • System performs real-time syntax validation (if format supports)
   • User clicks "Save" button or presses Ctrl+S
   • System collects current editor content

5. System Validates Content

   • System identifies file format from metadata
   • System invokes appropriate validator:
     • JSON: Parse with System.Text.Json, check schema if defined
     • XML: Parse with System.Xml, validate against XSD if provided
     • YAML: Parse with YamlDotNet library
     • TOML: Parse with TOML parser
     • Properties: Check key=value format
     • Text: No validation required
   • If validation fails:
     • System collects error details (line number, message)
     • System returns validation errors to UI
     • UI displays errors inline in editor
     • Content NOT saved
   • If validation succeeds:
     • Proceed to save content

6. System Persists File Content

   • System calculates file size in bytes
   • System writes content to storage backend (local filesystem or object storage)
   • System updates file metadata:
     • Size (bytes)
     • ModifiedAt (current UTC timestamp)
     • ModifiedBy (user ID)
     • ValidationStatus (Valid/Invalid)
     • ContentHash (SHA-256 for change detection)
   • System creates version history record:
     • FileId
     • Version number (auto-incremented)
     • Content snapshot (optionally compressed)
     • ModifiedBy
     • ModifiedAt
     • ChangeDescription (optional user comment)
   • System commits database transaction

7. System Creates Backup

   • System creates backup entry with previous content
   • Backup includes full file metadata and content
   • Retention policy applied (keep last 30 versions by default)

8. System Logs Audit Trail

   • System records audit entry:
     • Action: "FileContentUpdated"
     • UserId
     • FileId and Path
     • Timestamp
     • IP Address
     • Changes summary (size delta, validation status)

9. System Returns Success

   • API returns 200 OK with updated metadata
   • UI displays success message: "File saved successfully"
   • UI updates file tree with new size/modified date

10. User Browses and Manages Files

    • User can expand/collapse folders in tree view
    • User can filter files by type, name, or tags
    • User can sort by name, size, or modified date
    • User can search files by path or content (if indexed)
    • User can view file properties (metadata panel)
    • User can download files to local system

Alternative Flows

Alt Flow 1: File Path Conflict (Create/Rename)

Steps:

1. User attempts to create/rename/move file to path that already exists
2. System detects path conflict during validation
3. System returns 409 Conflict status
4. Response includes:
   • Error message: "A file already exists at path: /apps/fee-manager/config.json"
   • Existing file metadata (ID, size, modified date)
   • Suggestions: "Choose a different name or delete the existing file"
5. UI displays conflict dialog with options:
   • Cancel operation
   • Choose different name/path
   • Overwrite existing file (requires confirmation)
6. If user chooses overwrite:
   • System creates backup of existing file
   • System replaces content and metadata
   • Audit trail records overwrite action

Alt Flow 2: Invalid File Content (Validation Failure)

Steps:

1. User edits file content and clicks Save
2. System validates content based on file format (step 5)
3. Validation service detects errors:
   • JSON: Syntax error, missing comma, invalid UTF-8
   • XML: Malformed tags, invalid characters, schema violation
   • YAML: Indentation error, invalid syntax
   • TOML: Parse error, invalid value types
4. System returns 400 Bad Request with detailed errors:

   {
     "error": "ValidationError",
     "message": "Configuration file content is invalid",
     "validationErrors": [
       {
         "line": 15,
         "column": 22,
         "message": "Expected ',' or '}' after property value",
         "severity": "error"
       }
     ]
   }
   

5. UI highlights error locations in editor
6. Content NOT saved (original content preserved)
7. User corrects errors and saves again
8. Validation succeeds and file is saved

Alt Flow 3: Large File Handling

Steps:

1. User attempts to upload or save file exceeding size limits
2. System checks file size against thresholds:
   • < 1 MB: Normal processing
   • 1-10 MB: Warning displayed, requires confirmation
   • > 10 MB: Rejected immediately
3. For files 1-10 MB:
   • System displays warning: "This is a large file (5.2 MB). Saving may take time and slow down the editor."
   • User can proceed or cancel
   • If proceeding, system uses streaming approach to avoid memory issues
   • Validation may be limited (e.g., syntax check only, no schema validation)
4. For files > 10 MB:
   • System returns 413 Payload Too Large
   • Error message: "Configuration file exceeds maximum size of 10 MB. Consider splitting into multiple files or using external storage."
   • Suggest alternatives:
     • Split configuration into multiple smaller files
     • Use file references/imports
     • Store in external object storage and reference by URL

Alt Flow 4: Concurrent Edit Conflict

Steps:

1. Multiple users open same file simultaneously
2. Each receives current version with ETag header
3. User A saves changes first:
   • Provides ETag in If-Match header
   • System verifies ETag matches current version
   • Content saved, version incremented, new ETag generated
4. User B attempts to save changes:
   • Provides original ETag in If-Match header
   • System detects ETag mismatch (file was modified)
   • System returns 409 Conflict with message:
     • "File has been modified by another user. Please refresh and merge your changes."
     • Includes: LastModifiedBy, LastModifiedAt, current version
5. User B must:
   • Refresh to get latest content
   • Review differences between their version and latest
   • Manually merge changes or choose to overwrite
   • Save again with updated ETag
6. Alternatively, system can offer three-way merge UI showing:
   • Original content (base version)
   • User B's changes
   • User A's changes (current version)
   • Merged result (user confirms)

Alt Flow 5: Delete File or Folder with Confirmation

Steps:

1. User selects file or folder to delete
2. System displays confirmation dialog:
   • For single file: "Delete [filename]? This action can be undone within 30 days."
   • For folder: "Delete [foldername] and all its contents (X files, Y subfolders)?"
3. If user cancels, operation aborted
4. If user confirms:
   • System checks for dependencies (files referencing this file)
   • If dependencies exist, warn user or prevent deletion
   • System creates backup before deletion
   • System performs soft delete (sets DeletedAt timestamp, preserves record)
   • System marks storage file for deletion or moves to recycle bin
   • System logs deletion in audit trail
5. User can restore deleted files from "Recycle Bin" view within retention period
6. After retention period (30 days), permanent deletion occurs via background job

Alt Flow 6: Move/Rename File or Folder

Steps:

1. Rename Operation:

   • User right-clicks file and selects "Rename"
   • System displays inline editor or dialog with current name
   • User enters new name
   • System validates name format (no special chars, valid extension)
   • System constructs new path (same parent folder + new name)
   • System checks new path doesn't exist (prevent collision)
   • System renames file in storage backend
   • System updates file metadata with new name and path
   • System logs rename operation in audit trail
   • UI refreshes to show new name

2. Move Operation:

   • User drags file to different folder in tree view
   • System shows drop indicator when hovering over target folder
   • User drops file
   • System determines target folder ID
   • System constructs new path (target folder path + filename)
   • System checks new path doesn't exist
   • System moves file in storage backend
   • System updates file metadata (path, parent folder ID)
   • System updates file tree structure
   • System logs move operation in audit trail
   • UI updates tree view showing file in new location

3. Move Folder:

   • Similar to file move but applies recursively
   • All descendant files and subfolders updated
   • Path updates cascade through tree
   • Transaction ensures atomicity

Business Rules

Data Requirements

ConfigFile Record

{
  "id": "uuid-v4",
  "name": "string (required, 1-255 chars)",
  "path": "string (required, unique, Unix-style path)",
  "parentFolderId": "uuid-v4 (nullable, foreign key)",
  "type": "enum (JSON, XML, YAML, TOML, Properties, Text)",
  "description": "string (optional, max 1000 chars)",
  "size": "integer (bytes)",
  "contentHash": "string (SHA-256 hash)",
  "validationStatus": "enum (Valid, Invalid, NotValidated)",
  "validationErrors": "json (nullable, array of error objects)",
  "tags": "json (array of strings)",
  "isSystem": "boolean (default: false)",
  "isReadOnly": "boolean (default: false)",
  "createdBy": "uuid-v4 (user ID)",
  "createdAt": "datetime (UTC)",
  "modifiedBy": "uuid-v4 (user ID)",
  "modifiedAt": "datetime (UTC)",
  "deletedAt": "datetime (UTC, nullable)",
  "deletedBy": "uuid-v4 (user ID, nullable)",
  "version": "integer (auto-incrementing)",
  "metadata": "json (custom key-value pairs)"
}

ConfigFolder Record

{
  "id": "uuid-v4",
  "name": "string (required, 1-255 chars)",
  "path": "string (required, unique, Unix-style path)",
  "parentFolderId": "uuid-v4 (nullable, foreign key)",
  "description": "string (optional, max 1000 chars)",
  "isSystem": "boolean (default: false)",
  "createdBy": "uuid-v4 (user ID)",
  "createdAt": "datetime (UTC)",
  "modifiedBy": "uuid-v4 (user ID)",
  "modifiedAt": "datetime (UTC)",
  "deletedAt": "datetime (UTC, nullable)",
  "deletedBy": "uuid-v4 (user ID, nullable)"
}

ConfigFileVersion Record

{
  "id": "uuid-v4",
  "fileId": "uuid-v4 (foreign key)",
  "versionNumber": "integer",
  "content": "text (compressed/encrypted)",
  "contentHash": "string (SHA-256)",
  "size": "integer (bytes)",
  "changeDescription": "string (optional, user-provided)",
  "createdBy": "uuid-v4 (user ID)",
  "createdAt": "datetime (UTC)",
  "expiresAt": "datetime (UTC, for cleanup)"
}

ConfigFileBackup Record

{
  "id": "uuid-v4",
  "fileId": "uuid-v4 (foreign key)",
  "originalPath": "string",
  "content": "text",
  "metadata": "json (file metadata snapshot)",
  "backupReason": "enum (Deletion, Overwrite, Manual)",
  "createdBy": "uuid-v4 (user ID)",
  "createdAt": "datetime (UTC)",
  "expiresAt": "datetime (UTC)",
  "restoredAt": "datetime (UTC, nullable)",
  "restoredBy": "uuid-v4 (user ID, nullable)"
}

User Interface

Configuration File Tree View

┌─────────────────────────────────────────────────────────────────────┐
│  Configuration Files                                    [+ New] [↻] │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                                       │
│  Search: [________________]  Type: [All ▾]  Tags: [All ▾]            │
│                                                                       │
│  Tree View                          │ File Editor                    │
│  ──────────────────────────────────────────────────────────────     │
│  📁 /                               │                                │
│    📁 apps (8 files)                │  database.json                 │
│      📁 fee-manager                 │  ━━━━━━━━━━━━━━━━━━━━━━       │
│        📄 appsettings.json   5.2KB  │                                │
│        📄 database.json      2.1KB ◀│  {                             │
│        📄 logging.json       1.5KB  │    "connectionString": "...",  │
│      📁 value-manager               │    "provider": "PostgreSQL",   │
│        📄 appsettings.json   4.8KB  │    "maxPoolSize": 100,         │
│        📄 database.json      2.3KB  │    "commandTimeout": 30        │
│    📁 workflows (12 files)          │  }                             │
│      📁 approval-workflow           │                                │
│        📄 workflow.yaml      8.2KB  │  ✓ Valid JSON                  │
│        📄 mappings.json      3.1KB  │                                │
│    📁 services (5 files)            │  Modified: Jan 30, 2026 10:45  │
│      📄 ontologer.json       6.5KB  │  Size: 2.1 KB                  │
│      📄 namecheck.json       4.2KB  │  Version: 5                    │
│    📁 shared (3 files)              │                                │
│      📄 common.json          3.8KB  │  [Save] [Validate] [History]   │
│                                     │                                │
│  ──────────────────────────────────────────────────────────────     │
│  Right-click context menu:          │                                │
│  • New File                         │  File Properties Panel:        │
│  • New Folder                       │  ━━━━━━━━━━━━━━━━━━━━━       │
│  • Rename                           │  Name: database.json           │
│  • Move                             │  Path: /apps/fee-manager       │
│  • Delete                           │  Type: JSON                    │
│  • Copy Path                        │  Created: Jan 15, 2026         │
│  • Download                         │  Modified: Jan 30, 2026        │
│  • Properties                       │  Size: 2,134 bytes             │
│                                     │  Hash: a3f2c1...               │
│                                     │  Tags: production, database    │
│                                     │  Validation: ✓ Valid           │
│                                     │                                │
└─────────────────────────────────────────────────────────────────────┘

File Creation Dialog

┌─────────────────────────────────────────────────────┐
│  Create New Configuration File                      │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  Parent Folder:                                     │
│  📁 /apps/fee-manager                               │
│                                                     │
│  File Name: *                                       │
│  ┌─────────────────────────────────────────────┐   │
│  │ appsettings.json                            │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  File Type: *                                       │
│  ┌─────────────────────────────────────────────┐   │
│  │ JSON                                     ▾  │   │
│  └─────────────────────────────────────────────┘   │
│  Options: XML, YAML, TOML, Properties, Text         │
│                                                     │
│  Description:                                       │
│  ┌─────────────────────────────────────────────┐   │
│  │ Application settings for fee manager        │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  Tags (comma-separated):                            │
│  ┌─────────────────────────────────────────────┐   │
│  │ production, settings                        │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  Full Path:                                         │
│  /apps/fee-manager/appsettings.json                 │
│                                                     │
│  ┌──────────────┐                                  │
│  │   Create     │  [Cancel]                        │
│  └──────────────┘                                  │
│                                                     │
└─────────────────────────────────────────────────────┘

File Editor with Validation

┌─────────────────────────────────────────────────────────────────────┐
│  /apps/fee-manager/database.json                [Save] [Validate]   │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                                       │
│  1  {                                                                 │
│  2    "provider": "PostgreSQL",                                       │
│  3    "connectionString": "Host=localhost;Database=fees;...",         │
│  4    "maxPoolSize": 100,                                             │
│  5    "commandTimeout": 30,                                           │
│  6    "retryPolicy": {                                                │
│  7      "maxRetries": 3,                                              │
│  8      "delaySeconds": 5                                             │
│  9    },                                                              │
│ 10    "logging": {                                                    │
│ 11      "logCommands": true,                                          │
│ 12      "logLevel": "Information"                                     │
│ 13    }                                                               │
│ 14  }                                                                 │
│ 15                                                                    │
│                                                                       │
│  ✓ Valid JSON - No errors detected                                   │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│  Size: 2.1 KB  │  Lines: 14  │  Modified: Unsaved changes *          │
│                                                                       │
│  [History] [Download] [Copy Path] [Properties]                       │
│                                                                       │
│  Tabs: database.json * │ logging.json │ appsettings.json             │
└─────────────────────────────────────────────────────────────────────┘

With Validation Errors:
┌─────────────────────────────────────────────────────────────────────┐
│  /apps/fee-manager/database.json                [Save] [Validate]   │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                                       │
│  1  {                                                                 │
│  2    "provider": "PostgreSQL",                                       │
│  3    "connectionString": "Host=localhost;Database=fees;...",         │
│  4    "maxPoolSize": 100                                              │
│  5    "commandTimeout": 30,  ← ❌ Expected ',' after property value   │
│  6    "retryPolicy": {                                                │
│  7      "maxRetries": 3,                                              │
│  8      "delaySeconds": 5                                             │
│  9    },                                                              │
│ 10  }                            ← ❌ Unexpected token                │
│                                                                       │
│  ❌ Validation Failed - 2 errors                                      │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│  Line 5, Column 26: Expected ',' after property value                │
│  Line 10, Column 3: Unexpected token '}'                              │
│                                                                       │
│  ⚠ File cannot be saved until errors are fixed                       │
└─────────────────────────────────────────────────────────────────────┘

File Properties Panel

┌─────────────────────────────────────────────────────┐
│  File Properties                                    │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  Name:                                              │
│  database.json                                      │
│                                                     │
│  Full Path:                                         │
│  /apps/fee-manager/database.json                    │
│  [Copy Path]                                        │
│                                                     │
│  Type: JSON                                         │
│  Size: 2,134 bytes (2.1 KB)                         │
│                                                     │
│  Created:                                           │
│  Jan 15, 2026 at 14:30:00 UTC                       │
│  By: john.admin@example.com                         │
│                                                     │
│  Last Modified:                                     │
│  Jan 30, 2026 at 10:45:22 UTC                       │
│  By: jane.dev@example.com                           │
│                                                     │
│  Current Version: 5                                 │
│  [View Version History]                             │
│                                                     │
│  Content Hash:                                      │
│  a3f2c1b8d4e5f6a7b8c9d0e1f2a3b4c5                   │
│                                                     │
│  Validation Status:                                 │
│  ✓ Valid - Last checked Jan 30, 2026 10:45         │
│                                                     │
│  Tags:                                              │
│  [production] [database] [critical]                 │
│  [+ Add Tag]                                        │
│                                                     │
│  Description:                                       │
│  Database connection settings for fee               │
│  manager production environment.                    │
│  [Edit]                                             │
│                                                     │
│  Metadata:                                          │
│  • Referenced By: 3 applications                    │
│  • Last Validated: 2 minutes ago                    │
│  • Backup Available: Yes (last 30 days)             │
│                                                     │
│  Actions:                                           │
│  [Rename] [Move] [Download] [Delete]                │
│                                                     │
└─────────────────────────────────────────────────────┘

API Endpoints

Get Configuration Tree

Endpoint: GET /api/v1/config/tree

Authentication: Required (Bearer token)

Query Parameters:

• rootPath (optional): Root path to start tree (default: /)
• maxDepth (optional): Maximum depth to retrieve (default: 5)
• includeDeleted (optional): Include soft-deleted items (default: false)

Success Response: 200 OK

{
  "rootPath": "/",
  "tree": [
    {
      "id": "folder-id-apps",
      "name": "apps",
      "path": "/apps",
      "type": "folder",
      "fileCount": 8,
      "folderCount": 2,
      "children": [
        {
          "id": "folder-id-fee-mgr",
          "name": "fee-manager",
          "path": "/apps/fee-manager",
          "type": "folder",
          "fileCount": 3,
          "folderCount": 0,
          "children": [
            {
              "id": "file-id-123",
              "name": "database.json",
              "path": "/apps/fee-manager/database.json",
              "type": "file",
              "format": "JSON",
              "size": 2134,
              "modifiedAt": "2026-01-30T10:45:22Z",
              "validationStatus": "Valid"
            }
          ]
        }
      ]
    },
    {
      "id": "folder-id-workflows",
      "name": "workflows",
      "path": "/workflows",
      "type": "folder",
      "fileCount": 12,
      "folderCount": 3,
      "children": []
    }
  ]
}

Create Configuration Folder

Endpoint: POST /api/v1/config/folders

Authentication: Required (Bearer token)

Request Body:

{
  "name": "fee-manager",
  "parentFolderId": "folder-id-apps",
  "description": "Fee Manager configuration files"
}

Success Response: 201 Created

{
  "id": "folder-id-fee-mgr",
  "name": "fee-manager",
  "path": "/apps/fee-manager",
  "parentFolderId": "folder-id-apps",
  "description": "Fee Manager configuration files",
  "createdBy": "user-id-123",
  "createdAt": "2026-01-30T10:00:00Z",
  "modifiedAt": "2026-01-30T10:00:00Z"
}

Error Responses:

400 Bad Request - Invalid folder name

{
  "error": "ValidationError",
  "message": "Folder name contains invalid characters",
  "invalidCharacters": ["*", "/"]
}

409 Conflict - Path already exists

{
  "error": "PathConflict",
  "message": "A folder already exists at path: /apps/fee-manager",
  "existingFolderId": "folder-id-xyz"
}

Create Configuration File

Endpoint: POST /api/v1/config/files

Authentication: Required (Bearer token)

Request Body:

{
  "name": "database.json",
  "parentFolderId": "folder-id-fee-mgr",
  "type": "JSON",
  "description": "Database connection settings",
  "tags": ["production", "database"],
  "content": "{\n  \"provider\": \"PostgreSQL\"\n}",
  "metadata": {
    "environment": "production",
    "owner": "platform-team"
  }
}

Success Response: 201 Created

{
  "id": "file-id-123",
  "name": "database.json",
  "path": "/apps/fee-manager/database.json",
  "parentFolderId": "folder-id-fee-mgr",
  "type": "JSON",
  "description": "Database connection settings",
  "size": 35,
  "contentHash": "a3f2c1b8d4e5f6a7b8c9d0e1f2a3b4c5",
  "validationStatus": "Valid",
  "validationErrors": null,
  "tags": ["production", "database"],
  "version": 1,
  "createdBy": "user-id-123",
  "createdAt": "2026-01-30T10:30:00Z",
  "modifiedAt": "2026-01-30T10:30:00Z",
  "metadata": {
    "environment": "production",
    "owner": "platform-team"
  }
}

Error Responses:

400 Bad Request - Validation error

{
  "error": "ValidationError",
  "message": "File content is invalid JSON",
  "validationErrors": [
    {
      "line": 2,
      "column": 15,
      "message": "Unexpected token",
      "severity": "error"
    }
  ]
}

Get File Content

Endpoint: GET /api/v1/config/files/{id}/content

Alternative: GET /api/v1/config/files/by-path?path=/apps/fee-manager/database.json

Authentication: Required (Bearer token)

Success Response: 200 OK

{
  "fileId": "file-id-123",
  "path": "/apps/fee-manager/database.json",
  "content": "{\n  \"provider\": \"PostgreSQL\",\n  \"connectionString\": \"...\"\n}",
  "contentType": "application/json",
  "size": 2134,
  "version": 5,
  "etag": "v5-a3f2c1b8d4e5f6a7",
  "modifiedAt": "2026-01-30T10:45:22Z",
  "modifiedBy": "user-id-456"
}

Headers:

• ETag: "v5-a3f2c1b8d4e5f6a7" - For optimistic locking
• Content-Type: application/json
• Last-Modified: Wed, 30 Jan 2026 10:45:22 GMT

Update File Content

Endpoint: PUT /api/v1/config/files/{id}/content

Authentication: Required (Bearer token)

Headers:

• If-Match: "v5-a3f2c1b8d4e5f6a7" - Required for concurrency control

Request Body:

{
  "content": "{\n  \"provider\": \"PostgreSQL\",\n  \"connectionString\": \"Host=prod.db;...\",\n  \"maxPoolSize\": 150\n}",
  "changeDescription": "Increased pool size for production load",
  "validateBeforeSave": true
}

Success Response: 200 OK

{
  "fileId": "file-id-123",
  "path": "/apps/fee-manager/database.json",
  "size": 2256,
  "contentHash": "b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9",
  "validationStatus": "Valid",
  "version": 6,
  "etag": "v6-b4c5d6e7f8a9b0c1",
  "modifiedAt": "2026-01-30T11:00:00Z",
  "modifiedBy": "user-id-123",
  "message": "File saved successfully"
}

Error Responses:

400 Bad Request - Validation failed

{
  "error": "ValidationError",
  "message": "File content validation failed",
  "validationErrors": [
    {
      "line": 5,
      "column": 22,
      "message": "Expected comma after property value",
      "severity": "error"
    }
  ]
}

409 Conflict - Concurrent modification

{
  "error": "ConcurrentModification",
  "message": "File was modified by another user. Please refresh and try again.",
  "currentVersion": 7,
  "currentETag": "v7-c6d7e8f9a0b1c2d3",
  "lastModifiedBy": "jane.dev@example.com",
  "lastModifiedAt": "2026-01-30T10:58:00Z"
}

413 Payload Too Large - File too large

{
  "error": "FileTooLarge",
  "message": "File size exceeds maximum of 10 MB",
  "fileSize": 12582912,
  "maxSize": 10485760
}

Update File Metadata (Rename/Move)

Endpoint: PATCH /api/v1/config/files/{id}

Authentication: Required (Bearer token)

Request Body (Rename):

{
  "name": "database-production.json"
}

Request Body (Move):

{
  "parentFolderId": "folder-id-value-mgr"
}

Request Body (Update Metadata):

{
  "description": "Production database configuration",
  "tags": ["production", "database", "critical"],
  "metadata": {
    "environment": "production",
    "owner": "platform-team",
    "reviewedBy": "senior-architect"
  }
}

Success Response: 200 OK

{
  "id": "file-id-123",
  "name": "database-production.json",
  "path": "/apps/fee-manager/database-production.json",
  "parentFolderId": "folder-id-fee-mgr",
  "type": "JSON",
  "description": "Production database configuration",
  "tags": ["production", "database", "critical"],
  "modifiedAt": "2026-01-30T11:15:00Z",
  "modifiedBy": "user-id-123",
  "message": "File updated successfully"
}

Delete File

Endpoint: DELETE /api/v1/config/files/{id}

Authentication: Required (Bearer token)

Query Parameters:

• permanent (optional): Skip soft delete, permanently delete (default: false)

Success Response: 200 OK

{
  "id": "file-id-123",
  "path": "/apps/fee-manager/database.json",
  "deletedAt": "2026-01-30T11:30:00Z",
  "deletedBy": "user-id-123",
  "backupId": "backup-id-789",
  "message": "File deleted successfully. Can be restored within 30 days.",
  "restoreEndpoint": "/api/v1/config/backups/backup-id-789/restore"
}

Delete Folder

Endpoint: DELETE /api/v1/config/folders/{id}

Authentication: Required (Bearer token)

Query Parameters:

• recursive (required): Must be true to delete non-empty folder
• permanent (optional): Skip soft delete (default: false)

Success Response: 200 OK

{
  "id": "folder-id-fee-mgr",
  "path": "/apps/fee-manager",
  "deletedAt": "2026-01-30T11:45:00Z",
  "deletedBy": "user-id-123",
  "filesDeleted": 3,
  "foldersDeleted": 1,
  "backupIds": ["backup-id-790", "backup-id-791", "backup-id-792"],
  "message": "Folder and all contents deleted successfully"
}

Error Response:

400 Bad Request - Folder not empty

{
  "error": "FolderNotEmpty",
  "message": "Cannot delete folder with contents. Use recursive=true to delete all contents.",
  "fileCount": 3,
  "folderCount": 1
}

Get File Version History

Endpoint: GET /api/v1/config/files/{id}/versions

Authentication: Required (Bearer token)

Query Parameters:

• limit (optional): Max versions to return (default: 20)
• offset (optional): Pagination offset (default: 0)

Success Response: 200 OK

{
  "fileId": "file-id-123",
  "currentVersion": 6,
  "totalVersions": 6,
  "versions": [
    {
      "versionNumber": 6,
      "size": 2256,
      "contentHash": "b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9",
      "changeDescription": "Increased pool size for production load",
      "createdBy": "user-id-123",
      "createdByEmail": "john.admin@example.com",
      "createdAt": "2026-01-30T11:00:00Z",
      "downloadUrl": "/api/v1/config/files/file-id-123/versions/6/content"
    },
    {
      "versionNumber": 5,
      "size": 2134,
      "contentHash": "a3f2c1b8d4e5f6a7b8c9d0e1f2a3b4c5",
      "changeDescription": "Updated connection timeout",
      "createdBy": "user-id-456",
      "createdByEmail": "jane.dev@example.com",
      "createdAt": "2026-01-30T10:45:22Z",
      "downloadUrl": "/api/v1/config/files/file-id-123/versions/5/content"
    }
  ]
}

Restore File from Backup

Endpoint: POST /api/v1/config/backups/{backupId}/restore

Authentication: Required (Bearer token)

Request Body:

{
  "restoreToPath": "/apps/fee-manager/database-restored.json",
  "overwriteExisting": false
}

Success Response: 200 OK

{
  "restoredFileId": "file-id-234",
  "restoredPath": "/apps/fee-manager/database-restored.json",
  "originalPath": "/apps/fee-manager/database.json",
  "restoredAt": "2026-01-30T12:00:00Z",
  "restoredBy": "user-id-123",
  "message": "File restored successfully from backup"
}

Validate File Content

Endpoint: POST /api/v1/config/files/{id}/validate

Alternative: POST /api/v1/config/validate (validate without creating file)

Authentication: Required (Bearer token)

Request Body:

{
  "content": "{\n  \"provider\": \"PostgreSQL\",\n  \"maxPoolSize\": 100\n}",
  "type": "JSON",
  "schemaUrl": "https://schema.example.com/database-config.schema.json"
}

Success Response: 200 OK

{
  "isValid": true,
  "validationStatus": "Valid",
  "errors": [],
  "warnings": [],
  "info": {
    "parser": "System.Text.Json",
    "validatedAt": "2026-01-30T12:15:00Z",
    "schemaValidated": true
  }
}

Error Response (Invalid Content): 200 OK

{
  "isValid": false,
  "validationStatus": "Invalid",
  "errors": [
    {
      "line": 3,
      "column": 20,
      "message": "Expected comma after property value",
      "severity": "error",
      "code": "JSON_SYNTAX_ERROR"
    }
  ],
  "warnings": [
    {
      "message": "Property 'commandTimeout' is recommended but missing",
      "severity": "warning",
      "code": "MISSING_RECOMMENDED_PROPERTY"
    }
  ]
}

Search Configuration Files

Endpoint: GET /api/v1/config/files/search

Authentication: Required (Bearer token)

Query Parameters:

• query (optional): Search term (name, path, content)
• type (optional): Filter by file type (JSON, XML, etc.)
• tags (optional): Filter by tags (comma-separated)
• path (optional): Filter by path prefix
• validationStatus (optional): Filter by validation status
• modifiedAfter (optional): Filter by modification date
• limit (optional): Results per page (default: 50)
• offset (optional): Pagination offset (default: 0)

Success Response: 200 OK

{
  "query": "database",
  "totalResults": 15,
  "limit": 50,
  "offset": 0,
  "results": [
    {
      "id": "file-id-123",
      "name": "database.json",
      "path": "/apps/fee-manager/database.json",
      "type": "JSON",
      "size": 2134,
      "tags": ["production", "database"],
      "validationStatus": "Valid",
      "modifiedAt": "2026-01-30T10:45:22Z",
      "modifiedBy": "user-id-456",
      "excerpt": "...\"provider\": \"PostgreSQL\", \"database\": \"fees\"..."
    }
  ]
}

Performance Requirements

Security Considerations

Access Control

• All configuration management endpoints require authentication
• Role-based access control (RBAC):
  • Admin: Full access to all folders and files
  • Developer: Read/write access to assigned application folders
  • Viewer: Read-only access to specified folders
  • Application: Read-only access via API token
• System folders (/system, /internal) restricted to admins only
• File-level permissions can override folder permissions

Sensitive Data Handling

• Configuration files may contain sensitive data (connection strings, API keys)
• Encrypt sensitive files at rest using AES-256
• Mark files as "sensitive" to enable encryption
• Audit trail for all access to sensitive files
• Redact sensitive values in logs and error messages
• Option to use secret references instead of plaintext secrets:
  • {{secret:database-password}} resolved at runtime
  • Integration with secret management systems (Azure Key Vault, AWS Secrets Manager)

Validation and Sanitization

• Validate all file paths to prevent path traversal attacks
• Reject paths containing: .., ~, absolute paths, null bytes
• Normalize paths to Unix format (forward slashes only)
• Validate file content before saving (prevent code injection)
• Limit file sizes to prevent DoS attacks (max 10 MB)
• Rate limit API requests per user (100 requests/minute)

Audit Trail

• Log all file operations (create, read, update, delete)
• Include: user ID, IP address, timestamp, operation details
• Audit logs immutable and stored separately from application logs
• Retention period: 1 year (configurable)

Backup and Recovery

• Automatic backups before destructive operations
• Backups encrypted at rest
• Backup retention: 30 days (configurable)
• Soft delete with 30-day retention before permanent deletion
• Point-in-time recovery for critical configuration files

Version Control

• All content changes tracked with version history
• Version metadata includes: user, timestamp, change description
• Version comparison/diff capabilities
• Ability to restore previous versions

Testing Scenarios

Test Case 1: Create Folder and File Successfully

Given: User authenticated with developer role
When: User creates folder /apps/test-app and file config.json
Then: Folder and file created, metadata stored, audit logged
Verify: Database records exist, file in storage, tree view updated

Test Case 2: Prevent Duplicate File Creation

Given: File exists at /apps/fee-manager/database.json
When: User attempts to create file with same path
Then: 409 Conflict returned
Verify: No duplicate file created, original file unchanged

Test Case 3: JSON Validation Prevents Invalid Save

Given: User editing JSON file
When: User saves malformed JSON (missing comma)
Then: 400 Bad Request with validation errors
Verify: Content NOT saved, original content preserved, errors displayed in UI

Test Case 4: Concurrent Edit Conflict Detection

Given: Two users editing same file simultaneously
When: User A saves, then User B attempts to save
Then: User B receives 409 Conflict due to ETag mismatch
Verify: User B must refresh and merge changes

Test Case 5: Move File to Different Folder

Given: File exists at /apps/fee-manager/config.json
When: User moves file to /apps/value-manager/
Then: File path updated to /apps/value-manager/config.json
Verify: Storage file moved, metadata updated, tree view reflects new location

Test Case 6: Delete Folder with Contents

Given: Folder /apps/old-app contains 5 files and 2 subfolders
When: User deletes folder with recursive=true
Then: Folder and all contents soft deleted, backups created
Verify: All items marked deleted, backups available, can be restored

Test Case 7: Large File Warning and Streaming

Given: User uploads 8 MB configuration file
When: File size detected as > 1 MB
Then: Warning displayed, user confirms, file processed with streaming
Verify: File saved successfully, memory usage controlled

Test Case 8: File Restore from Backup

Given: File deleted 10 days ago
When: User requests restore from backup
Then: File restored to original or new path
Verify: Content matches backup, metadata restored, audit logged

Test Case 9: Path Traversal Attack Prevention

Given: Malicious user attempts to create file with path ../../etc/passwd
When: System validates path
Then: 400 Bad Request returned, path rejected
Verify: No file created, security event logged

Test Case 10: Sensitive File Encryption

Given: User marks file as "sensitive"
When: File content saved
Then: Content encrypted at rest with AES-256
Verify: Storage file encrypted, decrypted on read, encryption key secured

Test Case 11: Search Files by Content

Given: Multiple files containing "connectionString"
When: User searches for "connectionString"
Then: All matching files returned with excerpts
Verify: Search results accurate, excerpts highlighted

Test Case 12: Version History and Restoration

Given: File modified 5 times
When: User views version history
Then: All 5 versions displayed with metadata
When: User restores version 3
Then: File content reverted to version 3, new version 6 created
Verify: Version history maintained, content matches version 3

Monitoring and Analytics

Key Metrics to Track

• File Operations Rate: CRUD operations per minute/hour
• Storage Usage: Total size of configuration files, growth rate
• Validation Failure Rate: Percentage of saves rejected due to validation
• Concurrent Edit Conflicts: Number of 409 Conflict responses
• Average File Size: Mean and median file sizes
• Most Modified Files: Files with highest change frequency
• Popular File Types: Distribution of JSON, XML, YAML, etc.
• Access Patterns: Most frequently read/edited files
• API Response Times: P50, P95, P99 latencies for each endpoint
• Error Rate: Failed operations per minute

Alerts

• File operation error rate > 5% in 15 minutes
• Storage usage > 90% of allocated capacity
• Validation failure rate > 20% (may indicate documentation issues)
• Backup creation failures
• Abnormal spike in file deletions (potential data loss)
• API endpoint latency > 3 seconds (P95)
• Concurrent edit conflicts > 10 per minute (may need better UX)
• Unauthorized access attempts to sensitive files

Dashboard Widgets

• Storage Overview: Total files, folders, storage used, trending
• Recent Activity: Timeline of file operations (last 24 hours)
• Top Modified Files: Most frequently changed configurations
• Validation Statistics: Success vs failure rates by file type
• User Activity: Top contributors, operations per user
• Performance Metrics: API response times, operation durations

Related Use Cases

• UC-001: Trial User Self-Registration and Access
• UC-002: Application Registration and Lifecycle Management
• UC-003: Configuration Deployment to Applications
• UC-004: Configuration Schema Management and Validation
• UC-005: Secret Management and Integration
• UC-006: Configuration Change Approval Workflow
• UC-008: Configuration File Versioning and Rollback
• UC-009: Configuration Templates and Inheritance
• UC-010: Multi-Environment Configuration Management

Notes and Assumptions

1. File Storage Backend: System supports local filesystem or object storage (S3, Azure Blob)
2. Path Separator: Unix convention (forward slashes) used throughout for consistency across platforms
3. Case Sensitivity: File paths are case-sensitive to match Unix behavior
4. UTF-8 Encoding: All text files use UTF-8 encoding
5. File Locking: Optimistic locking (ETags) used instead of pessimistic locking for better concurrency
6. Real-time Sync: File tree updates in real-time via WebSocket or polling (implementation dependent)
7. Bulk Operations: Not currently supported but planned for future (bulk move, bulk delete)
8. File Import: Users can upload files from local system (drag-and-drop or file picker)
9. File Export: Files can be downloaded individually or exported as ZIP archive
10. Diff/Compare: File comparison between versions available in version history view
11. Schema Validation: JSON Schema and XSD validation supported when schema URLs provided
12. Content Indexing: Full-text search requires separate indexing service (Elasticsearch, Azure Search)
13. Hierarchical Permissions: Folder permissions inherited by children unless overridden
14. Soft Delete: 30-day retention before permanent deletion allows mistake recovery
15. Audit Compliance: Audit trail meets SOC 2 and ISO 27001 requirements

Revision History

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