Data management - ChaosPrep

ChaosPrep uses Firebase Firestore for real-time cloud sync with offline support. Your study data is always available, even without internet.

Cloud sync with Firebase

All your data syncs automatically to Firebase Firestore:

What’s synced

Tasks: Daily study items with completion status, subject, marks
Weekly targets: Goal tracking with completion percentage
Study logs: Timer sessions with duration, subject, timestamps
Error logs: Mistake tracking with chapter, type, and notes
Question logs: Daily practice counts
Syllabus progress: Chapter status (not started, in progress, completed, mastered)
Settings: Exam type, theme, custom subjects, rollover hour

How sync works

You make a change

Add a task, complete a timer session, or update syllabus progress.

Local database updates instantly

ChaosPrep uses Firestore’s persistent local cache. The change appears immediately in your UI.

Background sync to cloud

When online, the change uploads to Firebase. You’ll never notice the sync happening.

Other devices receive updates

If you’re logged in on multiple devices, they all update in real-time.

ChaosPrep uses Firestore’s persistentLocalCache with persistentMultipleTabManager(). This enables offline support and prevents data conflicts when using multiple tabs.

Offline support

ChaosPrep works fully offline thanks to Progressive Web App (PWA) architecture:

What works offline

✅ Complete functionality:

View and edit calendar tasks
Start/stop timer and log study sessions
Update syllabus progress
Add weekly targets
Log errors and questions
Change settings (theme, subjects, etc.)

Offline data persistence

All your data remains accessible offline through Firestore’s persistent cache:

const db = initializeFirestore(app, {
    localCache: persistentLocalCache({ 
        tabManager: persistentMultipleTabManager() 
    })
});

This means:

No data loss: Changes made offline are stored locally
Automatic sync: When you reconnect, everything uploads automatically
Multi-tab support: Use ChaosPrep in multiple tabs without conflicts

The persistent cache survives browser restarts. Even if you close all tabs and reopen later offline, your data is still there.

Offline indicators

ChaosPrep doesn’t show “offline” warnings because it works seamlessly either way. The only difference:

Online: Changes sync across devices in real-time
Offline: Changes sync when you reconnect

You’ll never lose work due to connectivity issues.

Install ChaosPrep as a PWA (“Add to Home Screen” on mobile, install button in browser) for the best offline experience. PWAs have dedicated storage that persists longer than browser tabs.

Data structure

Firestore organizes your data hierarchically:

artifacts/
  {appId}/
    users/
      {userId}/
        settings/
          config (document)
        tasks/ (collection)
          {taskId} (document)
        weeklyTargets/ (collection)
          {targetId} (document)
        studyLogs/ (collection)
          {logId} (document)
        errorLogs/ (collection)
          {errorId} (document)
        questionLogs/ (collection)
          {logId} (document)
        syllabus/
          progress (document)
        socialProfile/ (if Squad enabled)
          public (document)

Settings document structure

{
  "examType": "JEE Main",
  "session": "Apr",
  "targetYear": 2026,
  "targetDate": "2026-04-01",
  "customSubjects": [],
  "subjectColors": {
    "Physics": "rose",
    "Chemistry": "amber"
  },
  "theme": "dark",
  "bgUrl": "",
  "showCountdown": true,
  "dailyQuestionTarget": 50,
  "liteMode": false,
  "dayRolloverHour": 0
}

Task document structure

{
  "text": "Electrostatics Revision",
  "subject": "Physics",
  "date": "2026-03-03",
  "completed": false,
  "marks": 85,
  "maxMarks": 100,
  "subjectMarks": {
    "Physics": 85
  },
  "order": 0,
  "createdAt": "2026-03-03T08:30:00.000Z"
}

The order field enables drag-and-drop reordering. Tasks sort by order (ascending), then by createdAt for new tasks without order values.

Study log document structure

{
  "subject": "Physics",
  "durationMinutes": 45,
  "date": "2026-03-03",
  "timestamp": "2026-03-03T10:15:00.000Z",
  "type": "timer",
  "notes": "Gauss Law problems"
}

Syllabus progress document structure

