Skip to main content

✅ Exclusive Storage Mode - Implementation Complete

🎯 What Changed​

Before (Hybrid Mode - Confusing)​

❌ Always persisted to localStorage (via Zustand)
❌ Also synced to MongoDB if available
❌ Users didn't know where data lived
❌ Old conversations in localStorage, new in MongoDB
❌ Race conditions and sync issues

After (Exclusive Mode - Clear)​

✅ MongoDB mode: Data ONLY in MongoDB (localStorage persistence disabled)
✅ localStorage mode: Data ONLY in browser (no MongoDB calls)
✅ Storage mode determined by MONGODB_URI env variable
✅ Clear UI indicators showing which mode is active
✅ No confusion, no dual-writes, no sync issues

Testing Strategy​

localStorage Mode​

cd ui
# Comment out MONGODB_URI in .env.local
npm run dev

Verify:

  • Conversations persist in browser (check DevTools → Application → Local Storage)
  • No API calls to /api/chat/conversations
  • Sidebar shows "Local Storage Mode" indicator (amber)
  • New conversations create instantly (no server calls)
  • Refresh keeps conversations
  • Clear browser data = lose conversations

MongoDB Mode​

cd ui
# Ensure MONGODB_URI is set in .env.local
npm run dev

Verify:

  • Conversations saved to MongoDB (check database)
  • No localStorage persistence (check DevTools → empty or minimal data)
  • Sidebar shows "MongoDB Mode" indicator (green)
  • Conversations shareable
  • Admin dashboard works (stats, users, teams)
  • Refresh loads from MongoDB

Mode Switching​

localStorage → MongoDB:

  • Enable MONGODB_URI in .env.local
  • Restart server
  • Old localStorage conversations remain in browser (not used)
  • New conversations go to MongoDB
  • Use migration tool (if needed) to transfer old conversations

MongoDB → localStorage:

  • Disable MONGODB_URI in .env.local
  • Restart server
  • Old MongoDB conversations not visible (server unavailable)
  • New conversations go to localStorage
  • Mode indicator updates correctly

🚀 Deployment​

Development Environment​

# Default: localStorage mode (no MongoDB needed)
cd ui
npm run dev

Production Environment​

# MongoDB mode (required for multi-user)
export MONGODB_URI="mongodb://admin:password@mongo:27017"
export MONGODB_DATABASE="caipe"
cd ui
npm run build
npm start

Docker​

# docker-compose.yaml
services:
  ui:
    environment:
      - MONGODB_URI=mongodb://admin:changeme@mongodb:27017
      - MONGODB_DATABASE=caipe

📊 Benefits​

For Users​

✅ Clear visibility - Always know where your data is ✅ Predictable behavior - One storage mode, not two ✅ No surprises - Data doesn't disappear or duplicate ✅ Visual feedback - Color-coded storage indicators

For Developers​

✅ Simpler code - No dual-write logic ✅ Fewer bugs - No sync race conditions ✅ Faster development - Test one mode at a time ✅ Better debugging - Clear data flow

For Admins​

✅ Single source of truth - MongoDB is authoritative ✅ Better analytics - All data in one place ✅ Team features - Sharing and collaboration work reliably ✅ No localStorage confusion - Clean data model

❓ FAQ​

Q: Can I use both MongoDB and localStorage at the same time? A: No. The app uses exclusive storage mode to prevent confusion.

Q: What happens to my localStorage conversations when I enable MongoDB? A: They remain in localStorage but are not used. Use the migration API or manually export/import them.

Q: How do I know which mode I'm in? A: Check the sidebar indicator (green = MongoDB, amber = localStorage) or server startup logs.

Q: Can I switch modes without losing data? A:

  • localStorage → MongoDB: Conversations stay in localStorage until migrated
  • MongoDB → localStorage: Conversations stay in MongoDB (not accessible until re-enabled)

Q: Which mode should I use? A:

  • Development/Demo: localStorage mode (fast, zero config)
  • Production/Team: MongoDB mode (persistent, shareable)

📞 Support​

Issues: Check sidebar storage mode indicator first Migration: Use admin dashboard migration tool (if applicable) Questions: Contact eti-sre@cisco.com

🎉 Status​

✅ Implementation Complete ✅ All Tests Passing ✅ Documentation Updated ✅ Ready for Testing

Next Steps:

  1. Test both storage modes
  2. Verify UI indicators
  3. Test mode switching
  4. Deploy to staging
  5. Collect user feedback

Author: Sri Aradhyula (sraradhy@cisco.com) Date: 2026-01-30 Version: v1.0 Status: ✅ Complete and Ready for Testing