Architecture - ItemTracker Documentation

Technology Stack

ItemTracker is built using modern mobile development technologies:

React Native 0.80

Cross-platform mobile framework for iOS and Android

Firebase

Authentication, Firestore database, and Cloud Storage

ML Kit

On-device image labeling and text recognition

AsyncStorage

Local persistence for offline-first data access

Key Dependencies

Category	Package	Purpose
Navigation	`@react-navigation`	Stack and tab navigation
Firebase	`@react-native-firebase/*`	Auth, Firestore, Storage
Camera	`react-native-image-crop-picker`	Photo capture with orientation fix
ML/AI	`@react-native-ml-kit/*`	Image labeling, text recognition
Storage	`@react-native-async-storage`	Local data persistence

Project Structure

The codebase follows a modular structure organized by feature and responsibility:


├── src/
│   ├── components/       # Reusable UI components
│   │   ├── AddItemModal.js
│   │   ├── QuickCameraModal.js
│   │   └── ...
│   ├── screens/          # Screen components
│   │   ├── HomeScreen.js
│   │   ├── RoomsScreen.js
│   │   ├── ItemsScreen.js
│   │   └── ...
│   ├── services/         # Business logic & API services
│   │   ├── UnifiedStorageService.js
│   │   ├── AuthService.js
│   │   ├── AIVisionService.js
│   │   └── ...
│   ├── context/          # React Context providers
│   ├── config/           # App configuration
│   └── utils/            # Utility functions
├── android/              # Android native code
├── ios/                  # iOS native code
└── App.tsx               # Root component

Navigation Structure

The app uses React Navigation with a combination of stack and tab navigators:

Bottom Tab Navigator

The main navigation consists of five tabs:

Home: Dashboard with recent items and quick actions
Rooms: Room listing and management
Containers: Container overview across all rooms
Assistant: AI-powered chat for finding items
Scanner: QR code and barcode scanning

Stack Navigator

Nested screens for detailed views:

Room Detail Screen
Container Detail Screen (Items Screen)
Item Detail Screen
Settings Screen
Search Results Screen


// Navigation structure
<NavigationContainer>
  <Stack.Navigator>
    <Stack.Screen name="Main" component={BottomTabs} />
    <Stack.Screen name="RoomDetail" component={RoomDetailScreen} />
    <Stack.Screen name="Items" component={ItemsScreen} />
    <Stack.Screen name="Settings" component={SettingsScreen} />
  </Stack.Navigator>
</NavigationContainer>

State Management

ItemTracker uses a combination of local state, Context API, and service singletons:

Context Providers

ThemeContext: Dark/light mode preferences
NotificationContext: In-app notifications and alerts

Service Singletons

Core services are implemented as singletons that manage their own state:

UnifiedStorageService - Data persistence and sync state
AuthService - User authentication state
SubscriptionService - Premium subscription status

Local-First Pattern

The app prioritizes responsiveness using a local-first data pattern:

Read from local storage immediately (fast UI response)
Sync with cloud in the background
Update local storage with any cloud changes
Handle conflicts gracefully

Performance

This pattern ensures the app feels instant even on slow networks, while still maintaining data consistency across devices.

Build System

The project supports multiple build configurations for different deployment scenarios.

Build Variants

Variant	Script	Use Case
Debug	`npm run android`	Development and testing
Play Store Release	`./build-playstore.sh`	Production Google Play builds
Personal Release	`./build-personal.sh`	Debug-enabled builds for testing

Android Build Commands


# Start Metro bundler
npm start

# Run on connected Android device
npm run android

# Build release APK
./build-and-install.sh

# Build Play Store AAB
./build-playstore.sh

iOS Build Commands


# Install CocoaPods (first time)
bundle install
bundle exec pod install

# Run on iOS simulator
npm run ios

Environment Requirements

Development environment specifications:

Requirement	Version
Node.js	>= 18
React Native	0.80.1
Android SDK	Target SDK 35 (Android 15)
Android NDK	27.1.12297006
iOS	iOS 13.0+
CocoaPods	Latest

Platform Note

Android builds require 64-bit only architecture (arm64-v8a, x86_64) for 16KB memory page size support on Android 15+.

Architecture Overview