low-code-react-app-b/docs/STORAGE_DEFAULT_INDEXEDDB.md

Storage Backend Default: IndexedDB

Summary

The storage system has been updated to default to IndexedDB instead of Flask backend. Flask backend is now opt-in only, requiring explicit configuration through UI settings or environment variables.

Changes Made

1. Updated Storage Initialization Logic (src/lib/unified-storage.ts)

Previous Behavior:

• Checked for Flask backend preference first
• If codeforge-prefer-flask was set in localStorage, attempted Flask connection
• Fell back to IndexedDB only if Flask failed

New Behavior:

• IndexedDB is now the default - initialized first unless Flask is explicitly configured
• Flask backend is only used when:
  • VITE_FLASK_BACKEND_URL environment variable is set, OR
  • User explicitly enables Flask backend in UI settings
• Priority order:
  1. Flask (only if explicitly configured)
  2. IndexedDB (default)
  3. SQLite (if preferred)
  4. Spark KV (fallback)

2. Environment Variable Support

The Flask backend URL can be configured via environment variable:

# .env file
VITE_FLASK_BACKEND_URL=http://localhost:5001

Or for production:

VITE_FLASK_BACKEND_URL=https://backend.example.com

3. Updated UI Components (src/components/StorageSettingsPanel.tsx)

Added Flask backend switching functionality:

• Input field for Flask backend URL
• Button to switch to Flask backend
• Clear indication that IndexedDB is the default
• Improved descriptions explaining when to use each backend

4. Updated Documentation (STORAGE.md)

• Reorganized backend priority to show IndexedDB first as default
• Added clear "Default" label for IndexedDB
• Documented Flask backend configuration methods
• Clarified that Flask requires explicit configuration

Usage

Default Behavior (No Configuration)

By default, the app will use IndexedDB automatically:

import { unifiedStorage } from '@/lib/unified-storage'

// Uses IndexedDB by default
await unifiedStorage.set('my-key', myData)
const data = await unifiedStorage.get('my-key')

Console output:

[Storage] Initializing default IndexedDB backend...
[Storage] ✓ Using IndexedDB (default)

Enabling Flask Backend

Method 1: Environment Variable (Recommended for Production)

Create a .env file:

VITE_FLASK_BACKEND_URL=http://localhost:5001

Or set in Docker/Caprover:

docker run -e VITE_FLASK_BACKEND_URL=https://backend.example.com myapp

Method 2: UI Settings (User Preference)

1. Navigate to Settings → Storage
2. Enter Flask backend URL in the input field
3. Click "Flask Backend" button
4. System will migrate all data from IndexedDB to Flask

Switching Back to IndexedDB

In UI Settings:

1. Navigate to Settings → Storage
2. Click "IndexedDB (Default)" button
3. System will migrate all data back to IndexedDB

Benefits of IndexedDB Default

1. No Setup Required - Works immediately without backend server
2. Offline First - Full functionality without network connection
3. Fast Performance - Local storage is faster than network requests
4. Privacy - Data stays on user's device by default
5. Simpler Deployment - No backend infrastructure needed for basic usage

When to Use Flask Backend

Enable Flask backend when you need:

• Cross-device synchronization - Share data across multiple devices
• Centralized data management - Admin access to all user data
• Server-side processing - Complex queries, analytics, backups
• Team collaboration - Multiple users sharing the same data
• Production deployments - Centralized data storage for SaaS applications

Migration Path

The system automatically migrates data when switching backends:

// Switch from IndexedDB to Flask
await switchToFlask('http://localhost:5001')

// Switch from Flask back to IndexedDB  
await switchToIndexedDB()

All existing data is preserved during migration.

Backwards Compatibility

Existing projects with Flask backend configured will continue to use Flask backend:

• If codeforge-prefer-flask is set in localStorage
• If VITE_FLASK_BACKEND_URL is configured
• Data will not be lost or modified

Testing

To verify the default behavior:

1. Clear localStorage (to remove any preferences):

   localStorage.clear()
   

2. Reload the app

3. Check console output:

   [Storage] Initializing default IndexedDB backend...
   [Storage] ✓ Using IndexedDB (default)
   

4. Open DevTools → Application → IndexedDB

   • Should see CodeForgeDB database
   • Should see keyvalue object store

Files Changed

1. src/lib/unified-storage.ts - Updated initialization logic
2. src/components/StorageSettingsPanel.tsx - Added Flask backend UI
3. STORAGE.md - Updated documentation
4. .env.example - Already documented VITE_FLASK_BACKEND_URL

Related Documentation

• STORAGE.md - Complete storage system documentation
• FLASK_BACKEND_SETUP.md - Flask backend installation guide
• .env.example - Environment variable configuration