{
  "status": {
    "PHY_A_02": "completed",
    "CHE_A_01": "mastered",
    "MAT_B_03": "in-progress"
  },
  "meta": {
    "PHY_A_02": {
      "rev": 2,
      "pyq": true
    },
    "CHE_A_01": {
      "rev": 3,
      "pyq": true
    }
  }
}

Chapter IDs follow the pattern {SUBJECT}_{PRIORITY}_{NUMBER}. For example, PHY_A_02 is Physics, Priority A, Chapter 2.

Cross-device sync

Real-time updates

ChaosPrep uses Firestore snapshots for live updates:

onSnapshot(collection(db, 'artifacts', appId, 'users', user.uid, 'tasks'), (snap) => {
    state.tasks = snap.docs.map(d => ({ id: d.id, ...d.data() }));
    if (state.currentView === 'calendar') renderCalendar();
});

This means:

Complete a task on your phone → Desktop updates instantly
Add a target on desktop → Phone reflects it immediately
Update syllabus on tablet → All devices show the same progress

Device-specific settings

Some preferences are device-local, not synced:

Theme preference: Auto-detects system dark mode per device
View state: Calendar month, expanded syllabus sections
Temporary UI state: Open modals, selected filters

Everything else syncs across devices.

If you notice sync delays, check your internet connection. Firestore batches updates for efficiency, so minor delays (1-2 seconds) are normal on slower connections.

Local storage vs cloud storage

What’s stored locally

Firestore persistent cache:

Complete copy of your synced data
Survives browser restarts
Automatic cleanup of old data

Browser localStorage:

Temporary UI preferences
Authentication tokens (handled by Firebase)

IndexedDB (via Firestore):

Primary offline storage mechanism
Stores documents and pending writes
Managed automatically by Firebase SDK

What’s stored in the cloud

Everything in the Firestore data structure syncs to Google Cloud Platform:

Hosted in Firebase’s multi-region infrastructure
Automatic backups and redundancy
Encrypted in transit and at rest

Firestore uses IndexedDB for local persistence. You can view the raw data in Chrome DevTools → Application → IndexedDB → firestore/[project-id].

Data privacy and security

Authentication

ChaosPrep uses Firebase Authentication with Google Sign-In:

const provider = new GoogleAuthProvider();
await signInWithPopup(auth, provider);

Benefits:

No password management required
OAuth 2.0 security standard
Automatic session management

Access control

Firestore Security Rules ensure your data stays private:

Read access: Only you can read your own documents
Write access: Only you can modify your own data
No cross-user access: Other users cannot see your study logs or progress

If Squad features are enabled, only your public profile (display name, shared tasks) is visible to squad members. Your syllabus progress, error logs, and detailed study data remain completely private.

Data encryption

In transit: All data transfers use HTTPS/TLS encryption
At rest: Firebase encrypts all stored data automatically
Authentication tokens: Stored securely by Firebase Auth, never exposed to JavaScript

What happens when offline

Here’s exactly what happens during common offline scenarios:

Scenario 1: Add a task while offline

Task appears in your calendar immediately (optimistic update)
Firestore adds it to the local write queue
When you reconnect, the write uploads automatically
If the write fails, Firestore retries with exponential backoff

Scenario 2: Complete a task on phone (offline) and desktop (online)

Phone marks task complete locally
Desktop doesn’t see the change yet (phone is offline)
Phone reconnects and syncs
Desktop receives the update via snapshot listener
Both devices now show the task as complete

No conflicts: Last write wins. Firestore uses timestamps to resolve conflicts automatically.

Scenario 3: Update settings offline

Settings change applies locally (theme switches, rollover hour updates)
Firestore queues the write
On reconnection, settings sync to cloud
Other devices receive the new settings

Firestore’s offline persistence is designed for eventual consistency. In rare conflict cases (same field modified on two devices while offline), the last write timestamp wins.

Quota limits

Firebase Free Tier (Spark Plan) limits:

Reads: 50k/day
Writes: 20k/day
Storage: 1GB

