Skip to content

CODEBASE_GUIDE.md

Latest commit

 

History

History
2290 lines (1873 loc) · 109 KB

CODEBASE_GUIDE.md

File metadata and controls

2290 lines (1873 loc) · 109 KB

OffgridMobile — Comprehensive Codebase & Product Flows Guide

This document provides an in-depth reference for the OffgridMobile application: its architecture, every major subsystem, data models, native integrations, and detailed product flows.

Table of Contents

  1. Product Overview
  2. Architecture & Technology Stack
  3. Directory Structure
  4. Navigation & Screen Map
  5. State Management (Zustand Stores)
  6. Data Models & Types
  7. Core Services
  8. Native Integration Layer
  9. Product Flows — Detailed
  10. Testing Infrastructure
  11. Constants & Configuration
  12. File System Layout (On-Device)
  13. Appendix: Default System Prompt
  14. Appendix: Default Projects

1. Product Overview

OffgridMobile is a privacy-first, on-device AI assistant built with React Native. It runs large language models (LLMs), Stable Diffusion image generators, and Whisper speech-to-text models entirely on the user's phone — no server, no internet required after initial model download.

Core capabilities:

  • Text chat with streaming LLM inference (llama.cpp via llama.rn)
  • Remote LLM server support (connect to Ollama, LM Studio, LocalAI, or any OpenAI-compatible server on the local network)
  • Tool calling with automatic tool loop (web search, URL reader, calculator, date/time, device info, knowledge base search)
  • Project-scoped RAG knowledge base (upload documents, embed on-device with MiniLM, retrieve via cosine similarity)
  • Image generation with Stable Diffusion (MNN/QNN backends via LocalDream)
  • Voice input via Whisper speech-to-text (whisper.cpp via whisper.rn)
  • Vision model support (multimodal LLMs with image understanding)
  • Document attachment and analysis
  • Markdown rendering in chat messages
  • Project-based system prompt presets with scoped conversations and knowledge bases
  • Generated image gallery with metadata
  • Passphrase lock with lockout protection
  • Model browsing and download from Hugging Face

Platform support:

  • iOS: Text generation (Metal GPU), Whisper, image generation via Core ML (ANE acceleration).
  • Android: Full feature set including image generation (MNN CPU, QNN NPU on Qualcomm), background downloads via system DownloadManager.

2. Architecture & Technology Stack

Runtime

Layer Technology
Framework React Native (TypeScript)
Navigation React Navigation 7 (native stack + bottom tabs)
State Zustand with persist middleware → AsyncStorage
Styling React Native StyleSheet + dynamic theme system (src/theme/)

On-Device AI

Capability Library Native Backend
Text LLM llama.rn ^0.11 llama.cpp (C++) — Metal (iOS), CPU (Android)
Embeddings (RAG) llama.rn embedding mode llama.cpp — bundled all-MiniLM-L6-v2-Q8_0.gguf
RAG Storage @op-engineering/op-sqlite Native SQLite
Image Gen Custom LocalDreamModule libstable_diffusion_core.so subprocess on localhost:18081
Speech-to-Text whisper.rn ^0.5 whisper.cpp (C++)
Remote LLM OpenAICompatibleProvider XHR SSE → OpenAI-compatible server

Platform Services

Service Library
File I/O react-native-fs
Persistence @react-native-async-storage/async-storage
Secure Storage react-native-keychain
Device Info react-native-device-info
Image Picker react-native-image-picker
Document Picker @react-native-documents/picker
Document Viewer @react-native-documents/viewer
Zip Extraction react-native-zip-archive
Icons react-native-vector-icons (Feather)
Animations react-native-reanimated, lottie-react-native, moti
Lists @shopify/flash-list
Gradients react-native-linear-gradient
Blur @react-native-community/blur
Haptics react-native-haptic-feedback
Gestures react-native-gesture-handler
SVG react-native-svg
Sliders @react-native-community/slider
Onboarding react-native-spotlight-tour

Key Design Patterns

  • Lifecycle-independent services — Text and image generation continue running even when the user navigates away from the chat screen. Services use a subscriber/observer pattern so any screen can re-attach.
  • Selective persistence — Only durable state is persisted (conversations, settings, downloaded model metadata). Transient UI state (streaming position, loading flags) is kept in memory only.
  • Two model loading strategies — "Performance" keeps the model in RAM across generations; "Memory" unloads after each generation to free RAM.
  • Hybrid intent classification — Fast regex pattern matching with optional LLM fallback for ambiguous prompts.

3. Directory Structure

