Getting Started
This guide walks you through getting the Certi-Lock® mobile app running locally in under 10 minutes. For detailed environment configuration and build profiles, see the Development Setup page.
Prerequisites
Before starting, ensure you have the following installed:
- Node.js 20+ and npm 10+
- EAS CLI —
npm install -g eas-cli - Xcode 15+ (macOS only, for iOS simulator)
- Android Studio with an emulator configured (for Android)
- Watchman (recommended on macOS)
Quick Start
1. Clone and Install
git clone <repo-url> scottsdale-mint-mobile-app
cd scottsdale-mint-mobile-app
npm install
2. Configure Environment
Create a .env file in the project root:
# Algolia Product Search
EXPO_PUBLIC_ALGOLIA_API_KEY=<search-only-api-key>
EXPO_PUBLIC_ALGOLIA_APP_ID=<application-id>
EXPO_PUBLIC_ALGOLIA_INDEX_NAME=<index-name>
# Certi-Lock Image API
EXPO_PUBLIC_IMAGE_API_KEY=<api-key>
EXPO_PUBLIC_IMAGE_API_URL=<base-url>
# WordPress REST API (Banners + Error Logging)
EXPO_PUBLIC_WP_API_KEY=<api-key>
EXPO_PUBLIC_WP_API_URL=<base-url>
Contact the project lead for the actual API key values. Never commit .env to version control.
3. Log In to EAS
eas login
Use the Rhino Group Expo account credentials.
4. Start the Development Server
npm start
5. Run on a Device or Simulator
| Platform | Command | Notes |
|---|---|---|
| iOS Simulator | npm run ios | Requires macOS + Xcode |
| Android Emulator | npm run android | Requires running emulator |
| Physical Device | Scan QR code | Requires dev client build |
The custom native Vision Camera QR module requires a development build — Expo Go is not supported. Run npx expo run:ios or npx expo run:android for the initial native build.
Project Structure
scottsdale-mint-mobile-app/
├── app/ # Expo Router screens (file-based routing)
│ ├── _layout.tsx # Root layout with providers
│ ├── index.tsx # Home screen (banners + scan button)
│ ├── scan.tsx # Camera scanning screen
│ ├── items/ # Item list and detail screens
│ └── +not-found.tsx # 404 fallback
├── components/ # Reusable UI components
├── db/ # Drizzle ORM schema and migrations
│ ├── schema.ts # SQLite table definitions
│ └── index.ts # Database client initialization
├── drizzle/ # Generated SQL migration files
├── hooks/ # Custom React hooks (queries, mutations)
├── lib/ # Utility functions and API clients
├── assets/ # Images, fonts, static files
├── modules/ # Native modules (visionCameraQr)
├── app.json # Expo app configuration
├── eas.json # EAS build profiles
├── tailwind.config.js # NativeWind/Tailwind configuration
└── metro.config.js # Metro bundler config (Sentry integration)
Core Workflow
The typical development cycle follows this pattern:
- Scan — User scans a QR code or barcode via the camera screen
- Lookup — App queries Algolia for the matching product by serial number
- Fetch Image — Retrieves the sealed item image from the Certi-Lock Image API
- Store Locally — Saves product data to SQLite and image to the filesystem
- Display — Shows the verified item with product details and sealed image
All data is cached locally after the first scan, enabling full offline access.
Key Commands Reference
| Command | Purpose |
|---|---|
npm start | Start Expo dev server |
npm run ios | Run on iOS simulator |
npm run android | Run on Android emulator |
npm test | Run Jest test suite |
npm run lint | Run ESLint |
npm run check-types | TypeScript type checking |
npx expo start --clear | Clear Metro cache and restart |
npx drizzle-kit generate | Generate DB migration after schema changes |
npx drizzle-kit studio | Open Drizzle Studio for DB inspection |
Common Issues
"Native module not found" Errors
The app uses a custom native frame processor module (visionCameraQr) that is not available in Expo Go. You must create a development build:
npx expo run:ios # iOS
npx expo run:android # Android
Environment Variables Not Loading
- Ensure all variables are prefixed with
EXPO_PUBLIC_ - Restart the dev server after editing
.env - Variables are embedded at build time — production builds require a fresh EAS build
Database Issues
Migrations apply automatically on app startup. If the schema is out of sync:
# Regenerate migrations
npx drizzle-kit generate
# Restart the app to apply
npm start --clear
Next Steps
Once the app is running locally, explore the detailed documentation:
- Architecture — Expo Router navigation, provider hierarchy, and data flow
- API Integrations — Algolia, Image API, WordPress, and Sentry setup
- Database — Drizzle ORM schema, queries, and image storage
- Camera & Scanning — Vision Camera setup and native QR module
- UI & Styling — NativeWind configuration, fonts, and screen layouts
- Development Setup — Full environment details, EAS profiles, testing, and deployment