feat: Enhance provider components with detailed documentation and comments

- Added comprehensive comments and JSDoc-style documentation to NotificationProvider, ThemeProvider, UserProvider, and WebsiteThemeProvider for better clarity and maintainability.
- Improved type definitions in index.ts for better code understanding and usage.
- Introduced Docker support with Dockerfiles for various services including AI server, signaling server, and browser-use service.
- Created a docker-compose.yml file to orchestrate multiple services including PostgreSQL, AI, scraper, and frontend.
- Added a startup guide (startup.txt) for setting up the CRM environment on Ubuntu with Docker.
- Included a .dockerignore file to exclude unnecessary files from Docker builds.

scripts/backup.ps1

@@ -1,17 +1,30 @@
+<#
+.SYNOPSIS
+  PostgreSQL database backup with retention management and logging.
+.DESCRIPTION
+  Uses pg_dump (custom format) to back up the CRM database. Tracks the
+  backup in the backup_logs table and auto-prunes files older than
+  $RetentionDays. Reads DATABASE_URL from the environment or .env.local.
+.PARAMETER BackupDir
+  Directory where backup files are stored (default: ../backups).
+.PARAMETER RetentionDays
+  Number of days to retain backups (default: 30).
+#>
 param(
     [string]$BackupDir = "$PSScriptRoot\..\backups",
     [int]$RetentionDays = 30
 )
 
+# Fail fast on any error
 $ErrorActionPreference = "Stop"
 $startTime = Get-Date
 
-# Ensure backup directory exists
+# ── Ensure backup directory exists ────────────────────────────────
 if (-not (Test-Path $BackupDir)) {
     New-Item -ItemType Directory -Path $BackupDir -Force | Out-Null
 }
 
-# Determine database URL from env or .env.local
+# ── Determine database URL from env or .env.local ─────────────────
 $dbUrl = $env:DATABASE_URL
 if (-not $dbUrl -and (Test-Path "$PSScriptRoot\..\.env.local")) {
     $envContent = Get-Content "$PSScriptRoot\..\.env.local" -Raw
@@ -25,7 +38,7 @@ if (-not $dbUrl) {
     exit 1
 }
 
-# Parse the database URL
+# ── Parse the database URL into connection components ─────────────
 $uri = [System.Uri]$dbUrl
 $pgUser = $uri.UserInfo.Split(':')[0]
 $pgPass = $uri.UserInfo.Split(':')[1]
@@ -33,7 +46,7 @@ $pgHost = $uri.Host
 $pgPort = $uri.Port
 $pgDb = $uri.AbsolutePath.TrimStart('/')
 
-# Set PGPASSWORD for pg_dump
+# pg_dump reads password from this env var (avoids interactive prompt)
 $env:PGPASSWORD = $pgPass
 
 $timestamp = Get-Date -Format "yyyyMMdd_HHmmss"
@@ -44,13 +57,15 @@ Write-Output "Starting backup of database '$pgDb' to $filepath"
 Write-Output "Database: $pgHost:$pgPort/$pgDb"
 
 try {
-    # Run pg_dump
+    # ── Run pg_dump (custom format) ──────────────────────────────
+    # Check PATH first, then fall back to the bundled psql location
     $pgDumpPath = if (Get-Command pg_dump -ErrorAction SilentlyContinue) {
         "pg_dump"
     } else {
         "$env:TEMP\pg\pgsql\bin\pg_dump.exe"
     }
 
+    # Custom format (-Fc) for compressed, restorable output
     $output = & $pgDumpPath -h $pgHost -p $pgPort -U $pgUser -d $pgDb --format=custom --verbose --file $filename 2>&1
     $exitCode = $LASTEXITCODE
 
@@ -58,11 +73,13 @@ try {
         throw "pg_dump failed with exit code $exitCode"
     }
 
+    # Move to final backup location (dg_dump writes to CWD first)
     Move-Item -Path $filename -Destination $filepath -Force
     $fileInfo = Get-Item $filepath
     $fileSize = $fileInfo.Length
 
-    # Verify backup by checking if file is valid custom format
+    # ── Verify backup integrity ──────────────────────────────────
+    # Run a schema-only dump against the same file to check it's valid custom format
     $verifyOutput = & $pgDumpPath -h $pgHost -p $pgPort -U $pgUser -d $pgDb --format=custom --schema-only --file "$filename.verify" 2>&1
     $verifyExitCode = $LASTEXITCODE
     if (Test-Path "$filename.verify") { Remove-Item "$filename.verify" -Force }
@@ -73,7 +90,8 @@ try {
     $endTime = Get-Date
     $durationSeconds = [math]::Round(($endTime - $startTime).TotalSeconds)
 
-    # Log the backup
+    # ── Log backup to database ───────────────────────────────────
+    # Records metadata in backup_logs table for audit trail
     $logQuery = @"
 INSERT INTO backup_logs (backup_type, status, file_name, file_size_bytes, pg_dump_exit_code, verification_status, started_at, completed_at, duration_seconds, retention_days)
 VALUES ('full', 'completed', '$filename', $fileSize, $exitCode, '$verificationStatus', '$($startTime.ToString("yyyy-MM-dd HH:mm:ss"))', '$($endTime.ToString("yyyy-MM-dd HH:mm:ss"))', $durationSeconds, $RetentionDays);
@@ -93,7 +111,7 @@ VALUES ('full', 'completed', '$filename', $fileSize, $exitCode, '$verificationSt
     Write-Output "  Duration: ${durationSeconds}s"
     Write-Output "  Status: $verificationStatus"
 
-    # Cleanup old backups (beyond retention period)
+    # ── Cleanup old backups beyond retention period ──────────────
     $cutoff = (Get-Date).AddDays(-$RetentionDays)
     $oldBackups = Get-ChildItem $BackupDir -Filter "crm_backup_*.sql" | Where-Object {
         $_.CreationTime -lt $cutoff
@@ -106,7 +124,7 @@ VALUES ('full', 'completed', '$filename', $fileSize, $exitCode, '$verificationSt
 } catch {
     Write-Error "Backup failed: $_"
 
-    # Log failure
+    # Log failure to database for monitoring
     $endTime = Get-Date
     $durationSeconds = [math]::Round(($endTime - $startTime).TotalSeconds)
     $errorMsg = $_.ToString().Replace("'", "''")
@@ -121,5 +139,6 @@ VALUES ('full', 'failed', '$filename', '$errorMsg', $exitCode, 'failed', '$($sta
 
     exit 1
 } finally {
+    # Clean up the password environment variable for security
     Remove-Item "Env:PGPASSWORD" -ErrorAction SilentlyContinue
 }