OffgridMobile/
├── App.tsx                              # Root component: init, auth gate, navigation
├── app.json                             # RN app config (name: "OffgridMobile", displayName: "Off Grid")
├── package.json                         # Dependencies & scripts
├── tsconfig.json                        # TypeScript config
│
├── src/
│   ├── assets/
│   │   └── logo.png                     # App logo
│   │
│   ├── components/                      # Reusable UI components
│   │   ├── AnimatedEntry.tsx            # Animated mount/unmount wrapper
│   │   ├── AnimatedListItem.tsx         # Animated list item wrapper
│   │   ├── AnimatedPressable.tsx        # Animated press feedback wrapper
│   │   ├── AppSheet.tsx                 # Bottom sheet wrapper
│   │   ├── AppSheet.styles.ts           # Bottom sheet styles
│   │   ├── Button.tsx                   # Styled button
│   │   ├── Card.tsx                     # Card layout
│   │   ├── ChatInput/                   # Message input bar (text, voice, attachments, image mode)
│   │   │   ├── index.tsx                # Main ChatInput component
│   │   │   ├── Attachments.tsx          # Document/image attachment picker and preview
│   │   │   ├── Toolbar.tsx              # Input toolbar (send, voice, attachments, image mode)
│   │   │   ├── Voice.ts                 # Voice recording integration
│   │   │   └── styles.ts               # ChatInput styles
│   │   ├── ChatMessage/                 # Single message bubble (streaming, images, metadata)
│   │   │   ├── index.tsx                # Main ChatMessage component
│   │   │   ├── components/
│   │   │   │   ├── ActionMenuSheet.tsx  # Long-press action menu + EditSheet for inline message editing
│   │   │   │   ├── BlinkingCursor.tsx   # Streaming cursor animation
│   │   │   │   ├── GenerationMeta.tsx   # Generation metadata display
│   │   │   │   ├── MessageAttachments.tsx # Image/document attachment rendering
│   │   │   │   ├── MessageContent.tsx   # Message text/markdown rendering
│   │   │   │   └── ThinkingBlock.tsx    # Collapsible thinking block
│   │   │   ├── types.ts                 # ChatMessage types
│   │   │   ├── utils.ts                 # ChatMessage utilities
│   │   │   └── styles.ts               # ChatMessage styles
│   │   ├── checklist/                   # Onboarding checklist components
│   │   │   ├── index.ts                 # Checklist exports
│   │   │   ├── ProgressBar.tsx          # Animated checklist progress bar
│   │   │   ├── useOnboardingSteps.ts    # Onboarding step definitions
│   │   │   ├── animations.ts            # Checklist animations
│   │   │   └── types.ts                 # Checklist types
│   │   ├── onboarding/                  # Onboarding spotlight & sheet components
│   │   │   ├── index.ts                 # Onboarding exports
│   │   │   ├── OnboardingSheet.tsx      # Onboarding bottom sheet
│   │   │   ├── PulsatingIcon.tsx        # Animated pulsating icon
│   │   │   ├── useOnboardingSheet.ts    # Onboarding sheet hook
│   │   │   ├── spotlightConfig.tsx      # Spotlight step definitions per screen
│   │   │   └── spotlightState.ts        # Reactive spotlight state management
│   │   ├── GenerationSettingsModal/     # Generation settings modal (split into sections)
│   │   │   ├── index.tsx                # Main modal component
│   │   │   ├── TextGenerationSection.tsx # Text generation parameters
│   │   │   ├── PerformanceSection.tsx   # Performance tuning (threads, GPU, batch)
│   │   │   ├── ImageGenerationSection.tsx # Image generation parameters
│   │   │   ├── ImageQualitySliders.tsx  # Image quality slider controls
│   │   │   ├── ConversationActionsSection.tsx # Conversation actions (clear, etc.)
│   │   │   └── styles.ts               # Settings modal styles
│   │   ├── ModelSelectorModal/          # Model picker modal (text + image models, local + remote)
│   │   │   ├── index.tsx                # Main modal component
│   │   │   └── styles.ts               # Modal styles
│   │   ├── RemoteServerModal/           # Add/edit remote LLM server form
│   │   │   └── index.tsx                # Server config, connection test, model discovery
│   │   ├── VoiceRecordButton/           # Long-press voice recording with waveform
│   │   │   ├── index.tsx                # Main button component
│   │   │   ├── states.tsx               # Recording state UI variants
│   │   │   └── styles.ts               # Button styles
│   │   ├── CustomAlert.tsx              # Alert dialog
│   │   ├── DebugSheet.tsx               # Debug info bottom sheet
│   │   ├── MarkdownText.tsx             # Markdown rendering component
│   │   ├── ModelCard.tsx                # Model browser card with compact/full modes, icon actions
│   │   ├── ModelCard.styles.ts          # ModelCard extracted styles
│   │   ├── ModelCardContent.tsx         # ModelCard content sub-component
│   │   ├── ProjectSelectorSheet.tsx     # Project picker bottom sheet
│   │   ├── ThinkingIndicator.tsx        # Thinking/loading indicator
│   │   ├── ToolPickerSheet.tsx          # Tool selection bottom sheet (enable/disable tools)
│   │   └── index.ts                     # Component exports
│   │
│   ├── screens/                         # Screen components
│   │   ├── OnboardingScreen.tsx         # Welcome slides
│   │   ├── ModelDownloadScreen.tsx      # First model download during onboarding
│   │   ├── HomeScreen/                  # Dashboard: active models, memory, recent chats
│   │   │   ├── index.tsx                # Main HomeScreen component
│   │   │   ├── styles.ts               # HomeScreen styles
│   │   │   ├── components/
│   │   │   │   ├── ActiveModelsSection.tsx  # Active model cards
│   │   │   │   ├── RecentConversations.tsx  # Recent chat list
│   │   │   │   ├── ModelPickerSheet.tsx     # Model selection bottom sheet
│   │   │   │   └── LoadingOverlay.tsx       # Loading state overlay
│   │   │   └── hooks/
│   │   │       ├── useHomeScreen.ts         # Main home screen hook
│   │   │       └── useModelLoading.ts       # Model loading hook
│   │   ├── ChatScreen/                  # Main chat interface
│   │   │   ├── index.tsx                # Main ChatScreen component
│   │   │   ├── ChatScreenComponents.tsx # Extracted sub-components
│   │   │   ├── ChatModalSection.tsx     # Modal overlays (model selector, settings, etc.)
│   │   │   ├── MessageRenderer.tsx      # Message list rendering
│   │   │   ├── useChatScreen.ts         # Main chat screen hook
│   │   │   ├── useChatGenerationActions.ts # Text/image generation actions
│   │   │   ├── useChatModelActions.ts   # Model loading/switching actions
│   │   │   ├── useSaveImage.ts          # Image save-to-device logic
│   │   │   ├── types.ts                 # ChatScreen types
│   │   │   ├── styles.ts               # ChatScreen styles
│   │   │   └── stylesImage.ts           # Image generation styles
│   │   ├── ChatsListScreen.tsx          # Conversation list
│   │   ├── ModelsScreen/                # Model browser (text + image tabs)
│   │   │   ├── index.tsx                # Main ModelsScreen component
│   │   │   ├── TextModelsTab.tsx        # Text model browsing tab
│   │   │   ├── ImageModelsTab.tsx       # Image model browsing tab
│   │   │   ├── TextFiltersSection.tsx   # Text model filter UI
│   │   │   ├── ImageFilterBar.tsx       # Image model filter UI
│   │   │   ├── useTextModels.ts         # Text model browsing hook
│   │   │   ├── useImageModels.ts        # Image model browsing hook
│   │   │   ├── useModelsScreen.ts       # Main models screen hook
│   │   │   ├── useNotifRationale.ts     # Notification permission rationale
│   │   │   ├── imageDownloadActions.ts  # Image model download logic
│   │   │   ├── constants.ts             # ModelsScreen constants
│   │   │   ├── types.ts                 # ModelsScreen types
│   │   │   ├── utils.ts                 # ModelsScreen utilities
│   │   │   ├── styles.ts               # Text models styles
│   │   │   └── imageStyles.ts           # Image models styles
│   │   ├── ModelSettingsScreen/         # LLM + image gen parameters (split into sections)
│   │   │   ├── index.tsx                # Main ModelSettingsScreen component
│   │   │   ├── TextGenerationSection.tsx # Text generation settings
│   │   │   ├── PerformanceSection.tsx   # Performance tuning section
│   │   │   ├── ImageGenerationSection.tsx # Image generation settings
│   │   │   ├── SystemPromptSection.tsx  # System prompt editor
│   │   │   └── styles.ts               # ModelSettingsScreen styles
│   │   ├── GalleryScreen/               # Generated image gallery
│   │   │   ├── index.tsx                # Main GalleryScreen component
│   │   │   ├── FullscreenViewer.tsx     # Fullscreen image viewer with zoom
│   │   │   ├── GridItem.tsx             # Gallery grid item
│   │   │   ├── useGalleryActions.ts     # Gallery actions hook (save, delete, share)
│   │   │   └── styles.ts               # GalleryScreen styles
│   │   ├── DownloadManagerScreen/       # Active downloads (modal)
│   │   │   ├── index.tsx                # Main DownloadManagerScreen component
│   │   │   ├── items.tsx                # Download item components
│   │   │   ├── useDownloadManager.ts    # Download manager hook
│   │   │   └── styles.ts               # DownloadManagerScreen styles
│   │   ├── ProjectsScreen.tsx           # Projects list
│   │   ├── ProjectDetailScreen.tsx      # View project + linked chats + knowledge base entry
│   │   ├── ProjectDetailScreen.styles.ts # ProjectDetailScreen styles
│   │   ├── ProjectChatsScreen.tsx       # Conversations scoped to a project
│   │   ├── KnowledgeBaseScreen.tsx      # Project knowledge base (upload, delete, view documents)
│   │   ├── KnowledgeBaseScreen.styles.ts # KnowledgeBaseScreen styles
│   │   ├── DocumentPreviewScreen.tsx    # Full-text preview of an ingested document
│   │   ├── ProjectEditScreen.tsx        # Create/edit project
│   │   ├── RemoteServersScreen.tsx      # Remote LLM server list (add, edit, delete, set active)
│   │   ├── SettingsScreen.tsx           # Settings hub
│   │   ├── VoiceSettingsScreen.tsx      # Whisper model management
│   │   ├── DeviceInfoScreen.tsx         # Hardware specs
│   │   ├── StorageSettingsScreen.tsx    # Per-model storage usage
│   │   ├── StorageSettingsScreen.styles.ts # StorageSettingsScreen styles
│   │   ├── OrphanedFilesSection.tsx     # Orphaned model file cleanup UI
│   │   ├── SecuritySettingsScreen.tsx   # Passphrase toggle + change
│   │   ├── LockScreen.tsx              # Passphrase entry with lockout
│   │   ├── PassphraseSetupScreen.tsx    # Initial passphrase creation
│   │   └── index.ts                     # Screen exports
│   │
│   ├── navigation/
│   │   ├── AppNavigator.tsx             # Root stack + tab navigator definitions
│   │   ├── types.ts                     # Navigation param types
│   │   └── index.ts
│   │
│   ├── stores/                          # Zustand state stores
│   │   ├── appStore.ts                  # App-wide state (models, settings, device, gallery)
│   │   ├── chatStore.ts                 # Conversations + messages + streaming
│   │   ├── authStore.ts                 # Auth state + lockout
│   │   ├── projectStore.ts             # Projects (system prompt presets)
│   │   ├── remoteServerStore.ts        # Remote servers, discovered models, active server/model
│   │   └── whisperStore.ts             # Whisper model state
│   │
│   ├── services/                        # Business logic & native bridges
│   │   ├── llm.ts                       # LLMService — llama.rn context, streaming, GPU
│   │   ├── llmTypes.ts                  # LLM type definitions (extracted)
│   │   ├── llmMessages.ts              # LLM message building/formatting (extracted)
│   │   ├── llmHelpers.ts               # LLM helper utilities (extracted, includes 3-attempt init fallback)
│   │   ├── llmSafetyChecks.ts          # Model validation (GGUF magic, version, size) + memory checks
│   │   ├── activeModelService/          # Singleton — load/unload text & image models (folder)
│   │   │   ├── index.ts                # Main service entry point
│   │   │   ├── loaders.ts              # Model loading logic
│   │   │   ├── memory.ts               # Memory budget calculations
│   │   │   ├── types.ts                # Service types
│   │   │   └── utils.ts                # Service utilities
│   │   ├── modelManager/               # Download, store, track model files (folder)
│   │   │   ├── index.ts                # Main service entry point
│   │   │   ├── download.ts             # Download orchestration
│   │   │   ├── downloadHelpers.ts      # Download helper utilities
│   │   │   ├── scan.ts                 # Model file scanning & discovery
│   │   │   ├── storage.ts              # Storage management
│   │   │   ├── imageSync.ts            # Image model download sync/recovery
│   │   │   ├── restore.ts              # Download restore after app kill
│   │   │   └── types.ts                # Service types
│   │   ├── providers/                  # LLM provider abstraction layer
│   │   │   ├── types.ts                # LLMProvider interface, GenerationOptions, StreamCallbacks
│   │   │   ├── localProvider.ts        # Local GGUF provider — delegates to llmService
│   │   │   ├── openAICompatibleProvider.ts # Remote server provider — XHR SSE streaming
│   │   │   ├── registry.ts             # ProviderRegistry singleton with listener support
│   │   │   └── index.ts                # Provider exports
│   │   ├── rag/                        # Project-scoped RAG knowledge base
│   │   │   ├── chunking.ts             # Paragraph-aware text chunking with sliding-window overflow
│   │   │   ├── database.ts             # op-sqlite schema + CRUD for chunks and documents
│   │   │   ├── embedding.ts            # On-device MiniLM embeddings via llama.rn embedding mode
│   │   │   ├── retrieval.ts            # Cosine similarity ranking + XML-safe prompt formatting
│   │   │   ├── vectorMath.ts           # Dot product, magnitude, cosine similarity (pure TS)
│   │   │   └── index.ts                # ragService singleton
│   │   ├── generationService.ts        # Lifecycle-independent text generation (local + remote routing)
│   │   ├── imageGenerationService.ts   # Lifecycle-independent image generation
│   │   ├── localDreamGenerator.ts      # ONNX SD wrapper (native subprocess)
│   │   ├── imageGenerator.ts           # Image generator helper
│   │   ├── intentClassifier.ts         # Pattern + LLM intent detection
│   │   ├── huggingface.ts              # HF API: search, files, credibility
│   │   ├── huggingFaceModelBrowser.ts  # Image model browsing
│   │   ├── coreMLModelBrowser.ts       # iOS Core ML model discovery from Apple HF repos
│   │   ├── whisperService.ts           # Whisper model download/load/transcribe
│   │   ├── voiceService.ts             # Native voice input bridge
│   │   ├── authService.ts              # Passphrase hash + keychain
│   │   ├── hardware.ts                 # Device info, RAM, recommendations
│   │   ├── backgroundDownloadService.ts # DownloadManager bridge (Android + iOS)
│   │   ├── documentService.ts          # Document text extraction + RAG knowledge base ingestion
│   │   ├── pdfExtractor.ts             # Native PDF text extraction
│   │   ├── httpClient.ts               # XHR/SSE streaming, endpoint testing, server type detection
│   │   ├── remoteServerManager.ts      # Remote server CRUD, keychain API key storage, provider lifecycle
│   │   ├── generationToolLoop.ts       # Multi-turn tool loop orchestration (max 3 iterations, retry with backoff)
│   │   ├── llmToolGeneration.ts        # Tool-aware LLM generation with schema injection
│   │   └── tools/                      # Tool calling subsystem
│   │       ├── index.ts                # Public exports
│   │       ├── registry.ts             # Tool definitions, OpenAI schema conversion
│   │       ├── handlers.ts             # Tool execution (web search, URL reader, calculator, datetime, device info, knowledge base)
│   │       └── types.ts                # ToolDefinition, ToolCall, ToolResult types
│   │
│   ├── hooks/
│   │   ├── useAppState.ts              # AppState foreground/background tracking
│   │   ├── useFocusTrigger.ts          # Screen focus trigger hook
│   │   ├── useVoiceRecording.ts        # Voice recording state machine
│   │   └── useWhisperTranscription.ts  # Whisper transcription hook
│   │
│   ├── types/
│   │   ├── index.ts                    # All TypeScript interfaces & type aliases
│   │   ├── global.d.ts                 # Global type declarations
│   │   └── whisper.rn.d.ts             # Whisper native module type declarations
│   │
│   ├── theme/                            # Light/dark theme system
│   │   ├── index.ts                     # useTheme() hook, getTheme(), Theme type
│   │   ├── palettes.ts                  # COLORS_LIGHT/DARK, SHADOWS_LIGHT/DARK, createElevation()
│   │   └── useThemedStyles.ts           # useThemedStyles() — memoized style factory
│   │
│   ├── constants/
│   │   ├── index.ts                    # Model recommendations, org filters, quantization info, HF config, typography, spacing
│   │   └── models.ts                   # Curated model definitions (extracted)
│   │
│   └── utils/
│       ├── coreMLModelUtils.ts         # Core ML model path resolution helpers
│       ├── generateId.ts              # Crypto-safe UUID generation
│       ├── haptics.ts                  # Haptic feedback utilities
│       ├── logger.ts                   # Logger utility (replaces console.log/warn/error)
│       └── messageContent.ts           # Strip LLM control tokens from output
│
├── android/                             # Android native code
│   └── app/src/main/java/ai/offgridmobile/
│       ├── MainActivity.kt              # Main activity
│       ├── MainApplication.kt           # Application entry point
│       ├── localdream/
│       │   ├── LocalDreamModule.kt      # Stable Diffusion native module
│       │   └── LocalDreamPackage.kt     # Package registration
│       ├── download/
│       │   ├── DownloadManagerModule.kt # Background download native module
│       │   ├── DownloadManagerPackage.kt # Package registration
│       │   ├── DownloadForegroundService.kt # Foreground service to prevent download throttling
│       │   └── DownloadCompleteBroadcastReceiver.kt # Broadcast receiver
│       └── pdf/
│           ├── PDFExtractorModule.kt    # Native PDF text extraction
│           └── PDFExtractorPackage.kt   # Package registration
│
├── ios/                                 # iOS native code
│   ├── CoreMLDiffusionModule.swift      # Core ML image generation (root level)
│   ├── CoreMLDiffusionModule.m          # ObjC bridge (root level)
│   ├── DownloadManagerModule.swift      # iOS download manager (root level)
│   ├── DownloadManagerModule.m          # ObjC bridge (root level)
│   ├── PDFExtractorModule.swift         # Native PDF text extraction (root level)
│   ├── PDFExtractorModule.m             # ObjC bridge (root level)
│   └── OffgridMobile/
│       ├── AppDelegate.swift            # Application delegate
│       ├── OffgridMobile-Bridging-Header.h # Swift/ObjC bridging header
│       ├── CoreMLDiffusion/
│       │   └── CoreMLDiffusionModule.m  # ObjC bridge (subdirectory)
│       ├── Download/
│       │   └── DownloadManagerModule.m  # ObjC bridge (subdirectory)
│       └── PDFExtractor/
│           ├── PDFExtractorModule.m     # ObjC bridge (subdirectory)
│           └── PDFExtractorModule.swift # Swift implementation (subdirectory)
│
├── __tests__/                           # Test suites (~108 test files)
│   ├── unit/                            # Store & service unit tests
│   │   ├── stores/                      # appStore, chatStore, authStore, projectStore, whisperStore
│   │   ├── services/                    # 20+ service test files
│   │   ├── hooks/                       # Hook tests (useAppState, useChatGenerationActions, etc.)
│   │   ├── onboarding/                  # Onboarding/spotlight unit tests (6 files)
│   │   ├── screens/ModelsScreen/        # ModelsScreen utility tests
│   │   ├── constants/                   # Constants tests
│   │   ├── theme/                       # Theme palette tests
│   │   └── utils/                       # Utility tests
│   ├── integration/                     # Multi-service integration tests
│   │   ├── generation/                  # generationFlow, imageGenerationFlow
│   │   ├── models/                      # activeModelService
│   │   ├── onboarding/                  # spotlightFlowIntegration
│   │   └── stores/                      # chatStoreIntegration
│   ├── contracts/                       # Native module contract tests (7 files)
│   ├── rntl/                            # React Native Testing Library tests
│   │   ├── screens/                     # 19 screen tests
│   │   ├── components/                  # 17 component tests
│   │   ├── onboarding/                  # 5 spotlight screen tests
│   │   ├── hooks/                       # Hook tests (useFocusTrigger)
│   │   └── navigation/                  # AppNavigator tests
│   ├── specs/                           # Behavior specifications (YAML)
│   └── utils/                           # Test helpers, factories & spotlight mocks
│
├── .maestro/                            # E2E tests (Maestro framework)
│   ├── E2E_TESTING.md                   # E2E testing guide
│   ├── flows/p0/                        # 5 critical-path E2E flows (app launch, text/image gen, stop gen)
│   ├── flows/p1/                        # 4 important-path flows (attachments, retry)
│   ├── flows/p2/                        # 4 model management flows (download, uninstall, selection, unload)
│   ├── flows/p3/                        # 3 image model management flows
│   └── utils/
│
├── docs/                                # Documentation
│   ├── ARCHITECTURE.md                  # System architecture & build guide
│   ├── PRIVACY_POLICY.md               # Privacy policy
│   ├── standards/
│   │   └── CODEBASE_GUIDE.md            # This file — comprehensive architecture guide
│   ├── design/
│   │   ├── DESIGN_PHILOSOPHY_SYSTEM.md  # Design system reference
│   │   └── VISUAL_HIERARCHY_STANDARD.md # Visual hierarchy guidelines
│   ├── onboarding/
│   │   └── ONBOARDING_FLOWS.md          # Onboarding spotlight flow documentation
│   └── test/
│       ├── CLAUDE_TEST_SKILL.md         # Claude test generation skill
│       ├── TEST_FLOWS.md                # End-to-end test flows
│       ├── TEST_COVERAGE_REPORT.md      # Test coverage report
│       ├── TEST_PRIORITY_MAP.md         # Test priority mapping
│       └── TEST_SPEC_FORMAT.md          # Test specification format
│
├── patches/                             # patch-package patches

