🎓 Core Concepts

Understanding the key architectural concepts behind our intelligent storage system.

🧠 Intelligent Storage Philosophy

Autonomous Decision-Making

Our storage system is built on the principle that the system should make optimal decisions automatically rather than requiring manual configuration.

Traditional Approach (Manual):

// ❌ Developer must decide where to store data
await opfsStorage.save('user-data', userData);
await localStorageAdapter.save('critical-data', criticalData);
await indexedDBAdapter.save('large-data', largeData);

Our Approach (Intelligent):

// ✅ System decides automatically based on data characteristics
await storage.put('user-data', userData);        // → OPFS + localStorage (redundant)
await storage.put('critical-data', criticalData); // → Multi-adapter redundancy
await storage.put('large-data', largeData);      // → OPFS (optimal for size)

📦 Storage Adapters

Three-Tier Adapter System

The system uses three complementary storage adapters:

1. OPFS (Origin Private File System)

• Best For: Large data (>1MB), file-like storage
• Capacity: 20GB+ (dynamic based on available space)
• Speed: Fast file system operations
• Use Cases: Documents, large datasets, binary data

2. Dexie.js (IndexedDB)

• Best For: Structured data, medium-sized objects
• Capacity: 1GB+ typically
• Speed: Optimized for queries and transactions
• Features: Automatic compression (>1KB), LRU cache (50MB)
• Use Cases: User profiles, app data, structured records

3. localStorage

• Best For: Small, frequently accessed data
• Capacity: 5-10MB
• Speed: Instant access (synchronous)
• Use Cases: Micro-cache, hot keys, redundancy mirror

Automatic Adapter Selection

The Policy Engine analyzes each operation and selects adapters based on:

1. Key Pattern Analysis

   • user/*, auth/*, critical/* → Redundant storage
   • cache/* → Performance-optimized
   • temp/* → Single adapter, high-speed
   • data/* → Best available adapter

2. Data Size Analysis

   • Small (<8KB) → localStorage micro-cache
   • Medium (8KB-1MB) → Dexie with compression
   • Large (>1MB) → OPFS file system

3. Access Pattern Learning

   • Frequently accessed → Prioritized for cache
   • Rarely accessed → Storage-optimized
   • Hot keys → Pre-loaded on startup

⚡ Flash Persistence

Auto-Persistent Signals

Flash Persistence provides signals that automatically persist without manual save/load.

Traditional State (Manual):

// ❌ Boilerplate-heavy with manual persistence
@Component({})
export class Example {
  settings = signal({ theme: 'dark' });

  async ngOnInit() {
    const saved = await storage.get('settings');
    if (saved) this.settings.set(saved);
  }

  async saveSettings() {
    await storage.put('settings', this.settings());
  }
}

Flash Persistence (Automatic):

// ✅ Zero boilerplate - automatic persistence
@Component({})
export class Example {
  settings = autoFlashState('settings', { theme: 'dark' });
  // That's it! Automatically saved on every change.
}

Key Features

• Zero Boilerplate: No actions, reducers, or manual save/load
• Instant Hydration: Pre-loaded state for immediate access
• Automatic Debouncing: Intelligent write batching (300ms default)
• Type-Safe: Full TypeScript support
• Cross-Tab Sync: Changes propagate automatically

🔄 Cloud Sync (Optional)

Offline-First Architecture

Cloud sync is completely optional and maintains local-first performance:

┌─────────────────────────────────────┐
│   Your App (Instant 0.3ms Access)  │
├─────────────────────────────────────┤
│   Flash Persistence (Auto-Save)    │
├─────────────────────────────────────┤
│   Local Storage (Always Fast)      │
│   ├── OPFS (20GB+)                 │
│   ├── Dexie (1GB+)                 │
│   └── localStorage (5-10MB)        │
└─────────────────────────────────────┘
           │
           ↓ (Optional Background Sync)
┌─────────────────────────────────────┐
│   Cloud (MongoDB/Firebase)          │
│   - Configurable sync intervals     │
│   - Priority-based                  │
│   - Conflict resolution             │
└─────────────────────────────────────┘

Sync Strategies

MongoDB Integration:

• Offline-First (default): Local always fast, sync in background
• Online-First: Cloud first, fallback to local
• Realtime: Change Streams for collaborative editing

Firebase Integration:

• Bidirectional Sync: Local ↔ Cloud synchronization
• Real-Time Updates: Live propagation across clients
• Multi-Database: Switch between databases dynamically

🎯 Storage Strategies

Three Performance Modes

Speed Strategy

• Goal: Maximum performance
• Approach: Micro-cache + queued writes
• Best For: Games, real-time apps
• Performance: < 1ms operations

storage.setStrategy('speed');

Balanced Strategy (Default)

• Goal: Optimal balance
• Approach: Smart redundancy + instant writes
• Best For: Most applications
• Performance: 2-5ms operations

storage.setStrategy('balanced');

Durable Strategy

• Goal: Maximum reliability
• Approach: Triple redundancy + sync writes
• Best For: Financial, medical apps
• Performance: 5-10ms operations

storage.setStrategy('durable');

🔄 Cross-Tab Synchronization

Automatic State Sync

Changes automatically propagate across browser tabs using BroadcastChannel:

// Tab 1: Save data
await storage.put('user/theme', 'dark');

// Tab 2: Automatically updates within ~200ms
const theme = userTheme(); // 'dark' - no manual refresh!

Namespace Isolation

Each namespace gets its own broadcast channel:

// App A (namespace: 'app-a')
storage.put('user/data', dataA); // Broadcasts on 'gg-storage:app-a'

// App B (namespace: 'app-b')
storage.put('user/data', dataB); // Broadcasts on 'gg-storage:app-b'
// No conflicts - completely isolated

📊 Performance Architecture

Multi-Level Caching

Three-tier caching system for maximum performance:

┌─────────────────────────────────────┐
│  L1: Memory Cache (LRU)             │  ← 0.1ms
│  - Hot keys in RAM                  │
│  - Automatic eviction               │
├─────────────────────────────────────┤
│  L2: Micro-Cache (localStorage)     │  ← 0.3ms
│  - 100KB budget (configurable)      │
│  - Frequently accessed data         │
├─────────────────────────────────────┤
│  L3: Storage (OPFS/Dexie)          │  ← 2-5ms
│  - Persistent storage               │
│  - Automatic adapter selection      │
└─────────────────────────────────────┘

Boot Manifest

Automatically tracks "hot" keys for optimization:

• Frequently accessed keys pre-loaded on startup
• Warm cache for instant access
• Automatic adjustment based on usage patterns

🛡️ Data Safety

Smart Redundancy

Critical data is automatically mirrored across adapters:

await storage.put('user/auth-token', token);
// → Saved to:
//   1. OPFS (primary storage)
//   2. localStorage (redundancy)
//   3. Memory cache (performance)

Automatic Error Recovery

The system handles errors gracefully:

• Quota Exceeded: Auto-migration to OPFS
• Adapter Failure: Automatic failover to backup
• Data Corruption: Redundancy recovery
• Network Issues: Offline queue for sync

🔍 Key Concepts Summary

🎓 Learning Path

Now that you understand the core concepts:

1. Getting Started - Implement your first storage
2. API Reference - Explore all available methods
3. Flash Persistence - Deep dive into auto-persistent signals
4. MongoDB Integration - Add cloud sync
5. Performance Guide - Optimize for your use case

Understanding these concepts helps you leverage the full power of our intelligent storage system! 🚀