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.

Event-Driven Reactivity#

Mudawim dispatches custom cross-component browser events (mudawim:storage-change) whenever local data is updated:

• UI components (such as Streak Coins, profile avatars, workspace switchers, and notes) instantly synchronize without requiring page reloads or polling loops.
• Storage writes are automatically debounced to minimize write cycles while guaranteeing instantaneous in-memory reactivity.

PWA Installation & Direct Dashboard Launch#

Mudawim can be installed as a standalone Progressive Web App (PWA) on desktop and mobile devices:

• Mobile (iOS Safari): Tap the Share icon and select Add to Home Screen.
• Mobile (Android Chrome): Tap the browser menu or the in-app install prompt and choose Install app.
• Desktop (Chrome / Edge): Click the install icon in the address bar to run Mudawim in its own focused, native-like window.

Fast Dashboard Launch for Returning Learners#

To provide a frictionless study experience, Mudawim detects when it is opened in PWA mode:

• Direct to Dashboard: If you have already set up your profile or added courses, launching the PWA bypasses the marketing homepage and opens straight into your Dashboard.
• Visiting Homepage in PWA: If you ever want to check the homepage or feature roadmap from inside the PWA, simply click the Mudawim logo in the sidebar or top navigation bar.
• Regular Web Browsing: Visitors accessing Mudawim via regular web browser tabs will always see the landing homepage as usual.