4. Navigation & Screen Map

Root Navigator (Stack)

RootStack
│
├── OnboardingScreen          (shown once, first launch)
├── ModelDownloadScreen        (shown if no models downloaded after onboarding)
├── MainTabs                   (primary app interface)
├── DownloadManagerScreen      (modal overlay)
└── GalleryScreen              (modal overlay, fullscreen image viewer)

Main Tabs (Bottom Tab Navigator, 5 tabs)

MainTabs
│
├── HomeTab
│   └── HomeScreen
│
├── ChatsTab (Stack)
│   ├── ChatsListScreen
│   └── ChatScreen
│
├── ProjectsTab (Stack)
│   ├── ProjectsScreen
│   ├── ProjectDetailScreen
│   ├── ProjectChatsScreen
│   ├── KnowledgeBaseScreen
│   ├── DocumentPreviewScreen
│   └── ProjectEditScreen (modal presentation)
│
├── ModelsTab
│   └── ModelsScreen
│
└── SettingsTab (Stack)
    ├── SettingsScreen
    ├── ModelSettingsScreen
    ├── VoiceSettingsScreen
    ├── DeviceInfoScreen
    ├── StorageSettingsScreen
    ├── SecuritySettingsScreen
    └── RemoteServersScreen

Screen Descriptions

Screen Purpose Key testIDs
OnboardingScreen 4 welcome slides (privacy, offline, model choice). Shown once. onboarding-screen
ModelDownloadScreen Recommends a model based on device RAM. User downloads or skips. model-download-screen
HomeScreen Dashboard: active text/image models, memory usage (used/total), recent conversations with message preview and smart date formatting, quick "New Chat" button. home-screen, new-chat-button
ChatScreen Full chat interface. Streaming messages, model selector, project selector, generation settings, image generation with live preview, voice input, document attachments, debug panel. chat-screen, chat-input, send-button, stop-button
ChatsListScreen Sorted conversation list with compact items. Shows title, last message preview snippet, project badge, timestamp. Swipe-to-delete. conversation-list
ModelsScreen Two sections: Text Models and Image Models. Curated recommendations by RAM, search bar, advanced filters (org, size, quantization, type, credibility). Local .gguf import. Download progress, pause/cancel. Compact card layout with icon actions. models-screen, model-list
ProjectsScreen List of system prompt presets. Shows name, description snippet, linked chat count. Default projects: General Assistant, Spanish Learning, Code Review, Writing Helper. projects-screen
ProjectDetailScreen Full project view: name, system prompt, description, entry points to project chats and knowledge base.
ProjectChatsScreen Conversations scoped to a specific project.
KnowledgeBaseScreen Upload, view, and delete documents in a project's knowledge base. Shows ingestion status per document.
DocumentPreviewScreen Full-text preview of an ingested document retrieved from the RAG database.
ProjectEditScreen Create/edit form: name, description, system prompt, icon selection.
RemoteServersScreen List of configured remote LLM servers. Add, edit, delete, and set the active server.
GalleryScreen 3-column image grid. Filter by conversation. Multi-select for batch delete. Save to device. View metadata (prompt, steps, seed, model). gallery-screen
SettingsScreen Hub with sections: Model Settings, Voice Settings, Security, Storage, Device Info. settings-screen
ModelSettingsScreen Sliders/inputs for: system prompt, temperature (0–2), top-p (0–1), repeat penalty (1–2), max tokens, context length, threads, batch size, GPU toggle + layers, image gen steps/guidance/resolution, loading strategy, generation details toggle.
VoiceSettingsScreen Download/select Whisper model (tiny/base/small, English or multilingual).
DeviceInfoScreen Device model, OS, total/available RAM, total/available storage, emulator flag, GPU capabilities.
StorageSettingsScreen Per-category storage (text models, image models, whisper, gallery). Per-model sizes. Delete from here.
SecuritySettingsScreen Toggle passphrase lock. Change passphrase (requires old).
LockScreen Passphrase input. Shows lockout timer (MM:SS) after 5 failed attempts. 5-minute lockout. lock-screen
PassphraseSetupScreen Set new passphrase with confirmation. Must match.
DownloadManagerScreen Modal showing all active/completed/failed downloads with progress bars, pause/resume/cancel/retry controls.

5. State Management (Zustand Stores)

All stores use zustand/middleware persist with AsyncStorage. Only serializable, durable data is persisted; transient UI flags are excluded via partialize.

appStore (local-llm-app-storage)

State Group Fields Notes
Onboarding hasCompletedOnboarding Set true once, never reset
Device deviceInfo, modelRecommendation Refreshed on app start
Downloaded Models downloadedModels[], downloadedImageModels[] Metadata only; files on disk
Active Models activeModelId, activeImageModelId Persisted; model re-loaded on next use
Loading Flags isLoadingModel, isGeneratingImage Not persisted
Downloads downloadProgress{}, activeBackgroundDownloads[] Background downloads persisted (Android)
Settings systemPrompt, temperature, maxTokens, topP, repeatPenalty, contextLength, nThreads, nBatch, useGPU, nGPULayers, modelLoadingStrategy, flashAttention, kvCacheType All persisted
Image Settings imageSteps, imageGuidanceScale, imageWidth, imageHeight, imageThreads All persisted
Intent imageGenerationMode, autoDetectMethod, classifierModelId Persisted
Tools enabledTools[] User-selected tool IDs (default: all 5 tools enabled — ['web_search', 'calculator', 'get_current_datetime', 'get_device_info', 'read_url']). Persisted
UI showGenerationDetails Persisted
Gallery generatedImages[] Full metadata array, persisted

chatStore (local-llm-chat-storage)

State Group Fields Notes
Conversations conversations[] Full conversation objects with all messages
Active activeConversationId Which chat is currently open
Streaming streamingMessage, isStreaming, isThinking, streamingForConversationId Not persisted
Actions createConversation(), deleteConversation(), addMessage(), updateMessage(), deleteMessage(), deleteMessagesAfter(), setStreaming(), clearAllConversations()

authStore (local-llm-auth-storage)

Field Type Notes
isEnabled boolean Whether passphrase lock is turned on
isLocked boolean Current lock state
failedAttempts number Resets on success
lockoutUntil number | null Unix timestamp when lockout expires
lastBackgroundTime number | null When app went to background (for auto-lock)
Constants MAX_ATTEMPTS = 5, LOCKOUT_DURATION = 5 min

projectStore (local-llm-project-storage)

Field Notes
projects[] Array of Project objects
Default projects General Assistant, Spanish Learning, Code Review, Writing Helper
Actions createProject(), updateProject(), deleteProject(), duplicateProject()

remoteServerStore (remote-server-storage)

State Group Fields Notes
Servers servers[] Persisted. API keys are NOT stored here — kept in system keychain by remoteServerManager
Active activeServerId Which server is currently selected (null = local-only)
Models discoveredModels{} Map of serverId → RemoteModel[]. Persisted
Health serverHealth{} Map of serverId → { isHealthy, lastCheck }. Persisted
Active Model activeRemoteTextModelId, activeRemoteImageModelId Currently selected remote models
Loading isLoading, testingServerId, discoveringServerId Transient
Actions addServer(), updateServer(), removeServer(), setActiveServerId(), discoverModels(), testConnection(), testConnectionByEndpoint()

whisperStore (local-llm-whisper-storage)

Field Notes
downloadedModelId Which whisper model is downloaded
isLoading, isDownloading Transient flags
Actions downloadModel(), loadModel(), unloadModel(), deleteModel()

6. Data Models & Types

Core Entities

ModelInfo                    # Model from HuggingFace API
├── id, name, author
├── description, downloads, likes, tags
├── files: ModelFile[]
└── credibility?: ModelCredibility

ModelFile                    # A specific quantized file for a model
├── name, size, quantization, downloadUrl
└── mmProjFile?: { name, size, downloadUrl }   # Vision companion

DownloadedModel              # A model file on disk
├── id, name, author
├── filePath, fileName, fileSize, quantization
├── downloadedAt, credibility?
└── isVisionModel?, mmProjPath?, mmProjFileName?, mmProjFileSize?

ONNXImageModel               # Stable Diffusion model on disk
├── id, name, description
├── modelPath, downloadedAt, size
├── style? ('creative' | 'photorealistic' | 'anime')
└── backend? ('mnn' | 'qnn')

Conversation
├── id, title, modelId
├── messages: Message[]
├── createdAt, updatedAt
└── projectId?

Message
├── id, role ('user' | 'assistant' | 'system' | 'tool')
├── content, timestamp
├── isStreaming?, isThinking?, isSystemInfo?
├── attachments?: MediaAttachment[]
├── generationTimeMs?
├── generationMeta?: GenerationMeta
├── toolCallId? (for tool result messages)
├── toolCalls?: Array<{ id?, name, arguments }> (for assistant tool call messages)
└── toolName? (for tool result messages)

MediaAttachment
├── id, type ('image' | 'document'), uri
├── mimeType?, width?, height?, fileName?
├── textContent? (extracted document text)
└── fileSize?

GenerationMeta
├── gpu, gpuBackend?, gpuLayers?
├── cacheType? (KV cache quantization type, e.g. 'f16', 'q8_0', 'q4_0')
├── modelName?
├── tokensPerSecond?, decodeTokensPerSecond?
├── timeToFirstToken?, tokenCount?
├── steps?, guidanceScale?, resolution?

GeneratedImage
├── id, prompt, negativePrompt?
├── imagePath, width, height
├── steps, seed, modelId
├── createdAt, conversationId?

Project
├── id, name, description, systemPrompt
├── icon?, createdAt, updatedAt

RemoteServer
├── id, name, endpoint, providerType ('openai-compatible' | 'anthropic')
├── createdAt, lastHealthCheck?, isHealthy?, notes?
└── apiKey is NOT stored here — kept in system keychain

RemoteModel
├── id, name, serverId
├── capabilities: { supportsVision, supportsToolCalling, supportsThinking, maxContextLength?, family? }
├── details?, lastUpdated

