🏹 Project Arjuna — Help & Guide

1 Getting Started

Project Arjuna is a personal productivity dashboard built for UPSC preparation (2026–2028). It tracks your daily routine, study progress, finances, health, mind, growth, and tasks — all in one place.

Two operating modes

First launch

1. Open the app — it loads instantly from local storage (no network needed).
2. If Firebase is configured, a Google sign-in overlay will appear.
3. Click Sign in with Google and complete the auth flow.
4. The app merges any local data with your cloud data automatically.

2 Firebase & Sync Setup

Step-by-step: Create a Firebase project

Firestore Security Rules (copy-paste exactly)

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {

    // Master state document — all devices read/write here
    match /users/{userId}/data/state {
      allow read, write: if request.auth != null
                         && request.auth.uid == userId;
    }

    // Device presence documents — one per device, records last-seen time
    match /users/{userId}/devices/{deviceId} {
      allow read, write: if request.auth != null
                         && request.auth.uid == userId;
    }

    // Per-device state backups — isolated copy, never overwritten by other devices
    match /users/{userId}/deviceStates/{deviceId} {
      allow read, write: if request.auth != null
                         && request.auth.uid == userId;
    }

  }
}

Configure the app

Create (or edit) js/firebase-config.js in your repository with this content:

// js/firebase-config.js
// Replace ALL values below with your actual Firebase project values.
const FIREBASE_CONFIG = {
  apiKey:            "YOUR_API_KEY",
  authDomain:        "YOUR_PROJECT_ID.firebaseapp.com",
  projectId:         "YOUR_PROJECT_ID",
  storageBucket:     "YOUR_PROJECT_ID.appspot.com",
  messagingSenderId: "YOUR_SENDER_ID",
  appId:             "YOUR_APP_ID"
};

After saving and deploying, refresh the app. The sign-in overlay will appear and sync will be fully enabled.

3 Dashboard Tabs Overview

4 Cross-Device Sync Guide

How automatic sync works

1. On load: The app reads Firestore once and merges cloud data with local data.
2. On every save: Any change (checking a task, logging data) is pushed to Firestore within ~800 ms.
3. Real-time listener: The app watches Firestore for changes from other devices and applies them instantly (echo-guarded — it ignores its own writes).
4. Cross-tab sync: Tabs in the same browser sync via BroadcastChannel — no Firestore round-trip needed.

Manual sync

Open the header menu (☰) → click Sync Now. The button shows ⟳ while syncing and ✓ when done. The status row below it shows the last sync time.

Merge strategy (data is never deleted)

• Arrays (tasks, investments, etc.): items are unioned by ID. If the same item exists on two devices, the one with the newer modifiedAt timestamp wins.
• Object logs (health, mind, UPSC progress): keys from both sides are merged — local keys override cloud only for the same date key.
• done: true is sticky — a completed task stays completed regardless of which version wins.
• UPSC progress takes the maximum per subject — study progress never regresses.

Checking sync status (developer console)

Open browser DevTools (F12) → Console tab and run:

ATHENA.syncDiag()

The table shows: enabled (must be true), isAuthenticated, pendingPush, listenerActive, etc.

If data is missing on a device, run:

ATHENA.forcePull()

This bypasses all guards and directly applies the latest Firestore state.

5 Backup & Restore Guide

Auto-backups

The app creates backups automatically at three points:

• startup — once per session when the page loads (deferred to idle time)
• scheduled — every hour while the tab is open
• pre-sync — before applying a cloud merge or force-pull (safety snapshot)

Backups are stored in IndexedDB inside your browser. They are local — not synced to Firestore.

Accessing backups

1. Click the ☰ menu in the header.
2. Click 💾 Backups.
3. A modal lists all saved backups with their timestamp and type.
4. Click Restore next to any backup to apply it. The app will reload with that state.

Manual backup via console

// Create a backup right now
ATHENA.backup()

// List all backups (shows in console as a table)
ATHENA.listBackups()

// Restore a specific backup by key
ATHENA.restoreBackup('backup_key_here')

Exporting data

Open DevTools Console and run:

JSON.stringify(AppState._buildPayload())

Copy the output and save it as a .json file. This is your full data export.

6 Troubleshooting

7 Manual Actions You May Need to Take

A. Apply Firestore security rules

Every time the security rules in Section 2 change, you must re-publish them in Firebase Console → Firestore → Rules. The app cannot do this automatically.

B. Add your domain to Authorised Domains

When you deploy to a new URL (e.g. custom domain, new GitHub Pages URL), you must add it in Firebase Console → Authentication → Settings → Authorised domains.

C. Inject Firebase config at deploy time (GitHub Actions)

If you don't want to commit your real config, use GitHub Actions secrets:

1. Go to your GitHub repo → Settings → Secrets and variables → Actions.
2. Add secrets: FIREBASE_API_KEY, FIREBASE_PROJECT_ID, etc.
3. In your workflow YAML, add a step before deploy:

- name: Write Firebase config
  run: |
    cat > js/firebase-config.js <<EOF
    const FIREBASE_CONFIG = {
      apiKey: "${{ secrets.FIREBASE_API_KEY }}",
      authDomain: "${{ secrets.FIREBASE_PROJECT_ID }}.firebaseapp.com",
      projectId: "${{ secrets.FIREBASE_PROJECT_ID }}",
      storageBucket: "${{ secrets.FIREBASE_PROJECT_ID }}.appspot.com",
      messagingSenderId: "${{ secrets.FIREBASE_SENDER_ID }}",
      appId: "${{ secrets.FIREBASE_APP_ID }}"
    };
    EOF

D. Clear stale local data (reset)

If the app is stuck in a bad state, open DevTools Console and run:

ATHENA.clearState()   // wipes localStorage and reloads (data still in Firestore)

E. Force a full re-sync from Firestore

ATHENA.forcePull()   // pulls latest Firestore state, applies, and re-renders

F. Check sync diagnostics

ATHENA.syncDiag()    // prints a table of all sync state variables to console

Project Arjuna • Master Your Path • 2026–2028