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

Flask Backend Integration - Quick Start

This guide explains how to use the Flask backend for persistent storage with CodeForge.

Overview

CodeForge now supports multiple storage backends:

• IndexedDB (default) - Browser storage, works offline
• Flask Backend (optional) - Server storage, persistent across devices
• SQLite (optional) - Browser storage with SQL support
• Spark KV (fallback) - Cloud storage

Setup Flask Backend

Option 1: Docker (Recommended)

1. Start the backend with Docker Compose:

   docker-compose up -d backend
   

2. Verify it's running:

   curl http://localhost:5001/health
   

3. Configure in the UI:

   • Open CodeForge settings
   • Find "Storage Backend" section
   • Enter backend URL: http://localhost:5001
   • Click "Use Flask"

Option 2: Run Locally

1. Install dependencies:

   cd backend
   pip install -r requirements.txt
   

2. Start the server:

   python app.py
   

   Or with gunicorn:

   gunicorn --bind 0.0.0.0:5001 --workers 4 app:app
   

3. Configure in the UI (same as Docker option)

Option 3: Docker Only Backend

cd backend
docker build -t codeforge-backend .
docker run -d -p 5001:5001 -v codeforge-data:/data --name codeforge-backend codeforge-backend

Using the Backend

In the UI

1. Open Settings (or wherever StorageSettings component is added)
2. Find "Storage Backend" section
3. Enter Flask URL: http://localhost:5001 (or your server URL)
4. Click "Use Flask"
5. All data will be migrated automatically

Programmatically

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

// Switch to Flask backend
await unifiedStorage.switchToFlask('http://localhost:5001')

// Check current backend
const backend = await unifiedStorage.getBackend()
console.log(backend) // 'flask'

// Use storage as normal
await unifiedStorage.set('my-key', { foo: 'bar' })
const value = await unifiedStorage.get('my-key')

Configuration

Environment Variables

Create a .env file in the backend directory:

PORT=5001
DEBUG=false
DATABASE_PATH=/data/codeforge.db

Custom Port

# Docker
docker run -e PORT=8080 -p 8080:8080 ...

# Python
PORT=8080 python app.py

Data Persistence

Data is stored in SQLite at /data/codeforge.db. Make sure to mount a volume:

docker run -v $(pwd)/data:/data ...

Production Deployment

Docker Compose (Full Stack)

# Start both frontend and backend
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all
docker-compose down

Separate Deployment

1. Deploy backend:

   docker-compose up -d backend
   

2. Deploy frontend with backend URL:

   docker build -t codeforge-frontend .
   docker run -d -p 80:80 \
     -e VITE_BACKEND_URL=https://api.yourdomain.com \
     codeforge-frontend
   

3. Configure CORS if frontend and backend are on different domains

Switching Backends

From IndexedDB to Flask

1. Click "Use Flask" in settings
2. Enter backend URL
3. All data migrates automatically

From Flask to IndexedDB

1. Click "Use IndexedDB" in settings
2. All data downloads to browser
3. Can work offline

Export/Import

Always available regardless of backend:

// Export backup
const data = await unifiedStorage.exportData()
const json = JSON.stringify(data, null, 2)
// Save to file

// Import backup
await unifiedStorage.importData(parsedData)

Troubleshooting

Backend not connecting

1. Check backend is running:

   curl http://localhost:5001/health
   # Should return: {"status":"ok","timestamp":"..."}
   

2. Check CORS: Backend has CORS enabled by default

3. Check URL: Make sure URL in settings matches backend

4. Check network: Browser console will show connection errors

Data not persisting

1. Check volume mount:

   docker inspect codeforge-backend | grep Mounts -A 10
   

2. Check permissions:

   ls -la ./data
   

3. Check database:

   sqlite3 ./data/codeforge.db ".tables"
   

Port conflicts

# Use different port
docker run -p 8080:5001 ...

# Update URL in settings to match
http://localhost:8080

Security Considerations

⚠️ The default Flask backend has no authentication!

For production:

1. Add authentication (JWT, API keys, etc.)
2. Use HTTPS/TLS
3. Restrict CORS origins
4. Add rate limiting
5. Use environment-specific configs

API Endpoints

The Flask backend exposes these endpoints:

• GET /health - Health check
• GET /api/storage/keys - List all keys
• GET /api/storage/<key> - Get value
• PUT /api/storage/<key> - Set/update value
• DELETE /api/storage/<key> - Delete value
• POST /api/storage/clear - Clear all data
• GET /api/storage/export - Export all data
• POST /api/storage/import - Import data
• GET /api/storage/stats - Get statistics

See backend/README.md for detailed API documentation.

Benefits of Flask Backend

✅ Persistent across devices - Access data from any device ✅ Team collaboration - Share data with team members ✅ Backup/restore - Centralized backup location ✅ No size limits - Limited only by server disk space ✅ SQL queries - Server-side SQLite for complex queries ✅ Scalable - Add more storage as needed

Comparison

Feature	IndexedDB	Flask Backend	SQLite	Spark KV
Offline	✅ Yes	❌ No	✅ Yes	❌ No
Cross-device	❌ No	✅ Yes	❌ No	✅ Yes
Size limit	~50MB+	Unlimited	~5MB	Unlimited
Speed	Fast	Moderate	Fast	Moderate
Setup	None	Docker/Server	npm install	Spark only
SQL queries	❌ No	✅ Yes	✅ Yes	❌ No

Next Steps

1. Add to settings page:

   import { StorageSettings } from '@/components/molecules'
   
   function SettingsPage() {
     return <StorageSettings />
   }
   

2. Customize backend - Modify backend/app.py as needed

3. Add authentication - Secure your backend for production

4. Deploy to cloud - Use AWS, Azure, DigitalOcean, etc.

5. Monitor usage - Use /api/storage/stats endpoint

Support

• Full documentation: STORAGE.md
• Backend docs: backend/README.md
• Issues: Open a GitHub issue