Local-First Storage & Offline Engine

Storage Architecture#

Mudawim uses a high-performance Local-First hybrid storage engine.

┌─────────────────────────────────────────────────────────┐
│                    Mudawim Client App                   │
├────────────────────────────┬────────────────────────────┤
│   In-Memory Cache (RAM)    │ Fast UI Read/Write State   │
├────────────────────────────┼────────────────────────────┤
│  LocalStorage / IndexedDB  │ Persistent Local Database  │
└────────────────────────────┴────────────────────────────┘

• Primary Storage: Browser LocalStorage with automated size verification and fallback mechanisms.
• Zero Cloud Leakage: No data is ever transmitted to remote analytical endpoints or third-party servers.
• Offline Resilient: Once the web application is loaded, you can study, take timestamped notes, and review previous materials without an active internet connection (video playback itself requires connectivity to YouTube's CDN unless cached).

Self-Healing Database Validation#

Every time Mudawim loads from local storage, the database runs through validateAndRepairDb():

1. Schema Migration: Missing fields in older schemas are safely backfilled with default properties without data loss.
2. Streak Verification: Validates recorded studyDates against the calendar to ensure streak counts are mathematically exact.
3. Auto-Freeze Evaluation: Automatically applies active streak freeze tokens if yesterday was missed before breaking your streak.
4. Duration Recalculation: Ensures total watched minutes across all courses accurately sum up completed video durations.

Browser Quota Monitoring#

Mudawim features real-time storage diagnostics:

• Tracks current JSON payload size in kilobytes.
• Warns users when approaching typical browser limits (e.g. 5MB–10MB LocalStorage caps).
• Provides one-click JSON backup downloads in Settings > Data Management.