Core Services - ItemTracker Documentation

UnifiedStorageService

The central data orchestration service that manages both local (AsyncStorage) and cloud (Firebase Firestore) data storage.

Key Features

Local-first: Returns local data immediately for fast UI response
Background sync: Performs cloud sync without blocking the UI
Deduplication: Prevents duplicate items during sync operations
Conflict resolution: Handles concurrent edits gracefully

Key Methods


// Room operations
getRooms()              // Returns all rooms
saveRoom(room)          // Save or update a room
deleteRoom(roomId)      // Delete a room and its contents

// Container operations
getContainers(roomId?)  // Get containers, optionally filtered by room
saveContainer(container)
deleteContainer(containerId)

// Item operations
getItems(containerId?)  // Get items, optionally filtered by container
saveItem(item)
deleteItem(itemId)
moveItem(itemId, newContainerId)

// Sync operations
syncWithCloud()         // Force a full sync
getSyncStatus()         // Get current sync state

Sync Behavior

Scenario	Behavior
Read operation	Returns local data immediately, then syncs in background
Write operation	Saves locally first, then pushes to cloud
Offline mode	All operations work locally, sync when online
Conflict detected	Most recent timestamp wins

Sync Flags

The service uses internal sync flags to prevent concurrent sync operations, which could cause data inconsistencies.

AuthService

Manages user authentication using Firebase Authentication with support for multiple sign-in providers.

Supported Providers

Google Sign-In: OAuth-based authentication
Apple Sign-In: iOS native authentication with nonce support
Email/Password: Traditional authentication

Key Methods


// Authentication
signInWithGoogle()      // Initiate Google OAuth flow
signInWithApple()       // Initiate Apple Sign-In (iOS)
signInWithEmail(email, password)
signUpWithEmail(email, password)
signOut()

// User state
getCurrentUser()        // Get current Firebase user
isAuthenticated()       // Check if user is signed in
onAuthStateChanged(callback)  // Subscribe to auth changes

// Account management
deleteAccount()         // Delete user and all data

Apple Sign-In Implementation

Apple Sign-In requires proper nonce handling for security:


// Nonce is generated and hashed before sending to Apple
const nonce = generateNonce();
const hashedNonce = sha256(nonce);

// Apple receives hashed nonce
const appleCredential = await appleAuth.performRequest({
  requestedOperation: appleAuth.Operation.LOGIN,
  requestedScopes: [appleAuth.Scope.EMAIL, appleAuth.Scope.FULL_NAME],
  nonce: hashedNonce
});

// Firebase receives raw nonce for verification
const credential = auth.OAuthProvider.credential(
  'apple.com',
  appleCredential.identityToken,
  nonce  // Raw nonce
);

AIVisionService

Integrates ML Kit for on-device image analysis, providing item detection and text recognition capabilities.

Capabilities

Image Labeling: Identifies objects in photos
Text Recognition: Extracts text from product labels, boxes, etc.
Smart Naming: Combines text and labels for accurate item names
Category Inference: Suggests appropriate categories

Key Methods


// Main detection method
analyzeImage(imageUri)  // Returns detection results

// Results include:
{
  name: string,         // Smart-generated item name
  category: string,     // Suggested category
  confidence: number,   // Detection confidence
  labels: string[],     // Raw ML Kit labels
  extractedText: string // Any text found in image
}

Smart Naming Logic

The service prioritizes text recognition for creating accurate names:

Extract all visible text from the image
Identify brand names and product identifiers
Extract model numbers or SKUs if present
Combine with object labels for context
Generate a specific, descriptive name

Example

A photo of a drill might return "DeWalt 20V Max Drill" instead of just "Drill" if the label is visible in the image.

HouseholdService

Manages multi-user household functionality, enabling inventory sharing between family members, cleaners, and property managers.

Key Methods


// Household management
createHousehold(name)           // Create a new household
getHousehold()                  // Get current household
inviteMember(email)             // Send invitation
acceptInvitation(inviteCode)    // Join a household
removeMember(userId)            // Remove a member
leaveHousehold()                // Leave current household

// Member operations
getMembers()                    // List all members
getMemberRole(userId)           // Get member's role (owner, admin, cleaner, guest)

Member Roles

Role	Access
Owner	Full access, manage members, billing
Admin	Add/edit items, manage turnovers
Cleaner	View assigned turnovers, verify items, report damage
Guest	View-only access

Data Sharing

When a user joins a household, they gain access to:

All rooms, containers, and items (or assigned properties for cleaners)
Ability to add and edit items (owners and admins)
Checkout/return capabilities
Real-time sync of changes made by others
Turnover checklists and damage reporting (cleaners, Pro plan)

PhotoStorageService

Handles photo capture, compression, and Firebase Storage uploads.

Key Methods


// Photo operations
capturePhoto()          // Launch camera and capture
selectFromGallery()     // Pick from device gallery
uploadPhoto(uri, path)  // Upload to Firebase Storage
deletePhoto(path)       // Remove from storage
getPhotoUrl(path)       // Get download URL

// Compression
compressImage(uri, options)  // Reduce file size

Image Processing

Photos are processed before upload:

EXIF orientation is corrected (fixes rotated images)
Image is compressed to reduce storage/bandwidth
Thumbnail is generated for list views
Full image is uploaded to Firebase Storage

SubscriptionService

Handles in-app purchases and feature management across three subscription tiers using react-native-iap.

Key Methods


// Subscription status
isPremium()             // Check premium status
isPro()                 // Check pro status
getSubscriptionTier()   // Returns 'free', 'premium', or 'pro'
getSubscriptionDetails()
restorePurchases()      // Restore previous purchases

// Feature checks
canAddProperty()        // Pro only
canManageCleaners()     // Pro only
canManageTurnovers()    // Pro only
canUseCloudSync()       // Premium+
canUseAICameraDetection()  // Free: 10 uses, Premium+: unlimited
canUseAIAssistant()     // Premium: 50/mo, Pro: 100/mo

Subscription Tiers

Feature	Free	Premium ($3.99/mo)	Pro ($14.99/mo)
Rooms	10	Unlimited	Unlimited
Containers	20	Unlimited	Unlimited
Items	100	Unlimited	Unlimited
Properties	1	1	Unlimited
Cloud Sync	-	Yes	Yes
Team Members	-	5	10
AI Assistant	-	50 requests/mo	100 requests/mo
Export	-	CSV, Excel, JSON	CSV, Excel, JSON
Multiple Photos	-	Yes	Yes
Cleaner Management	-	-	Yes
Turnover Management	-	-	Yes
Damage Reporting	-	-	Yes