For typical usage (one student, daily study tracking), you’ll never hit these limits. ChaosPrep is well within free tier capacity.

To minimize reads and writes, ChaosPrep uses Firestore’s local cache aggressively. Switching between views doesn’t trigger new database queries - it uses cached data.

Data backup and export

ChaosPrep provides built-in export and import functionality for creating local backups of your data.

Exporting your data

To create a JSON backup of all your study data:

Open Settings (gear icon)
Scroll to the Data Management section
Click Export Data
A JSON file downloads to your device with all your data

The export includes:

All tasks (past and future)
Weekly targets
Study timer logs
Mock test records
Error logs
Question logs
Syllabus progress
All settings and preferences

The file is named with a timestamp (e.g., chaosprep-backup-2026-03-03.json) for easy organization.

Export format: The JSON file mirrors your Firestore data structure exactly. It’s human-readable and can be viewed in any text editor.

Importing data

To restore from a backup or transfer data between accounts:

Open Settings
Find the Data Management section
Click Import Data
Select your backup JSON file
Confirm the import (this will overwrite existing data)

Import overwrites: Importing a backup replaces all current tasks, logs, and settings with the backup’s contents. Export your current data first if you want to preserve it.

Export to calendar (.ics)

You can export your tasks as a calendar file to import into Google Calendar, Apple Calendar, or other calendar apps:

Go to the Daily Planner view
Click the Export button (or find it in Settings)
Select Export to Calendar
An .ics file downloads with all your scheduled tasks

The calendar export includes:

Task titles and descriptions
Scheduled dates
Subject information
All future tasks (past tasks are excluded)

Import the .ics file into your calendar app to see your study schedule alongside other commitments.

Use case: Export your study plan to your phone’s native calendar to get system notifications and reminders outside of ChaosPrep.

Backup best practices

Regular backups

Export your data weekly or before major changes (exam type switches, bulk deletions).

Cloud storage

Store backup JSON files in Google Drive or Dropbox for redundancy beyond Firestore.

Pre-import backup

Always export current data before importing a backup, in case you need to revert.

Version control

Keep dated backups (don’t overwrite the same file) to preserve snapshots of your progress.

When to use export/import

Common scenarios:

Switching Google accounts: Export from old account → Sign in with new account → Import
Device reset: Export before factory reset → Import after setup
Data migration: Moving from old device to new device
Disaster recovery: Restore if Firestore data is accidentally deleted
Archival: Save historical data for long-term records

The export/import system ensures your study data is never locked into a single account or device.

Get Started

Core Features

Guides

Reference

​Cloud sync with Firebase

​What’s synced

​How sync works

​Offline support

​What works offline

​Offline data persistence

​Offline indicators

​Data structure

​Settings document structure

​Task document structure

​Study log document structure

​Syllabus progress document structure

​Cross-device sync

​Real-time updates

​Device-specific settings

​Local storage vs cloud storage

​What’s stored locally

​What’s stored in the cloud

​Data privacy and security

​Authentication

​Access control

​Data encryption

​What happens when offline

​Scenario 1: Add a task while offline

​Scenario 2: Complete a task on phone (offline) and desktop (online)

​Scenario 3: Update settings offline

​Quota limits

​Data backup and export

​Exporting your data

​Importing data

​Export to calendar (.ics)

​Backup best practices

Regular backups

Cloud storage

Pre-import backup

Version control

​When to use export/import

Build docs developers (and LLMs) love

Cloud sync with Firebase

What’s synced

How sync works

Offline support

What works offline

Offline data persistence

Offline indicators

Data structure

Settings document structure

Task document structure

Study log document structure

Syllabus progress document structure

Cross-device sync

Real-time updates

Device-specific settings

Local storage vs cloud storage

What’s stored locally

What’s stored in the cloud

Data privacy and security

Authentication

Access control

Data encryption

What happens when offline

Scenario 1: Add a task while offline

Scenario 2: Complete a task on phone (offline) and desktop (online)

Scenario 3: Update settings offline

Quota limits

Data backup and export

Exporting your data

Importing data

Export to calendar (.ics)

Backup best practices

When to use export/import