App Boilerplate

A modular, offline-first Flutter boilerplate for apps that store, sync, and share media and metadata across centralized (Immich, Firebase) and decentralized (Nostr) systems.

Phase 1 - Local Storage & Caching

• Local storage service with SQLite database
• CRUD operations for items
• Image caching functionality
• Comprehensive unit tests

Quick Start

# Install dependencies
flutter pub get

# Run tests
flutter test

# Run app
flutter run

Local Storage & Caching

LocalStorageService

Service for local storage and caching operations located at lib/data/local/local_storage_service.dart.

Usage:

import 'package:app_boilerplate/data/local/local_storage_service.dart';
import 'package:app_boilerplate/data/local/models/item.dart';

// Initialize service
final service = LocalStorageService();
await service.initialize();

// Insert item
final item = Item(
  id: 'item-1',
  data: {'name': 'Test Item', 'value': 123},
);
await service.insertItem(item);

// Get item
final retrieved = await service.getItem('item-1');

// Get all items
final allItems = await service.getAllItems();

// Update item
final updated = item.copyWith(data: {'name': 'Updated'});
await service.updateItem(updated);

// Delete item
await service.deleteItem('item-1');

// Cache image
final cachedFile = await service.getCachedImage('https://example.com/image.jpg');

// Clear image cache
await service.clearImageCache();

// Close service
await service.close();

Key Features:

• CRUD operations for items stored in SQLite
• Image caching with automatic download and storage
• Cache hit/miss handling
• Modular design - no UI dependencies
• Easily mockable for testing

Files

• lib/data/local/local_storage_service.dart - Main service class
• lib/data/local/models/item.dart - Item data model
• test/data/local/local_storage_service_test.dart - Unit tests

Configuration

Config Files Location

Configuration is defined in code at:

• lib/config/app_config.dart - Configuration model
• lib/config/config_loader.dart - Environment loader (where to tweak values)

How to Modify Config

Edit lib/config/config_loader.dart to change environment values:

// Current dev config (lines 36-40)
case 'dev':
  return const AppConfig(
    apiBaseUrl: 'https://api-dev.example.com',  // ← Change this
    enableLogging: true,                         // ← Change this
  );

// Current prod config (lines 41-45)
case 'prod':
  return const AppConfig(
    apiBaseUrl: 'https://api.example.com',      // ← Change this
    enableLogging: false,                        // ← Change this
  );

Environment Variables

Currently, the app uses compile-time environment variables via --dart-define:

# Set environment at runtime
flutter run --dart-define=ENV=prod

Future: .env file support can be added in later phases. When implemented, .env files would go in the project root and be loaded at runtime.

Available Environments

• dev - Development (default): Logging enabled, dev API URL
• prod - Production: Logging disabled, production API URL

Running the App

Android Emulator

Important: Wait for emulator to fully boot (30-60 seconds on cold boot).

1. Start emulator from Android Studio AVD Manager
2. Wait for boot animation to complete and home screen appears
3. Run: flutter run

iOS Simulator (macOS)

open -a Simulator
flutter run

Running Tests

# Run all tests
flutter test

# Run with coverage
flutter test --coverage

Important: Tests must be run separately - flutter run does not execute tests.

Project Structure

lib/
 ├── config/
 │    ├── app_config.dart
 │    └── config_loader.dart
 ├── data/
 │    └── local/
 │         ├── local_storage_service.dart
 │         └── models/
 │              └── item.dart
 └── main.dart

test/
 ├── config/
 │    └── config_loader_test.dart
 └── data/
      └── local/
           └── local_storage_service_test.dart