Offline Mode - 100% Available

Civix is designed to work 100% offline. Users can study for their citizenship test anytime, anywhere, without requiring an internet connection.

---

Offline-First Architecture

Core Principle

All essential features work without internet. Data is stored locally first, with optional cloud sync in the future.

Data Storage

AsyncStorage (Local)
├── User Settings (language, theme, test date)
├── Question Stats (SM-2 algorithm data)
├── Practice Results (session history)
├── Gamification (XP, level, badges, streak)
├── Favorites (bookmarked questions)
└── Premium Status (cached from RevenueCat)

---

Feature Availability

Feature	Offline	Online
Quiz Mode	Yes	Yes
Practice Mode	Yes	Yes
Mock Interview	Yes	Yes
Speaking Practice	Yes	Yes
Reading Practice	Yes	Yes
Writing Practice	Yes	Yes
128 Questions	Yes	Yes
SM-2 Algorithm	Yes	Yes
XP & Levels	Yes	Yes
Badges	Yes	Yes
Daily Streak	Yes	Yes
Progress Tracking	Yes	Yes
Settings	Yes	Yes
AI Interview	No*	Yes
Purchase/Restore	No	Yes

*AI Interview falls back to local Mock Interview when offline.

---

Technical Implementation

Network Detection

// lib/offline.ts
import * as Network from 'expo-network';

export async function checkNetworkStatus() {
  const state = await Network.getNetworkStateAsync();
  return {
    isConnected: state.isConnected,
    isInternetReachable: state.isInternetReachable,
    type: state.type,
  };
}

React Hook

// Usage in components
import { useNetworkStatus } from '@/lib/offline';

function MyComponent() {
  const { isOffline, isConnected } = useNetworkStatus();

  if (isOffline) {
    // Handle offline state
  }
}

Offline Indicator

The app shows a non-intrusive banner when offline:

• Blue banner at top of screen
• "Offline Mode - 100% Available" message
• Auto-expands on first offline detection
• Tap to see detailed message

---

Question Bank

All 128 USCIS 2025 Civics Test questions are bundled with the app:

lib/bank/
├── en.ts   # 128 English questions
├── fa.ts   # Farsi translations (future)
├── ps.ts   # Pashto translations (future)
└── index.ts

No Network Required

• Questions are compiled into the app bundle
• Zero API calls needed to fetch questions
• Works immediately after install

Senior/State-Dependent Handling Offline

• Senior practice/exam mode remains strictly in the senior 65/20 pool.
• State-dependent civics items (for example governor/senator prompts) are only prioritized when local stateProfile data exists.
• If state profile data is missing, the algorithm prioritizes evaluatable senior questions to avoid dead-end prompts.

---

State Persistence

Using Zustand with AsyncStorage middleware:

// store/useAppStore.ts
import { persist } from 'zustand/middleware';
import AsyncStorage from '@react-native-async-storage/async-storage';

const useAppStore = create(
  persist(
    (set, get) => ({
      // All state here
    }),
    {
      name: 'civix-store',
      storage: createJSONStorage(() => AsyncStorage),
    }
  )
);

Persisted Data

• lang - Selected language
• theme - Light/Dark mode preference
• testDate - User's test date
• questionStatsV2 - SM-2 algorithm stats per question
• practiceResults - All session history
• xp, dailyStreak, badges - Gamification
• favorites - Bookmarked question IDs
• isUnlocked - Premium status (cached)

---

Offline Graceful Degradation

AI Interview

When offline:

1. Detect no connection
2. Show "Use Mock Interview for offline practice"
3. Mock Interview works with local questions
4. Full interview simulation available

Purchases

When offline:

1. Use cached premium status
2. Show "Purchases require internet"
3. Restore button disabled
4. Features based on last known status

---

Files Created

File	Purpose
lib/offline.ts	Network status detection, offline utilities
components/OfflineIndicator.tsx	UI banner for offline state
docs/OFFLINE-MODE.md	This documentation

---

Testing Offline Mode

Simulator/Emulator

1. iOS: Features > Toggle In-Call Status Bar (doesn't simulate offline)
   • Better: Use Network Link Conditioner
2. Android: Settings > Network > Airplane Mode

Physical Device

1. Enable Airplane Mode
2. Launch app
3. Verify all features work
4. Check offline indicator appears

Test Checklist

• App launches offline
• Quiz works offline
• Practice works offline
• Mock Interview works offline
• Progress saves offline
• XP/Levels work offline
• Settings persist offline
• Offline indicator shows
• No crashes or errors

---

Future Enhancements

Cloud Sync (Not Implemented)

Future: Optional cloud backup
├── Sync progress across devices
├── Backup question stats
├── Restore on new device
└── Requires user account

Dynamic Content Updates (Not Implemented)

Future: Update current officials
├── President, VP, Speaker changes
├── Fetch when online
├── Cache locally
└── Use cached if offline

---

Key Points for Users

1. Download Once, Use Anywhere

   • All 128 questions included
   • No internet needed after install

2. Progress Always Saved

   • XP, levels, badges saved locally
   • Never lose your progress

3. Study Anywhere

   • On airplane, subway, remote areas
   • Full functionality offline

4. AI Features Need Internet

   • AI Interview requires connection
   • Mock Interview works offline as alternative

---

100% Offline - Because citizenship prep shouldn't depend on WiFi.