RagDocument                  # A document ingested into a project knowledge base
├── id, projectId, name, filePath
├── fileSize, mimeType, createdAt
└── chunkCount

RagChunk                     # A chunk of text with its embedding vector
├── id, documentId, projectId
├── content, position (chunk index within document)
└── embedding: number[]      (384-dim MiniLM vector, stored as JSON)

Enums & Aliases

Type Values Used By
ModelSource 'lmstudio' | 'official' | 'verified-quantizer' | 'community' Credibility badges
ImageGenerationMode 'auto' | 'manual' Settings: auto-detect vs explicit
AutoDetectMethod 'pattern' | 'llm' Settings: fast regex vs LLM fallback
ModelLoadingStrategy 'performance' | 'memory' Settings: keep loaded vs load-on-demand
ImageModeState 'auto' | 'force' Chat input toggle
BackgroundDownloadStatus 'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'unknown' Download manager
SoCVendor 'qualcomm' | 'mediatek' | 'exynos' | 'tensor' | 'apple' | 'unknown' SoC detection
CacheType 'f16' | 'q8_0' | 'q4_0' KV cache quantization

Additional Interfaces

SoCInfo                      # System-on-Chip detection
├── vendor: SoCVendor
├── hasNPU: boolean
├── qnnVariant?: '8gen2' | '8gen1' | 'min'
└── appleChip?: 'A14' | 'A15' | 'A16' | 'A17Pro' | 'A18'

ImageModelRecommendation     # Per-device image model recommendation
├── recommendedBackend: 'qnn' | 'mnn' | 'coreml' | 'all'
├── qnnVariant?, recommendedModels?
├── bannerText, warning?
└── compatibleBackends: Array<'mnn' | 'qnn' | 'coreml'>

PersistedDownloadInfo        # Persisted download state for restore after app kill
├── modelId, fileName, quantization, author, totalBytes
├── mainFileSize?, mmProjFileName?, mmProjFileSize?
└── imageModel* fields (for image model download restore)

7. Core Services

LLMService (src/services/llm.ts + llmTypes.ts, llmMessages.ts, llmHelpers.ts, llmSafetyChecks.ts)

The central service for on-device text inference.

Responsibilities:

  • Initialize and manage llama.rn LlamaContext
  • Configure GPU offloading (Metal on iOS, disabled on Android for stability)
  • Stream tokens to callbacks during generation
  • Track performance metrics (tok/s, TTFT, decode tok/s)
  • Handle context window management (85% utilization cap, smart truncation)
  • Support multimodal/vision models via mmproj files
  • KV cache management (clear between conversations)
  • Session caching for repeated system prompts
  • Tool calling capability detection via jinja chat template introspection
  • Configurable KV cache type (f16, q8_0, q4_0) and flash attention toggle
  • Parameter constraint enforcement (GPU/flash attention/KV cache compatibility on Android)
  • Comprehensive diagnostic logging ([LLM] tags) throughout the load pipeline: model validation (file size, GGUF magic, GGUF version), user settings resolution, memory estimation, and numbered init attempts (1/3 GPU → 2/3 CPU → 3/3 CPU@2048) with full error chains on failure

Platform defaults:

Parameter iOS Android
Threads 4 6
Batch size 256 256
GPU layers 99 (Metal) 0 (disabled)
Context length 2048 2048

ActiveModelService (src/services/activeModelService/)

Singleton that manages which models are loaded in native memory. Split into index.ts, loaders.ts, memory.ts, types.ts, utils.ts.

Responsibilities:

  • Load/unload text models (llama.rn context creation)
  • Load/unload image models (LocalDream subprocess)
  • Memory budget enforcement (60% of device RAM max, warning at 50%)
  • Memory estimation: 1.5x file size for text, 1.8x for image
  • Automatic unload of previous model before loading new one
  • Observable pattern for UI subscriptions

ModelManager (src/services/modelManager/)

Handles model file lifecycle on disk. Split into index.ts, download.ts, downloadHelpers.ts, scan.ts, storage.ts, imageSync.ts, restore.ts, types.ts.

Responsibilities:

  • Download from Hugging Face (background downloads exclusively on both platforms)
  • Parallel mmproj downloads alongside main model for vision models
  • Import local .gguf files from device storage (Bring Your Own Model)
  • Store text models in Documents/local-llm/models/
  • Store image models in Documents/image_models/
  • Track downloaded model metadata in AsyncStorage
  • Handle vision model companion files (mmproj)
  • Verify file integrity
  • Delete models and clean up
  • Recover/restore downloads after app kill (both iOS and Android)
  • Image model download sync and recovery (imageSync.ts)

GenerationService (src/services/generationService.ts, 7KB)

Lifecycle-independent text generation manager.

Responsibilities:

  • Manage generation state outside of any screen's lifecycle
  • Subscriber pattern: screens subscribe/unsubscribe to generation state
  • Handles app backgrounding during generation
  • Tracks generation progress and completion

ImageGenerationService (src/services/imageGenerationService.ts, 10KB)

Lifecycle-independent image generation manager.

Responsibilities:

  • Orchestrate the full image generation pipeline
  • Listen to native LocalDreamProgress events
  • Save generated images to gallery store
  • Insert generated image as assistant message in chat
  • Preview path management during generation
  • Continue generating even when user navigates away

IntentClassifier (src/services/intentClassifier.ts, 12KB)

Determines whether a user message should trigger text generation or image generation.

Two-stage pipeline:

  1. Pattern matching (fast, no LLM needed):

    • 45+ image patterns: "draw", "generate image", "paint", "create a picture", art styles, DALL-E references, negative prompts, resolution specs
    • 40+ text patterns: questions ("what is", "how do"), code requests, math, analysis, explanation
    • Short messages (<10 chars) → text
    • Multiple sentences with punctuation → text

  2. LLM classification (fallback for ambiguous cases):

    • Simple yes/no prompt to the LLM
    • Can use a separate lightweight classifier model
    • Result cached (max 100 entries)
    • Falls back to text if LLM unavailable

HuggingFaceService (src/services/huggingface.ts, 15KB)

API client for model discovery.

Key methods:

  • searchModels(query, options) — GGUF filter, sort by downloads
  • getModelFiles(modelId) — List quantized files with sizes, auto-pair mmproj companions
  • getDownloadUrl(modelId, fileName) — Construct download URL

Credibility determination:

  • LM Studio authors (highest) → Official model creators → Verified quantizers → Community

WhisperService (src/services/whisperService.ts, 9KB)

Speech-to-text model management and transcription.

Models available:

Model Size Language
tiny.en 75 MB English only
tiny 75 MB Multilingual
base.en 142 MB English only
base 142 MB Multilingual
small.en 466 MB English only

Transcription modes:

  • Realtime: Streams partial results every ~3 seconds
  • File: Batch process a recorded audio file

AuthService (src/services/authService.ts, 3KB)

Passphrase management.

  • Hash passphrase with 1000 rounds of iteration
  • Store in device Keychain (encrypted native storage)
  • Methods: setPassphrase(), verifyPassphrase(), hasPassphrase(), removePassphrase()

BackgroundDownloadService (src/services/backgroundDownloadService.ts)

Bridge to native download managers on both platforms. This is now the only download method (foreground downloads removed).

  • Downloads continue even after app is killed (both Android and iOS)
  • Android: Persists download state in SharedPreferences, 500ms polling for progress; foreground service keeps downloads alive during doze
  • iOS: Uses background URLSession with delegate-based progress callbacks
  • Emits events: DownloadProgress, DownloadComplete, DownloadError
  • Moves completed files from Downloads temp to models directory
  • Tracks event delivery separately from completion status to prevent race conditions
  • Download restore after app kill via modelManager/restore.ts
  • Image model download sync/recovery via modelManager/imageSync.ts

Tool Calling Services (src/services/tools/, src/services/generationToolLoop.ts, src/services/llmToolGeneration.ts)

On-device function calling for compatible models.

Tool Registry (tools/registry.ts):

  • Defines 5 built-in tools: web_search, calculator, get_current_datetime, get_device_info, read_url
  • Converts tool definitions to OpenAI function calling schema for llama.cpp
  • Generates system prompt hints listing available tools

Tool Handlers (tools/handlers.ts):

  • web_search — Scrapes Brave Search, returns top 5 results with clickable URLs
  • calculator — Recursive descent parser (no eval()), supports +, -, *, /, %, ^, ()
  • get_current_datetime — Formatted date/time with optional timezone
  • get_device_info — Battery, storage, memory via react-native-device-info
  • read_url — Fetches and reads web page content, strips HTML, truncates to 80% of context window
  • search_knowledge_base — Semantic search over a project's RAG document store; only available in project conversations that have documents ingested

Tool Loop (generationToolLoop.ts):

  • Orchestrates multi-turn tool execution: LLM → parse → execute → inject → repeat
  • Hard limits: 3 iterations, 5 total tool calls
  • Supports structured tool calls AND fallback text parsing for smaller models:
    • JSON format: <tool_call>{"name":"web_search","arguments":{"query":"test"}}</tool_call>
    • XML-like format: <tool_call><function=web_search><parameter=query>test</tool_call>
    • Unclosed tags: handles models that hit EOS without emitting </tool_call>
  • Empty web search queries fall back to last user message
  • Retry with backoff (callLLMWithRetry): Up to 4 retries with linear backoff (1s, 2s, 3s, …) for transient native context errors ("Context is busy", "already in progress", etc.). Non-retryable errors ("No model loaded", "aborted") fail immediately.
  • Context release pause (500ms): Delay after tool execution before next LLM call, allowing native context to fully release

LLM Tool Generation (llmToolGeneration.ts):

  • Reserves ~100 tokens per tool in context window for schema injection
  • Passes tool schemas via tool_choice: 'auto' to llama.rn
  • Prefers completionResult.tool_calls over streamed tool calls — streaming may deliver partial tool calls (name only, no arguments) while the final result contains complete data
  • completionResult.text fallback: If streaming produced no tokens but the completion result has a .text field (can happen with thinking models), uses that as the response
  • Thinking model support: For models with <think> Jinja templates, injects <think> tag into stream for UI display while keeping fullResponse clean for tool call parsing

Remote LLM Providers (src/services/providers/)

A provider abstraction that allows generationService to route text generation to either a local GGUF model or a remote OpenAI-compatible server transparently.

LLMProvider interface (all providers implement):

  • generate(messages, options, callbacks) — streaming generation
  • loadModel(modelId) / unloadModel() / isModelLoaded() / getLoadedModelId()
  • capabilities — { supportsVision, supportsToolCalling, supportsThinking }

LocalProvider wraps llmService. Generation delegates to llama.rn. Model loading state is tracked separately from llmService (which is managed by activeModelService).

OpenAICompatibleProvider streams from a remote server:

  • Builds OpenAI-format messages array (including base64 image parts for vision)
  • Streams via XMLHttpRequest onprogress with incremental SSE parsing
  • Accumulates tool call deltas across chunks and delivers complete calls at finish_reason
  • Guarantees onComplete is called even for finish_reason: 'length' or absent finish reasons
  • Calls this.abortController.abort() on API error to immediately stop the XHR

ProviderRegistry singleton:

  • Maintains Map<id, LLMProvider> + activeProviderId
  • generationService reads activeServerId from remoteServerStore and calls providerRegistry.getProvider(activeServerId) for each generation
  • Notifies subscribers on provider change (used to keep activeServerId store in sync)

Remote Server Manager (src/services/remoteServerManager.ts)

Singleton that owns the lifecycle of remote server configurations and their providers.

  • Add/update/remove servers, creating/destroying the corresponding OpenAICompatibleProvider
  • API key storage: keys stored via react-native-keychain under service name ai.offgridmobile.servers; never written to AsyncStorage or the Zustand store
  • Model discovery: calls /v1/models and maps results to RemoteModel with capability heuristics
  • Connection testing: testConnectionByEndpoint() — pings health endpoints in order (Ollama, generic OpenAI)
  • Active model selection: setActiveRemoteTextModel(serverId, modelId) loads the model on the provider and updates remoteServerStore
  • App startup: initializeProviders() must be called in App.tsx to re-register providers and re-discover models for all persisted servers

HTTP Client (src/services/httpClient.ts)

