Skip to main content

Architecture: Storage Modes - CAIPE UI

Date: 2026-01-30

Storage Modes​

🗄️ MongoDB Mode (Production)​

When: MONGODB_URI and MONGODB_DATABASE are configured

Features:

  • ✅ Persistent across devices
  • ✅ Shareable conversations
  • ✅ Team collaboration
  • ✅ Admin analytics
  • ✅ Multi-user support

Data Location: MongoDB database (server-side)

Use Case: Production deployments, team environments

💾 localStorage Mode (Development/Demo)​

When: MongoDB NOT configured

Features:

  • ✅ Zero configuration
  • ✅ Fast local development
  • ✅ No database required
  • ⚠️ Browser-only (not shareable)
  • ⚠️ Lost if browser cleared

Data Location: Browser's localStorage

Use Case: Local development, demos, testing

Configuration​

Enable MongoDB Mode​

In ui/.env.local:

# MongoDB Configuration
MONGODB_URI=mongodb://localhost:27017
MONGODB_DATABASE=caipe

# Required for admin features
MONGODB_ADMIN_DB=admin

Enable localStorage Mode​

Simply don't set MONGODB_URI - that's it!

How It Works​

Storage Detection​

At build/runtime, the app checks:

// ui/src/lib/storage-config.ts
export const IS_MONGODB_CONFIGURED = !!(MONGODB_URI && MONGODB_DATABASE);

export function getStorageMode(): 'mongodb' | 'localStorage' {
  return IS_MONGODB_CONFIGURED ? 'mongodb' : 'localStorage';
}

Exclusive Behavior​

In MongoDB mode:

  • ❌ No localStorage persistence
  • ✅ All CRUD operations go to MongoDB
  • ✅ Server is source of truth

In localStorage mode:

  • ❌ No MongoDB API calls
  • ✅ All CRUD operations use Zustand + localStorage
  • ✅ Browser is source of truth

UI Indicators​

The sidebar shows the current storage mode:

localStorage Mode:

⚠️ Local Storage Mode
   Browser-only • Not shareable

MongoDB Mode:

✅ MongoDB Mode
   Persistent • Shareable • Teams

Admin Dashboard​

MongoDB mode enables:

  • User management
  • Team management
  • Usage statistics (DAU/MAU)
  • Conversation sharing

localStorage mode disables admin features.

Migration​

From localStorage to MongoDB​

If you previously used localStorage mode and want to migrate:

  1. Export your conversations (manually copy from browser DevTools → Application → Local Storage)
  2. Configure MongoDB in .env.local
  3. Restart the app
  4. Use migration API (if implemented) or manually import

From MongoDB to localStorage​

Simply remove MONGODB_URI from .env.local and restart.

Note: You'll lose access to server-side conversations until MongoDB is re-enabled.

Architecture​

chat-store.ts​

// Conditional persistence based on storage mode
export const useChatStore = shouldUseLocalStorage()
  ? create<ChatState>()(persist(storeImplementation, { ... })) // With localStorage
  : create<ChatState>()(storeImplementation);                  // Without localStorage

CRUD Operations​

createConversation: () => {
  const storageMode = getStorageMode();
  
  if (storageMode === 'mongodb') {
    // Create on server
    await apiClient.createConversation({ ... });
  }
  
  // Update local state (persisted only in localStorage mode)
  set({ conversations: [...] });
}