off grid mobile - Moses Yebei

Abstract

The Swiss Army Knife of Offline AI. Chat, Speak, and Generate Images - Privacy First, Zero Internet. Download an LLM and use it on your mobile device. No data ever leaves your phone. Supports text-to-text, vision, text-to-image

The Problem

Mobile users who need AI‑driven chat, image creation, vision, or transcription must trust cloud services that ship data off‑device. For privacy‑sensitive or bandwidth‑constrained scenarios this is unacceptable, yet building a fully offline stack on Android/iOS is non‑trivial.

What This Does

off-grid-mobile bundles on‑device LLMs, Stable Diffusion, Whisper, and a small vision stack into a single React‑Native app. The core entry point is App.tsx, which bootstraps the UI and calls initializeApp (also in App.tsx). Model binaries live under android/app/src/main/assets/ (e.g., ggml-hexagon/*.so, qnnlibs/*.so) and are managed by src/services/modelManager.ts. UI screens such as src/screens/ChatScreen.tsx and src/screens/ModelsScreen.tsx render the chat UI and model download UI respectively. Shared constants, theme definitions, and TypeScript types reside in hub modules src/constants/index.ts, src/theme/index.ts, and src/types/index.ts.

How It Is Wired

Execution starts at App.tsx → initializeApp (line 57). initializeApp creates the app‑wide stores, then calls initialize in src/services/modelManager.ts, which ensures a model‑cache directory via RNFS.mkdir and triggers any pending downloads.

Key call‑graph hotspots:

Function	Callers	Reach
`showAlert`	55 places (e.g., `CustomAlert.tsx`)	UI‑wide notification
`getState`	39 places (e.g., `ChatScreen.tsx`, `ModelCard.tsx`)	Central store access
`useTheme` / `useThemedStyles`	39 / 31 places	Theme propagation
`isModelLoaded`	21 places (model selector, generation flow)	Guard before inference
`generateImage`	10+ places (image‑gen UI) → `updateState`, `isCurrentlyGenerating`	Image pipeline

File‑level responsibilities (largest blast radius first):

src/theme/index.ts – defines getTheme, useTheme; imported by 35 modules (hub).
src/constants/index.ts – 36 dependents; holds static config used throughout.
src/types/index.ts – type definitions consumed by 35 modules.
src/services/modelManager.ts – 39 functions, handles filesystem I/O for model download/unpack.
src/services/llm.ts – 33 functions, prepares LLM session directories and computes optimal thread/batch sizes.

Import cycles exist among src/theme/index.ts, src/stores/index.ts, and src/services/index.ts (11 modules in total). This means a change in any of these files can trigger recompilation of the entire dependency graph and risks runtime circular‑reference errors.

Deep nesting (max depth 9) appears in src/services/activeModelService.ts, src/screens/HomeScreen.tsx, and the native Kotlin download manager, making the control flow hard to follow.

Oversized files (src/services/llm.ts, src/services/modelManager.ts, src/screens/ChatScreen.tsx) exceed 700 lines, concentrating many responsibilities and increasing change impact.

Duplicated 6‑line test blocks are scattered across contract and unit tests, indicating DRY violations.

How To Use It

# Clone the exact repo
git clone https://github.com/moses-y/off-grid-mobile
cd off-grid-mobile

# Install JS dependencies
npm install

# Android build
cd android && ./gradlew clean && cd ..
npm run android   # launches Metro and builds the APK

# iOS build (macOS only)
cd ios && pod install && cd ..
npm run ios       # launches Metro and builds the app via Xcode

The README’s “Install” section confirms these commands. No additional environment variables are required; model files are downloaded at runtime by modelManager.ts.

Real‑World Use

A field‑worker installs the APK on a rugged Android phone, opens the app, and selects a GGUF model in Models → Download. The UI calls downloadModel → modelManager.ts → native DownloadManagerModule.kt, which writes to the app’s private storage. Once complete, the worker launches Chat, speaks a query, and useWhisperTranscription (via whisper native module) returns text without any network traffic. The same flow can be switched to image generation, invoking imageGenerator.ts → native StableDiffusion libs.

Code Health & Issues

Critical – Private key committed (android/app/debug.keystore).
High – GitHub Actions not pinned to commit SHAs (.github/workflows/*).
High – CI pushes directly to default branch (release-ios.yml).
Medium – No least‑privilege GITHUB_TOKEN permissions (ci.yml).
Medium – No Dependabot/Renovate configured.
Medium – No dependency‑vulnerability scan in CI.
Medium – No pre‑commit secret‑leak gate.
Medium – Checkout step keeps token (persist-credentials missing).
Low – No job timeout limits in CI workflows.
High – Import cycles among theme, stores, and services.
High – Hub modules (constants, theme, types) have very high fan‑in.
High – Deep nesting (max depth 9) in key service files.
High – Oversized service and screen files (> 700 LOC).
High – Repeated test code blocks across contracts and unit tests.

The Bottom Line

off-grid-mobile delivers a functional, fully offline AI suite for mobile, with a solid React‑Native foundation and native model integration. The codebase works but suffers from architectural smells—import cycles, large hub modules, deep nesting, and oversized files—that will increase maintenance cost. Security hygiene needs immediate attention (private key, CI permissions). It is suitable for teams ready to invest in refactoring and hardening before production deployment.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

366 files

TypeScript85
TSX72
YAML24
Markdown14
Kotlin9
JSON8

ReactExpressRailsTransformers

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["src<br/>78 modules"] g1["__tests__<br/>77 modules"] g2["(root)<br/>8 modules"] g1 -->|124| g0 g2 -->|6| g0 g1 -->|1| g2

Module dependencies

The 10 most depended-upon modules of 163, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_constants_index["index"] n1_src_theme_index["index"] n2_src_types_index["index"] n3_src_stores_index["index"] n4_src_services_index["index"] n5_src_components_CustomAlert["CustomAlert"] n6___tests___utils_factories["factories"] n7___tests___utils_testHelpers["testHelpers"] n8_src_components_index["index"] n9_src_stores_appStore["appStore"] n6___tests___utils_factories --> n2_src_types_index n7___tests___utils_testHelpers --> n9_src_stores_appStore n7___tests___utils_testHelpers --> n6___tests___utils_factories n5_src_components_CustomAlert --> n1_src_theme_index n5_src_components_CustomAlert --> n0_src_constants_index n8_src_components_index --> n5_src_components_CustomAlert n9_src_stores_appStore --> n2_src_types_index n3_src_stores_index --> n9_src_stores_appStore n1_src_theme_index --> n9_src_stores_appStore classDef cyc stroke:#ef4444,stroke-width:2px; class n1_src_theme_index,n3_src_stores_index,n4_src_services_index cyc;

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

critical1

high2

medium5

low1

Rotate and purge the committed private keycritical

android/app/debug.keystore

A published signing or TLS private key cannot be unpublished, and it lets anyone impersonate the service or decrypt captured traffic.

Fix: Reissue the key pair, then purge the blob from history; deleting it in a later commit is not enough.

Pin third-party GitHub Actions to a commit SHAhigh2 occurrences

.github/workflows

ruby/setup-ruby@v1, android-actions/setup-android@v3

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Open a pull request instead of pushing to the default branchhigh

.github/workflows/release-ios.yml

git push

Automated commits land on the branch that deploys, with no test having run against the result.

Fix: Push to a bot branch and open a pull request, or restrict the push to a tag ref.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/ci.yml

1 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

2 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Add a pre-commit secret gatemedium

a secret-shaped file is tracked and no repo-level gate is visible

Without a gate the same class of leak recurs on the next commit, so a leak finding is the symptom and this is the cause.

Fix: Add a pre-commit hook scanning staged content, and enable push protection.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/ci.yml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.