Low-level HTTP utilities for remote server communication.

  • createStreamingRequest(url, body, headers, onEvent, timeout, signal?) — XHR-based SSE streaming. AbortSignal wires directly to xhr.abort() so cancellations propagate immediately.
  • processSSELines(data, onEvent) — incremental SSE line parser that handles partial lines across onprogress calls
  • testEndpoint(endpoint, apiKey?) — tries Ollama /api/tags, then OpenAI /v1/models; returns ServerTestResult
  • detectServerType(endpoint) — heuristic detection of server software (Ollama, LM Studio, LocalAI)
  • isPrivateNetworkEndpoint(endpoint) — returns false for public internet IPs/hostnames; used to warn users
  • imageToBase64DataUrl(uri) — converts a file:// image URI to a base64 data URL for vision requests

RAG Knowledge Base (src/services/rag/)

Project-scoped retrieval-augmented generation pipeline running entirely on-device.

Ingestion flow:

  1. documentService.ingestDocumentToKnowledgeBase(projectId, attachment) — called from KnowledgeBaseScreen
  2. ragService.ingestDocument(projectId, filePath, name, mimeType) — orchestrates chunking + embedding + storage
  3. chunking.chunkText(text) — splits by paragraph; oversized paragraphs use sliding-window with overlap
  4. embedding.embedText(text) — calls llama.rn in embedding mode with the bundled all-MiniLM-L6-v2-Q8_0.gguf; returns a 384-dim float vector
  5. database.insertChunks(chunks) — stores text + JSON-serialised vector in op-sqlite

Retrieval flow (called by search_knowledge_base tool):

  1. ragService.searchProject(projectId, query, topK=5)
  2. Query text is embedded with the same MiniLM model
  3. All chunks for the project are loaded from SQLite and cosine-similarity scored against the query vector
  4. Top-K chunks are returned sorted by score
  5. retrieval.formatForPrompt(chunks) wraps them in <knowledge_base>…</knowledge_base> XML for the LLM

vectorMath.ts: Pure TypeScript cosine similarity — no native dependency, fully testable.

Database schema (op-sqlite):

documents(id, project_id, name, file_path, file_size, mime_type, created_at)
chunks(id, document_id, project_id, content, position, embedding TEXT)

8. Native Integration Layer

Android Native Modules

LocalDreamModule (android/.../localdream/LocalDreamModule.kt)

Stable Diffusion image generation via a native subprocess.

Architecture:

  • Spawns libstable_diffusion_core.so as a subprocess
  • Subprocess runs an HTTP server on localhost:18081
  • TypeScript layer makes HTTP POST requests for generation
  • Receives SSE (Server-Sent Events) stream with progress + base64 preview images

Backend support:

Backend Hardware Model Format Files
MNN (CPU) All Android .mnn CLIP, UNet, VAE decoder, tokenizer
QNN (NPU) Qualcomm Snapdragon .bin Same components, Hexagon DSP optimized

Key native methods:

  • loadModel(path), unloadModel(), isModelLoaded()
  • generateImage(prompt, negativePrompt, steps, guidanceScale, width, height, seed)
  • cancelGeneration()
  • saveRgbAsPng(base64, width, height, path)
  • isNpuSupported() — checks for Qualcomm chipset

QNN runtime libraries: Extracted from assets to runtime_libs/:

  • libQnnHtp.so (Hexagon DSP backend)
  • libQnnSystem.so (QNN system library)

DownloadManagerModule (android/.../download/DownloadManagerModule.kt)

Android system DownloadManager integration with foreground service support.

Key native methods:

  • startDownload(url, fileName) — enqueues in system DownloadManager and starts DownloadForegroundService
  • cancelDownload(downloadId) — cancels download and stops foreground service if no active downloads remain
  • getActiveDownloads() — reads from SharedPreferences
  • getDownloadProgress(downloadId) — queries DownloadManager
  • moveCompletedDownload(downloadId, destPath) — moves from temp to models dir
  • startProgressPolling() / stopProgressPolling() — 500ms interval

Foreground service lifecycle:

  • DownloadForegroundService (dataSync type) starts when any download is enqueued
  • Automatically stopped via stopForegroundServiceIfIdle() when all downloads reach a terminal state (completed, failed, or cancelled)
  • Prevents Android doze/battery-saver from throttling or pausing large downloads
  • Non-fatal: if the service fails to start/stop, download continues normally

iOS Native Modules

CoreMLDiffusionModule (ios/.../CoreMLDiffusion/CoreMLDiffusionModule.swift)

Stable Diffusion image generation via Apple's ml-stable-diffusion Core ML pipeline.

Architecture:

  • In-process StableDiffusionPipeline (no subprocess)
  • Core ML auto-dispatches across CPU, GPU (Metal), and ANE (Apple Neural Engine)
  • DPM-Solver multistep scheduler for faster convergence
  • reduceMemory mode for iPhones with limited RAM

Key native methods:

  • loadModel(params), unloadModel(), isModelLoaded()
  • generateImage(params) — with step-by-step progress callbacks
  • cancelGeneration() — boolean flag checked between steps
  • isNpuSupported() — always true (Core ML uses ANE automatically)

Model format: .mlmodelc compiled Core ML models from Apple's HuggingFace repos.

DownloadManagerModule (ios/.../Download/DownloadManagerModule.swift)

iOS background download manager using URLSession with background configuration.

Key differences from Android:

  • Delegate-based progress callbacks (not polling)
  • Survives app suspension but NOT user force-quit
  • Temporary file on completion must be moved immediately

Additional iOS dependencies:

  • llama.rn for Metal-accelerated LLM inference (99 GPU layers by default)
  • whisper.rn for speech-to-text
  • Standard RN library natives for everything else

Third-Party Native Bindings

Package Native Functionality
llama.rn llama.cpp context creation, completion streaming, GPU offload
whisper.rn whisper.cpp context, realtime + file transcription
react-native-fs File read/write/download/stat/mkdir
react-native-device-info RAM, device model, OS, emulator detection
react-native-keychain Encrypted credential storage
react-native-image-picker Camera and gallery image selection
react-native-zip-archive Model archive extraction

9. Product Flows — Detailed

This section expands on every testable flow, grouped by feature area. Each flow includes the trigger, step-by-step behavior, services/stores involved, and edge cases.

9.1 App Initialization & Onboarding

9.1.1 Cold Start Sequence

Trigger: User taps app icon (fresh install or subsequent launch).

Steps:

  1. App.tsx mounts → shows loading screen
  2. Hardware service queries device info (RAM, model, OS) → stores in appStore.deviceInfo
  3. Model recommendations calculated from RAM tier → appStore.modelRecommendation
  4. ModelManager syncs downloaded models list (verifies files still exist on disk)
  5. On Android: sync background download state from SharedPreferences
  6. AuthStore checked: if isEnabled && passphrase exists → show LockScreen
  7. Otherwise, check hasCompletedOnboarding:
    • false → navigate to OnboardingScreen
    • true + no downloaded models → ModelDownloadScreen
    • true + has models → MainTabs

Services: HardwareService, ModelManager, AuthService, BackgroundDownloadService (Android) Stores: appStore, authStore

9.1.2 Onboarding Flow

Trigger: First app launch (hasCompletedOnboarding === false).

Steps:

  1. Display 4 slides: Welcome → Privacy → Offline → Choose Model
  2. User swipes through or taps "Next"
  3. On final slide, tap "Get Started"
  4. appStore.setHasCompletedOnboarding(true)
  5. Navigate to ModelDownloadScreen

Slides content:

Slide Title Message
1 Welcome to Off Grid Run AI models directly on your device. No internet required, complete privacy.
2 Your Privacy Matters All conversations stay on your device. No data is sent to any server.
3 Works Offline Once you download a model, it works without internet.
4 Choose Your Model Smaller models are faster, larger models are smarter. We'll help you pick.

9.1.3 First Model Download

Trigger: Onboarding complete, no models downloaded.

Steps:

  1. ModelDownloadScreen shows recommended models filtered by device RAM
  2. Each card shows: model name, parameter count, size estimate, description
  3. User selects a model → download begins
  4. Progress bar shows percentage + bytes
  5. On completion → navigate to MainTabs (Home)
  6. User can also tap "Skip" → goes to Home with no model (shows "download a model" prompt)

Recommendations by RAM:

Device RAM Max Parameters Suggested Quantization
3–4 GB 1.5B Q4_K_M
4–6 GB 3B Q4_K_M
6–8 GB 4B Q4_K_M
8–12 GB 8B Q4_K_M
12–16 GB 13B Q4_K_M
16+ GB 30B Q4_K_M

9.2 Authentication & Security

9.2.1 Passphrase Setup

Trigger: Settings → Security → Enable Passphrase.

Steps:

  1. Navigate to PassphraseSetupScreen
  2. Enter passphrase (first field)
  3. Confirm passphrase (second field)
  4. Validation: entries must match
  5. On mismatch → error message, fields cleared
  6. On match → authService.setPassphrase(hash) → stored in Keychain
  7. authStore.setEnabled(true)
  8. Navigate back to Settings

Service: AuthService (hashes with 1000 iteration rounds, stores in Keychain)

9.2.2 App Lock Trigger

Trigger: App goes to background while auth is enabled.

Steps:

  1. useAppState hook detects AppState → background
  2. authStore.lastBackgroundTime set to Date.now()
  3. When app returns to foreground:
    • Check if enough time has passed (immediate lock currently)
    • authStore.setLocked(true)
    • LockScreen renders over entire app

9.2.3 Unlock Flow

Trigger: User enters passphrase on LockScreen.

Steps:

  1. Check lockout: if lockoutUntil > now → show countdown timer (MM:SS), input disabled
  2. User enters passphrase → authService.verifyPassphrase(input)
  3. Correct: authStore.setLocked(false), resetFailedAttempts() → app unlocks
  4. Incorrect: authStore.recordFailedAttempt()
    • failedAttempts++
    • If failedAttempts >= 5 → lockoutUntil = now + 5 minutes
    • Show error + remaining attempts count
  5. Lockout persists across app restart (lockoutUntil is persisted)

9.3 Model Browsing & Download

9.3.1 Browse Text Models

Trigger: Navigate to Models tab.

Steps:

  1. ModelsScreen loads → shows curated recommended models filtered by device RAM
  2. Recommended models fetched from HuggingFace API with real metadata (excludes already downloaded)
  3. Each ModelCard shows: name, author tag, description, credibility badge, action icons
  4. User can:
    • Search: type query → fetches from HuggingFace API with search term
    • Filter by organization: Qwen, Meta, Google, Microsoft, Mistral, DeepSeek, HuggingFace, NVIDIA
    • Filter by size: tiny (<1B), small (1-3B), medium (3-8B), large (8B+)
    • Filter by quantization: Q4_K_M, Q4_K_S, Q5_K_M, Q6_K, Q8_0
    • Filter by type: Text, Vision, Code
    • Filter by credibility: LM Studio, Official, Verified, Community
    • Import local model: Import .gguf files from device storage via file picker
    • Pull to refresh: re-fetches from API
    • Scroll for more: pagination / infinite scroll

Filter UI:

  • Filter pills with expandable sections for multi-select options
  • Active filter indicator dot on filter toggle button
  • Clear all filters button
  • Filters persist within the session

Credibility badges:

