Offline - Offline-First Architecture

Implement offline-first architecture with local storage, automatic sync, and conflict resolution. Supports multiple patterns from fully offline apps to online-first with offline fallback.

When to Use This Skill

• Adding offline support to existing features
• Building fully offline-first apps
• Implementing data synchronization
• Adding local caching with sync
• User asks "offline mode", "sync data", "work offline", "cache locally"

When NOT to Use This Skill

• Simple in-memory caching - Use /data caching patterns instead
• Network connectivity detection - Use /network-connectivity instead
• Error handling for failed requests - Use /data NetworkFailure types

Questions to Ask

1. Offline mode: Fully offline-first or online-first with offline fallback?
2. Data complexity: Simple key-value or structured relational data?
3. Sync strategy: Periodic sync, on-demand, or push-based?
4. Conflict resolution: Last-write-wins, server-wins, or custom merge?
5. Data sensitivity: Does local data need encryption?

Quick Reference

Offline Patterns

Storage Options

Sync Strategies

Conflict Resolution

Workflow

Phase 1: Analyze Requirements

1. Determine offline pattern (see Quick Reference)
2. Identify data that needs offline access
3. Choose storage solution based on data complexity
4. Define sync strategy and conflict resolution

Phase 2: Setup Local Storage

1. Add dependencies to pubspec.yaml
2. Create local database models/tables
3. Implement local data source

See: storage-guide.md for detailed setup

Phase 3: Implement Sync Layer

1. Add sync status tracking to models
2. Create sync queue for pending operations
3. Implement sync service with conflict resolution
4. Add background sync via WorkManager (optional)

See: sync-guide.md for sync patterns

Phase 4: Update Repository

1. Modify repository to read local-first
2. Add write-through or write-behind patterns
3. Handle sync status in domain entities
4. Integrate with connectivity monitoring

Phase 5: Verify

dart run .claude/skills/offline/scripts/check.dart --feature {feature}

Core API

final items = await repository.getAll(); // Local-first read
await repository.create(item);           // Saves locally, queues sync
final isSynced = ref.watch(syncStatusProvider);

See: storage-guide.md for dependencies and file structure.

Guides

Reference Files

See: reference/ for complete implementations:

• reference/models/ - SyncStatus enum, SyncOperation, OfflineEntity mixin
• reference/local_storage/ - Drift database, Hive local source
• reference/sync/ - SyncQueue, SyncService, ConflictResolver
• reference/repositories/ - Offline-first and cache-first patterns
• reference/providers/ - Sync status providers

Checklist

Setup:

• Offline pattern determined (fully offline vs. online-first + fallback)
• Storage solution chosen (Drift/Hive) and added to pubspec.yaml
• Local database/tables created

Models:

• Domain entity has syncStatus field
• DTO model has sync tracking fields (localId, updatedAt, isSynced)
• Client-generated UUIDs for new entities

Repository:

• Reads from local storage first
• Writes to local storage immediately
• Queues remote sync operations
• Handles sync failures gracefully

Sync:

• Sync queue persists pending operations
• Sync triggers on connectivity restore
• Conflict resolution strategy implemented
• Sync status exposed to UI

Verification:

• Works in airplane mode
• Data persists across app restarts
• Sync completes when online
• Conflicts resolved correctly

Related Skills

• /network-connectivity - Connectivity monitoring and offline banner
• /data - Base repository patterns, caching, error handling
• /push-notifications - Push-based sync triggers
• /analytics - Track sync events and failures

Common Issues

See: sync-guide.md for detailed troubleshooting.

Next Steps

After running this skill:

1. Run /network-connectivity for offline banner
2. Run /testing for offline scenario tests
3. Run /i18n for sync status messages
4. Consider /push-notifications for push-based sync