Badge Color Meaning
LM Studio Cyan (#22D3EE) Official LM Studio quantization — highest quality GGUF
Official Green (#22C55E) From the original model creator (Meta, Microsoft, Qwen, etc.)
Verified Purple (#A78BFA) From trusted quantizers (TheBloke, bartowski, etc.)
Community Gray (#64748B) Community contributed

9.3.2 View Model Files

Trigger: Tap a model card to expand.

Steps:

  1. Calls huggingFaceService.getModelFiles(modelId)
  2. Uses HF tree API (preferred) with fallback to siblings array
  3. Filters for .gguf files only
  4. Sorts by size (ascending)
  5. Displays for each file: filename, quantization level (e.g., Q4_K_M), size (GB/MB)
  6. For vision models: auto-pairs mmproj companion file with matching quantization
  7. Shows quantization quality indicator (Low → Excellent)

9.3.3 Download Text Model (Background — Both Platforms)

Trigger: Tap download button on a model file.

Steps:

  1. Construct download URL: https://huggingface.co/{modelId}/resolve/main/{fileName}
  2. First download triggers notification permission rationale dialog (if not yet granted)
  3. backgroundDownloadService.startDownload(url, fileName) enqueues in native download manager
  4. Android: System DownloadManager with SharedPreferences tracking, 500ms polling for progress
  5. iOS: Background URLSession with delegate-based progress callbacks
  6. UI shows: progress bar, percentage, bytes downloaded / total
  7. File saved to Documents/local-llm/models/{fileName}
  8. If vision model: mmproj file downloaded in parallel alongside main model
  9. On completion:
    • File moved from temp location to models directory
    • Create DownloadedModel metadata object
    • Save to appStore.downloadedModels[]
    • Persist metadata to AsyncStorage
  10. Model appears in "Downloaded" section and model selector

Cancellation: User taps cancel → download cancelled → partial file cleaned up

Recovery after app kill: On next launch, restore.ts recovers download state from native storage (SharedPreferences on Android, URLSession on iOS)

States: pending → running → paused → completed / failed

9.3.4 Import Local Model (Bring Your Own Model)

Trigger: Tap "Import local .gguf" button on Models screen.

Steps:

  1. Native file picker opens via @react-native-documents/picker (filtered to all files)
  2. User selects a .gguf file from device storage
  3. Validation: file must have .gguf extension
  4. On Android: if URI is content://, file is first copied to app cache directory
  5. File size determined, duplicate check against existing downloaded models
  6. File copied to Documents/local-llm/models/{fileName} with progress tracking (500ms polling)
  7. Model name and quantization parsed from filename (e.g., qwen3-3b-q4_k_m.gguf → name: "qwen3-3b", quant: "Q4_K_M")
  8. DownloadedModel metadata created with source: 'local-import'
  9. Saved to appStore.downloadedModels[]
  10. Model appears in model selector, ready to load

Error handling:

  • Non-GGUF files → error alert
  • Duplicate model → error alert with existing model name
  • Copy failure → cleanup partial file, error alert

Implementation: modelManager.importLocalModel() in src/services/modelManager.ts

9.3.5 Download Image Model

Trigger: Tap download on an image model card.

Steps:

  1. Download archive (.zip) containing model components
  2. Extract via react-native-zip-archive
  3. Components: CLIP text encoder, UNet, VAE decoder, tokenizer JSON
  4. Stored in Documents/image_models/{modelName}/
  5. Create ONNXImageModel metadata with detected backend (mnn/qnn) and style
  6. Save to appStore.downloadedImageModels[]

9.3.6 Delete Model

Trigger: Long-press model in Downloaded section → Delete, or from Storage Settings.

Steps:

  1. Show confirmation dialog ("This will permanently delete the model file")
  2. If model is currently loaded → warn that it will be unloaded first
  3. activeModelService.unloadTextModel() if needed
  4. RNFS.unlink(filePath) → delete from disk
  5. If vision model: also delete mmproj file
  6. Remove from appStore.downloadedModels[]
  7. Update AsyncStorage

9.4 Model Loading & Memory

9.4.1 Load Text Model

Trigger: Tap model in selector, or auto-load on chat entry if activeModelId set.

Steps:

  1. Check memory budget: estimatedMemory = fileSize * 1.5
  2. If exceeds 60% of device RAM → show warning, possibly refuse
  3. If another model loaded → unload first (free context, clear KV cache)
  4. llmService.initContext() with parameters:
    • model: file path
    • n_ctx: from settings (default 2048)
    • n_threads: platform default
    • n_batch: 256
    • n_gpu_layers: iOS Metal = 99, Android = 0
    • Optional: mmproj path for vision models
  5. UI shows loading indicator
  6. On success:
    • appStore.setActiveModelId(id)
    • Detect multimodal support (initMultimodal())
    • Show "Model loaded" system message in chat
    • Display load time
  7. On failure:
    • OOM → suggest smaller model
    • Corrupt file → suggest re-download
    • Unknown error → show error + retry option

9.4.2 Unload Text Model

Trigger: Explicit unload from UI, or automatic before loading different model.

Steps:

  1. If generation in progress → stop it first
  2. llmService.releaseContext() → frees native memory
  3. Clear KV cache
  4. appStore.setActiveModelId(null)
  5. Show "Model unloaded" system message
  6. Display freed memory estimate

9.4.3 Load Image Model

Trigger: Image generation requested, or manual load from model selector.

Steps:

  1. Memory check: estimatedMemory = modelSize * 1.8
  2. LocalDreamModule.loadModel(modelPath) → starts subprocess
  3. Subprocess loads CLIP, UNet, VAE components
  4. Detects backend (MNN vs QNN based on file extensions)
  5. If QNN model on non-Qualcomm device → falls back to MNN
  6. appStore.setActiveImageModelId(id)

9.4.4 Model Loading Strategies

Performance mode ('performance'):

  • Model stays loaded in RAM across generations
  • Faster response times (no load latency between messages)
  • Higher memory usage
  • Session caching works optimally
  • Intent classifier can swap to classifier model and swap back

Memory mode ('memory'):

  • Model loaded on demand before each generation
  • Unloaded after generation completes
  • Lower peak memory usage
  • Slower (load time added to each generation)
  • Suitable for devices with < 6GB RAM

9.5 Text Generation

9.5.1 Send Message & Generate Response

Trigger: User types message and taps Send.

Steps:

  1. Validate: message not empty/whitespace-only, model loaded
  2. Create Message object with role: 'user', add to conversation via chatStore.addMessage()
  3. Clear input field
  4. Intent classification (if image mode is 'auto'):
    • Run pattern matching on message text
    • If uncertain and autoDetectMethod === 'llm': classify via LLM
    • If intent is 'image' → route to image generation (see 9.6)
  5. Build message context:
    • System prompt (from project if linked, else from settings)
    • Conversation history (truncated to fit context window at 85% utilization)
    • Current user message
  6. generationService.startGeneration() → llmService.completion()
  7. Streaming phase:
    • chatStore.setStreaming(true)
    • Tokens arrive via callback → chatStore.updateStreamingMessage(token)
    • <think> tags detected → isThinking = true (content shown in collapsible block)
    • UI auto-scrolls to follow new tokens
    • Stop button appears
  8. Completion:
    • Final message saved to conversation with generationMeta:
      • tokensPerSecond, decodeTokensPerSecond, timeToFirstToken, tokenCount
      • gpu (boolean), gpuBackend, gpuLayers
      • kvCacheType, flashAttention
      • modelName
    • generationTimeMs recorded
    • chatStore.setStreaming(false)
    • Conversation updatedAt timestamp updated
    • If tool calling enabled and model supports it, enters tool loop (see Tool Calling Services)

9.5.2 Stop Generation

Trigger: User taps Stop button during streaming.

Steps:

  1. llmService.stopCompletion() → signals native to stop
  2. Current partial response is kept (not discarded)
  3. Message finalized with partial content + metadata
  4. Streaming state cleared
  5. User can send new message immediately

9.5.3 Retry Generation

Trigger: User taps retry on an assistant message.

Steps:

  1. Delete the assistant message being retried
  2. Re-send the preceding user message through the generation pipeline
  3. New response streams in to replace the old one

9.5.4 Context Window Management

How it works:

  1. Before each generation, tokenize the full context (system + history + current)
  2. If token count exceeds contextLength * 0.85:
    • Drop oldest messages (keeping system prompt + most recent messages)
    • Re-tokenize to verify fit
  3. If KV cache is full → clear cache and rebuild context
  4. Safety margin prevents overflows that would crash native inference

9.5.5 Thinking Blocks

Trigger: Model outputs <think>...</think> tags.

Behavior:

  1. Parser detects <think> opening tag
  2. isThinking flag set on streaming message
  3. Content inside tags rendered in a collapsible/dimmed block
  4. </think> tag detected → isThinking = false
  5. Content after closing tag rendered normally
  6. Final message preserves thinking content (viewable on expand)

9.5.6 Generation Metadata Display

When showGenerationDetails is enabled in settings:

Metric Source Display
Tokens/sec (overall) tokensPerSecond "12.3 tok/s"
Tokens/sec (decode) decodeTokensPerSecond "15.1 tok/s decode"
Time to first token timeToFirstToken "0.8s TTFT"
Total tokens tokenCount "342 tokens"
GPU used gpu + gpuBackend "Metal" or "CPU"
GPU layers gpuLayers "99 layers"
Model name modelName "Qwen2.5-3B-Q4_K_M"
Generation time generationTimeMs "28.4s"

9.6 Image Generation

9.6.1 Auto-Triggered Image Generation

Trigger: User sends message that intent classifier routes to image generation.

Steps:

  1. Intent classified as 'image' (see 9.5.1 step 4)
  2. Check: image model loaded?
    • No → attempt to load activeImageModelId
    • Still no → show "No image model" error
  3. Create user message in conversation
  4. imageGenerationService.generate() with params:
    • prompt: user's message
    • negativePrompt: from settings (if configured)
    • steps: from settings (default varies by model)
    • guidanceScale: from settings
    • width, height: from settings
    • seed: random (or specified)
  5. Progress phase:
    • Native module emits LocalDreamProgress events
    • UI shows: step counter ("Step 5/20"), progress bar, preview thumbnail
    • Preview images update every few steps (base64 → PNG → display)
  6. Completion:
    • Final RGB data received as base64
    • Saved as PNG via LocalDreamModule.saveRgbAsPng()
    • GeneratedImage created with full metadata
    • Added to appStore.generatedImages[]
    • Assistant message added to conversation with image attachment
    • Generation meta includes: steps, guidanceScale, resolution, seed

9.6.2 Manual/Forced Image Generation

Trigger: User toggles image mode to "Force" in chat input, then sends any message.

Steps:

  1. Image mode toggle in ChatInput → ImageModeState = 'force'
  2. Visual indicator shows image mode is active
  3. Any message sent bypasses intent classification → routes directly to image generation
  4. Same pipeline as 9.6.1 from step 2 onward

9.6.3 Cancel Image Generation

Trigger: User taps Stop during image generation progress.

Steps:

  1. imageGenerationService.cancel() → LocalDreamModule.cancelGeneration()
  2. Current partial image may be available (from preview)
  3. Generation state cleared
  4. No image added to gallery or conversation

9.6.4 Image Generation Parameters

Parameter Range Default Effect
Steps 1–50 Model-dependent More steps = higher quality, slower
Guidance Scale 1.0–20.0 7.5 Higher = stricter prompt following
Width 128–512 (multiples of 64) 512 Image width in pixels
Height 128–512 (multiples of 64) 512 Image height in pixels
Negative Prompt Free text Empty What to exclude from generation
Seed Integer Random Reproducibility (same seed = same image)

9.6.5 Backend Selection

Backend Hardware Speed Quality Detection
MNN (CPU) All Android Slower Good Default fallback
QNN (NPU) Qualcomm Snapdragon (SM/QCS/QCM) 3-5x faster Same Auto-detected via isNpuSupported()

Auto-selection: If QNN model downloaded and device supports QNN → use QNN. Otherwise → MNN.

9.7 Vision Models (Image Understanding)

9.7.1 Load Vision Model

Trigger: Select a vision-capable model (has mmproj companion file).

Steps:

  1. Same loading flow as 9.4.1
  2. Additionally: llmService.initContext() receives mmproj path
  3. initMultimodal() called → enables image input processing
  4. Vision capability indicator shown in UI

9.7.2 Send Image for Analysis

Trigger: User attaches image (camera or gallery) + sends message.

Steps:

  1. Tap attachment button → choose Camera or Gallery
  2. Image selected → MediaAttachment created with type: 'image'
  3. Thumbnail shown in input area
  4. User types prompt (e.g., "What's in this image?") + sends
  5. Message created with attachments array containing the image
  6. Image passed to llama.rn context alongside text
  7. Vision encoder (mmproj) processes the image
  8. Text model generates response about the image
  9. Response streams normally with metadata

9.7.3 Document Attachment

Trigger: User attaches a document (.txt, .py, .js, etc.).

Steps:

  1. Tap attachment button → choose Document
  2. documentService.extractText(uri) → extracts text content
  3. MediaAttachment created with type: 'document', textContent populated
  4. Preview shows filename + text snippet
  5. On send: text content included in prompt context
  6. Model can reference and analyze document content

9.8 Voice Input

9.8.1 Voice Recording & Transcription

Trigger: Long-press or tap microphone button in ChatInput.

Steps:

  1. Check microphone permission → request if not granted
  2. Check Whisper model availability:
    • Not downloaded → prompt to download (navigate to Voice Settings)
    • Downloaded but not loaded → load model
  3. Start recording → voiceService.startRecording()
  4. UI shows: recording indicator, duration timer, waveform visualization
  5. User releases / taps stop → recording ends
  6. Audio sent to whisperService.transcribeRealtime():
    • Processes in chunks
    • Partial results update in real-time
    • Final transcription returned
  7. Transcribed text inserted into chat input field
  8. User can edit before sending

9.8.2 Whisper Model Management

Trigger: Voice Settings screen.

Steps:

  1. List available Whisper models with sizes
  2. User selects and downloads a model
  3. Download progress shown
  4. On completion: model stored in Documents/whisper-models/
  5. whisperStore.downloadedModelId set
  6. Model loaded on first transcription request

9.9 Conversations

9.9.1 Create Conversation

Trigger: "New Chat" button on Home or Chats tab.

Steps:

  1. chatStore.createConversation() creates new Conversation:
    • Generated UUID
    • Title: "New Conversation" (auto-updated after first message)
    • modelId: current activeModelId
    • projectId: if started from a project
    • Empty messages[]
    • Timestamps set
  2. Navigate to ChatScreen with new conversation

9.9.2 Auto-Generate Title

Trigger: First user message sent in a conversation.

Steps:

  1. After first response completes
  2. Title derived from first message content (truncated)
  3. chatStore.updateConversation() updates title

9.9.3 Switch Conversations

Trigger: Tap a conversation in ChatsListScreen.

Steps:

  1. If generation in progress → warn user (generation will stop)
  2. chatStore.setActiveConversationId(newId)
  3. Navigate to ChatScreen
  4. Messages loaded from store (already in memory, persisted)
  5. Scroll to bottom

9.9.4 Delete Conversation

Trigger: Swipe-to-delete or long-press → Delete.

Steps:

  1. Show confirmation dialog
  2. chatStore.deleteConversation(id):
    • Remove from conversations[]
    • All messages deleted
  3. Associated gallery images remain (not cascade-deleted)
  4. If was active conversation → navigate to conversations list

9.9.5 Projects Integration

Trigger: Start chat from a project, or select project in chat.

Steps:

  1. chatStore.createConversation() with projectId set
  2. System prompt from projectStore.projects[].systemPrompt used instead of default
  3. Project badge shown in chat header and conversation list
  4. If project deleted later → conversation keeps its system prompt (snapshot)

9.10 Gallery

9.10.1 View Gallery

Trigger: Navigate to Gallery tab/modal.

Steps:

  1. Load appStore.generatedImages[]
  2. Display as 3-column grid, sorted by createdAt (most recent first)
  3. Each thumbnail loaded from imagePath on disk
  4. Filter dropdown: "All" or specific conversation

9.10.2 Image Detail View

Trigger: Tap an image thumbnail.

Steps:

  1. Open fullscreen viewer
  2. Pinch to zoom, pan to navigate
  3. View metadata: prompt, negative prompt, steps, seed, guidance scale, resolution, model, timestamp
  4. Actions: Share, Save to Device, Delete

9.10.3 Save to Device

Trigger: Tap Save in image viewer.

Steps:

  1. Copy image to device-accessible location:
    • Android: Pictures/OffgridMobile/ or Documents/OffgridMobile_Images/
    • iOS: Camera Roll (via photo library API)
  2. Show success confirmation

9.10.4 Multi-Select & Batch Delete

Trigger: Enter selection mode (long-press an image).

Steps:

  1. Selection mode activated → checkboxes appear on thumbnails
  2. Tap to select/deselect individual images
  3. "Select All" option available
  4. Tap "Delete Selected"
  5. Confirmation dialog
  6. Delete selected images from disk + remove from appStore.generatedImages[]

9.11 Settings

9.11.1 Text Generation Settings

Setting Type Range Default Effect
System Prompt Text area Free text (see APP_CONFIG) Personality/behavior instructions
Temperature Slider 0.0 – 2.0 0.7 Randomness (low = deterministic, high = creative)
Top-P Slider 0.0 – 1.0 0.9 Nucleus sampling threshold
Repeat Penalty Slider 1.0 – 2.0 1.1 Penalizes token repetition
Max Tokens Input 1 – 4096+ 512 Maximum response length
Context Length Input 512 – 8192 2048 Conversation history window
Threads Slider 1 – device max 4 (iOS) / 6 (Android) CPU threads for inference
Batch Size Input 1 – 512 256 Token processing batch
GPU Toggle On/Off iOS: On, Android: Off GPU acceleration
GPU Layers Slider 0 – 99 iOS: 99, Android: 0 Layers offloaded to GPU
Loading Strategy Toggle Performance / Memory Performance Keep model loaded vs load-on-demand
Show Details Toggle On/Off Off Show generation metadata on messages

9.11.2 Image Generation Settings

Setting Type Range Default
Steps Slider 1 – 50 Model-dependent
Guidance Scale Slider 1.0 – 20.0 7.5
Width Input 128 – 512 512
Height Input 128 – 512 512
Threads Slider 1 – device max Platform default

9.11.3 Intent Detection Settings

Setting Options Effect
Image Generation Mode Auto / Manual Auto detects intent; Manual requires explicit toggle
Auto-Detect Method Pattern / LLM Pattern-only (fast) vs Pattern + LLM fallback (accurate)
Classifier Model (model selector) Which model to use for LLM classification

All settings auto-save on change (no save button needed) and persist across app restarts.

9.12 App Lifecycle

9.12.1 Background / Foreground

Trigger: User switches apps, locks phone, or presses home button.

Going to background:

  1. useAppState detects AppState → background
  2. authStore.lastBackgroundTime recorded
  3. Generation services continue (lifecycle-independent)
  4. Background downloads continue (Android)

Returning to foreground:

  1. useAppState detects AppState → active
  2. If auth enabled → authStore.setLocked(true) → show LockScreen
  3. Refresh device info (available memory may have changed)
  4. If generation completed while backgrounded → messages already in store

9.12.2 Force Kill & Recovery

Trigger: User swipes away app or system kills it.

Recovery on next launch:

  1. All Zustand persisted stores rehydrated from AsyncStorage
  2. Conversations, messages, settings all restored
  3. Active model ID remembered (but model not loaded — needs re-load)
  4. Background downloads (Android): synced from SharedPreferences
  5. Streaming state cleared (was not persisted)
  6. Any partial generation is lost (the streaming message was not saved)

9.12.3 Generation During Background

Text generation: Continues via generationService (lifecycle-independent). When user returns, streaming message and final result are in the store.

Image generation: Continues via imageGenerationService. Progress events accumulate. When user returns to chat, they see current progress or completed image.

Background downloads (Android): Android DownloadManager continues independently. On next app open, syncBackgroundDownloads() queries system for status.

9.13 Intent Classification — Detailed

The intent classifier determines whether a user's message should trigger text generation or image generation.

Classification Pipeline

User message
    │
    ▼
[1] Quick checks ─────────────────────────────────────────┐
    │ • Message < 10 chars → TEXT                         │
    │ • Multiple sentences → TEXT                          │
    │ • Exact code/question keywords → TEXT                │
    │                                                      │
    ▼                                                      │
[2] Image pattern matching ────────────────────────────────┤
    │ • 45+ patterns: "draw", "generate image",           │
    │   "paint", art styles, DALL-E, negative prompt,     │
    │   resolution specifications                          │
    │ • Match found → IMAGE                               │
    │                                                      │
    ▼                                                      │
[3] Text pattern matching ─────────────────────────────────┤
    │ • 40+ patterns: questions, code, math, analysis,    │
    │   explanation, help requests                         │
    │ • Match found → TEXT                                │
    │                                                      │
    ▼                                                      │
[4] Ambiguous — check autoDetectMethod ────────────────────┤
    │                                                      │
    ├── 'pattern' mode → default TEXT                      │
    │                                                      │
    └── 'llm' mode → [5] LLM Classification               │
                          │                                │
                          ▼                                │
                    Prompt: "Is this asking to             │
                    create/generate/draw an image?"        │
                          │                                │
                          ├── "yes" → IMAGE                │
                          ├── "no" → TEXT                  │
                          └── error → TEXT (fallback)      │
                                                           │
                    Result cached (max 100 entries) ◄──────┘

Example Classifications

Input Classification Stage Reason
"Hi" TEXT Quick check < 10 chars
"Draw a cat" IMAGE Image patterns Matches "draw"
"What is Python?" TEXT Text patterns Matches "what is"
"A beautiful sunset over mountains" TEXT (pattern) or IMAGE (LLM) Ambiguous No clear pattern; LLM may classify as image
"Generate an oil painting of a forest" IMAGE Image patterns Matches "generate" + "oil painting"
"Write a function to sort an array" TEXT Text patterns Matches "write a function"

9.14 Error Handling

Network Errors

Scenario Handling
No internet during model browse Error message + "Retry" button
Network drop during download (foreground) Error + "Resume" option (HTTP range requests)
Network drop during download (background) Android DownloadManager pauses; resumes when network returns
HuggingFace API timeout Timeout error + retry

Model Errors

Scenario Handling
Corrupt model file Detection on load → error + "Delete and re-download" suggestion
OOM during model load Error + "Try a smaller model" suggestion
Model file deleted externally Detected during sync → removed from list
Incompatible model version Error message during load

Generation Errors

Scenario Handling
OOM during text generation Error message + suggest reducing context length
Native crash during generation Graceful error message, generation state cleared
Image generation failure Error message, no image added
No model loaded when sending Prompt to load a model

Storage Errors

Scenario Handling
Insufficient storage before download Pre-check + error with space requirements
Storage full mid-download Download fails gracefully, partial file cleaned up
File system permission denied Error message

10. Testing Infrastructure

Unit Tests (__tests__/unit/)

Test File Covers
stores/appStore.test.ts App store state transitions
stores/chatStore.test.ts Conversation CRUD, message management
stores/authStore.test.ts Auth state, lockout logic
stores/projectStore.test.ts Project CRUD
stores/whisperStore.test.ts Whisper model state
services/generationService.test.ts Text generation lifecycle
services/generationToolLoop.test.ts Tool loop orchestration
services/intentClassifier.test.ts Pattern matching, LLM fallback
services/llm.test.ts Model loading, GPU fallback, generation, context
services/llmMessages.test.ts Message building/formatting
services/llmToolGeneration.test.ts Tool-aware LLM generation
services/hardware.test.ts Device info, memory calculations, recommendations
services/modelManager.test.ts Download lifecycle, storage, orphan detection
services/downloadHelpers.test.ts Download helper utilities
services/restore.test.ts Download restore after app kill
services/parallelMmproj.test.ts Parallel mmproj download
services/backgroundDownloadService.test.ts Native events, polling lifecycle
services/localDreamGenerator.test.ts Platform routing, iOS/Android delegation
services/imageGenerator.test.ts Image generator helper
services/imageModelRecommendation.test.ts Image model recommendations
services/coreMLModelBrowser.test.ts Model discovery, caching, errors
services/huggingFaceModelBrowser.test.ts Image model browsing
services/whisperService.test.ts Transcription, permissions
services/voiceService.test.ts Voice input bridge
services/documentService.test.ts File types, reading, preview
services/pdfExtractor.test.ts PDF text extraction
services/huggingface.test.ts HuggingFace API client
services/authService.test.ts Auth service
tools/handlers.test.ts Tool execution handlers
tools/registry.test.ts Tool definitions & schema
hooks/useAppState.test.ts App state foreground/background
hooks/useChatGenerationActions.test.ts Chat generation actions
hooks/useChatModelActions.test.ts Chat model actions
hooks/useNotifRationale.test.ts Notification rationale
hooks/useVoiceRecording.test.ts Voice recording state machine
hooks/useWhisperTranscription.test.ts Whisper transcription
onboarding/checklistComponents.test.tsx Checklist ProgressBar, animations
onboarding/onboardingFlows.test.ts Onboarding flow logic
onboarding/spotlightTooltips.test.ts Spotlight tooltip rendering
onboarding/handleStepPress.test.ts Step press navigation
onboarding/chatScreenSpotlight.test.ts Chat screen spotlight behavior
onboarding/reactiveSpotlightConditions.test.ts Reactive spotlight conditions
constants/constants.test.ts Constants validation
theme/palettes.test.ts Theme palette definitions
utils/coreMLModelUtils.test.ts Core ML model path utilities
utils/messageContent.test.ts Message content utilities
screens/ModelsScreen/imageDownloadActions.test.ts Image download actions
screens/ModelsScreen/restoreImageDownloads.test.ts Image download restore
screens/ModelsScreen/utils.test.ts ModelsScreen utilities

Integration Tests (__tests__/integration/)

Test File Covers
stores/chatStoreIntegration.test.ts Multi-store interactions
models/activeModelService.test.ts Model load/unload with memory checks
generation/generationFlow.test.ts End-to-end text generation
generation/imageGenerationFlow.test.ts End-to-end image generation
onboarding/spotlightFlowIntegration.test.ts End-to-end spotlight behavior

Contract Tests (__tests__/contracts/)

Tests that verify native module interfaces haven't changed:

Test File Native Module
llama.rn.test.ts llama.rn API shape
whisper.rn.test.ts whisper.rn API shape
whisper.contract.test.ts Whisper service contracts
localDream.contract.test.ts LocalDream module contracts
llamaContext.contract.test.ts LlamaContext lifecycle
coreMLDiffusion.contract.test.ts iOS Core ML parity
iosDownloadManager.contract.test.ts iOS download parity

Component Tests (__tests__/rntl/)

React Native Testing Library tests:

Screens (19 files):

  • ChatScreen.test.tsx, ChatsListScreen.test.tsx, DeviceInfoScreen.test.tsx
  • DownloadManagerScreen.test.tsx, GalleryScreen.test.tsx, HomeScreen.test.tsx
  • LockScreen.test.tsx, ModelDownloadScreen.test.tsx, ModelSettingsScreen.test.tsx
  • ModelsScreen.test.tsx, OnboardingScreen.test.tsx, PassphraseSetupScreen.test.tsx
  • ProjectDetailScreen.test.tsx, ProjectEditScreen.test.tsx, ProjectsScreen.test.tsx
  • SecuritySettingsScreen.test.tsx, SettingsScreen.test.tsx, StorageSettingsScreen.test.tsx
  • VoiceSettingsScreen.test.tsx

Components (17 files):

  • ChatInput.test.tsx, ChatMessage.test.tsx, ChatMessageTools.test.tsx
  • AnimatedEntry.test.tsx, AnimatedListItem.test.tsx, AnimatedPressable.test.tsx
  • AppSheet.test.tsx, Card.test.tsx, CustomAlert.test.tsx, DebugSheet.test.tsx
  • GenerationSettingsModal.test.tsx, MarkdownText.test.tsx
  • ModelCard.test.tsx, ModelSelectorModal.test.tsx
  • ProjectSelectorSheet.test.tsx, ToolPickerSheet.test.tsx, VoiceRecordButton.test.tsx

Onboarding/Spotlight (5 files):

  • ChatScreenSpotlight.test.tsx, ChatsListScreenSpotlight.test.tsx
  • HomeScreenSpotlight.test.tsx, ModelSettingsScreenSpotlight.test.tsx
  • ProjectEditScreenSpotlight.test.tsx

Other:

  • navigation/AppNavigator.test.tsx
  • hooks/useFocusTrigger.test.ts

E2E Tests (Maestro, .maestro/)

Configuration: App ID ai.offgridmobile, 30-second default timeout, screenshots on failure.

E2E Flows by Priority (16 flows across 4 tiers)

P0 — Critical Path (5 flows)

Flow File What It Tests
Model Setup p0/00-setup-model.yaml Model setup utility for other tests
App Launch p0/01-app-launch.yaml Launch → loading disappears → home screen visible
Text Generation p0/02-text-generation.yaml Home → new chat → type message → send → assistant responds
Stop Generation p0/03-stop-generation.yaml Send message → tap stop during streaming → generation halts
Image Generation p0/04-image-generation.yaml Image generation + auto-download

P1 — Important Path (4 flows)

Flow File What It Tests
Document Attachment p1/06a-document-attachment.yaml Attach document to chat
Image Attachment p1/06b-image-attachment.yaml Attach image to chat
Text Gen Full p1/06c-text-generation-full.yaml Full text generation with attachments
Text Gen Retry p1/06d-text-generation-retry.yaml Retry/regenerate text generation

P2 — Model Management (4 flows)

Flow File What It Tests
Model Uninstall p2/05a-model-uninstall.yaml Model deletion
Model Download p2/05b-model-download.yaml Models screen → trigger download → progress → complete
Model Selection p2/05b-model-selection.yaml Model switching between downloaded models
Model Unload p2/05c-model-unload.yaml Model unloading from memory

P3 — Image Model Management (3 flows)

Flow File What It Tests
Image Model Uninstall p3/07a-image-model-uninstall.yaml Image model deletion
Image Model Download p3/07b-image-model-download.yaml Image model download
Image Model Activate p3/07c-image-model-set-active.yaml Image model activation

Key testIDs Required

Area testIDs
Navigation home-screen, chat-screen, models-screen, tab-bar, home-tab, chats-tab, models-tab, settings-tab
Chat chat-input, send-button, stop-button, thinking-indicator, streaming-message, assistant-message
Models model-selector, model-list, model-item-{index}, download-button, download-progress, download-complete
Image image-mode-toggle, image-generation-progress, generated-image, image-message
Conversations conversation-list-button, conversation-list, conversation-item-{index}
Auth lock-screen

Test commands:

npm run test              # Jest unit/integration/contract tests
npm run test:e2e          # All P0 Maestro flows
npm run test:e2e:single   # Single Maestro flow

11. Constants & Configuration

Model Recommendations by RAM

Device RAM Max Model Parameters Recommended Quantization
3–4 GB 1.5B Q4_K_M
4–6 GB 3B Q4_K_M
6–8 GB 4B Q4_K_M
8–12 GB 8B Q4_K_M
12–16 GB 13B Q4_K_M
16+ GB 30B Q4_K_M

Recommended Models (Mar 2026)

Model Parameters Min RAM Type Description
Qwen 3 0.6B 0.6B 3 GB Text Latest Qwen with thinking mode, ultra-light
Gemma 3 1B 1B 3 GB Text Google's tiny model, 128K context
Llama 3.2 1B 1B 4 GB Text Meta's fastest mobile model, 128K context
Gemma 3n E2B 2B 4 GB Text Google's mobile-first with selective activation
Llama 3.2 3B 3B 6 GB Text Best quality-to-size ratio for mobile
SmolLM3 3B 3B 6 GB Text Strong reasoning & 128K context
Phi-4 Mini 3.8B 6 GB Text Math & reasoning specialist
Qwen 3 8B 8B 8 GB Text Thinking + non-thinking modes, 100+ languages
Qwen 3 VL 2B 2B 4 GB Vision Compact vision-language with thinking mode
Gemma 3n E4B 4B 6 GB Vision Vision + audio, built for mobile
Qwen 3 VL 8B 8B 8 GB Vision Vision-language with thinking mode
Qwen 3 Coder A3B 3B 6 GB Code MoE coding model, only 3B active params

Organization Filters

The Models screen supports filtering by model organization:

Key Label
Qwen Qwen
meta-llama Llama
google Google
microsoft Microsoft
mistralai Mistral
deepseek-ai DeepSeek
HuggingFaceTB HuggingFace
nvidia NVIDIA

Defined in MODEL_ORGS constant (src/constants/index.ts).

Quantization Quality Ladder

Quantization Bits/Weight Quality Recommended Notes
Q2_K 2.625 Low No Extreme compression, noticeable quality loss
Q3_K_S 3.4375 Low-Medium No High compression, some quality loss
Q3_K_M 3.4375 Medium No Good compression with acceptable quality
Q4_0 4.0 Medium No Basic 4-bit quantization
Q4_K_S 4.5 Medium-Good Yes Good balance of size and quality
Q4_K_M 4.5 Good Yes Optimal for mobile — best balance
Q5_K_S 5.5 Good-High No Higher quality, larger size
Q5_K_M 5.5 High No Near original quality
Q6_K 6.5 Very High No Minimal quality loss
Q8_0 8.0 Excellent No Best quality, largest size

Theme System

The app supports light and dark modes via a dynamic theme system in src/theme/. Colors and shadows are no longer hardcoded — all screens and components use useTheme() and useThemedStyles() hooks.

Architecture:

  • src/theme/palettes.ts — Light and dark color palettes, shadow definitions, elevation factory
  • src/theme/index.ts — useTheme() hook (returns { colors, shadows, elevation, isDark }), getTheme(mode) for non-hook contexts
  • src/theme/useThemedStyles.ts — useThemedStyles(createStyles) memoized style factory
  • Theme preference stored in appStore.themeMode (persisted via Zustand + AsyncStorage)
  • Toggle in Settings screen (Dark Mode switch)

Pattern (every screen/component):

import { useTheme, useThemedStyles } from '../theme';
import type { ThemeColors, ThemeShadows } from '../theme';

const MyScreen = () => {
  const { colors } = useTheme();
  const styles = useThemedStyles(createStyles);
  return <View style={styles.container}><Icon color={colors.text} /></View>;
};

const createStyles = (colors: ThemeColors, shadows: ThemeShadows) => ({
  container: { backgroundColor: colors.background, ...shadows.small },
});

Theme-independent tokens (TYPOGRAPHY, SPACING, FONTS) remain in src/constants/index.ts.

Color Palettes

Dark Mode (default)

Token Hex Usage
primary #34D399 Emerald accent, active states
background #0A0A0A Main background (pure black)
surface #141414 Cards, elevated elements
text #FFFFFF Primary text
textSecondary #B0B0B0 Secondary text
textMuted #808080 Metadata, placeholders
border #1E1E1E Default borders
error #EF4444 Error states

Light Mode

Token Hex Usage
primary #059669 Emerald accent (darker for contrast)
background #FFFFFF Main background (white)
surface #F5F5F5 Cards, elevated elements
text #0A0A0A Primary text (near black)
textSecondary #525252 Secondary text
textMuted #8A8A8A Metadata, placeholders
border #E5E5E5 Default borders
error #DC2626 Error states

Shadows

Shadows adapt per theme for proper visibility:

  • Light mode: Standard black shadows (opacity 0.15–0.35, radius 6–18)
  • Dark mode: Tight white glow (opacity 0.08–0.12, radius 1–3) for crisp edge definition without blur

12. File System Layout (On-Device)

Documents/
├── local-llm/
│   └── models/                    # Text LLM models (GGUF)
│       ├── qwen2.5-3b-q4_k_m.gguf
│       ├── qwen2.5-3b-q4_k_m-mmproj-f16.gguf   # Vision companion
│       └── ...
│
├── image_models/                  # Stable Diffusion models
│   └── {model-name}/
│       ├── clip_text_encoder.mnn  # (or .bin for QNN)
│       ├── unet.mnn
│       ├── vae_decoder.mnn
│       └── tokenizer.json
│
├── whisper-models/                # Whisper STT models
│   ├── ggml-tiny.en.bin
│   └── ...
│
└── OffgridMobile_Images/               # User-saved generated images
    └── ...

Caches/
└── llm-sessions/                  # LLM session KV cache files
    └── ...

Files/
└── generated_images/              # Generated image PNGs
    ├── {uuid}.png
    └── ...

Cache/
└── preview/                       # Temp preview images during generation
    └── preview.png

Android-specific:

ExternalFilesDir/
└── Downloads/                     # Temp location for background downloads
    └── (moved to Documents/models/ on completion)

assets/
└── runtime_libs/                  # QNN runtime libraries
    ├── libQnnHtp.so
    └── libQnnSystem.so

Appendix: Default System Prompt

You are a helpful AI assistant running locally on the user's device. Your responses should be:
- Accurate and factual - never make up information
- Concise but complete - answer the question fully without unnecessary elaboration
- Helpful and friendly - focus on solving the user's actual need
- Honest about limitations - if you don't know something, say so

If asked about yourself, you can mention you're a local AI assistant that prioritizes user privacy.

Appendix: Default Projects

Project System Prompt Summary
General Assistant Helpful AI assistant (default prompt)
Spanish Learning Spanish language tutor with conversation practice
Code Review Code reviewer providing constructive feedback
Writing Helper Writing assistant for drafting and editing