Part Finder - Couchbase Lite CKO Demo

Snap a photo. Find your part. A React Native Expo application demonstrating Couchbase Lite mobile database capabilities with visual product search powered by CLIP embeddings.

Overview

This demo app showcases a visual product search workflow:

1. Capture - Take a photo of a part or select from gallery
2. Embed - Generate a 512-dimensional vector embedding using CLIP (on-device or via API)
3. Search - Query Couchbase Lite using vector similarity search
4. Match - Display similar products sorted by cosine distance

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Camera/Image  │────▶│  CLIP Model      │────▶│  Vector Query   │
│     Input       │     │  (512-dim)       │     │  Couchbase Lite │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                                                         │
                                                         ▼
                                                 ┌─────────────────┐
                                                 │ Similar Products│
                                                 │   (Top N)       │
                                                 └─────────────────┘

Features

• 📱 Mobile Database - Couchbase Lite with offline-first architecture
• 🔄 Sync Gateway Integration - Push/pull replication with Capella
• 🔍 Visual Search - AI-powered image similarity search
• 📸 Camera Integration - Capture or select images for search
• 🧠 On-Device ML - MobileCLIP inference via TensorFlow Lite
• 📦 Product Catalog - Browse synced products and vectors
• 💾 My Items - Save captured items with image blobs

Screenshots

Home	Products	Visual Search
Dashboard with collection counts	Browse synced products	Camera → embedding → results

Tech Stack

Component	Technology	Version
Framework	React Native (Expo)	0.76.3 / SDK 52
Language	TypeScript	5.3.3
Navigation	Expo Router	4.0.0
Database	Couchbase Lite (cbl-reactnative)	0.6.3
ML Inference	TensorFlow Lite (react-native-fast-tflite)	2.0.0
Image Picker	Expo Image Picker	16.0.6

Project Structure

cb_cko_demo/
├── cb_cko_demo_app/           # Main Expo application
│   ├── app/                   # Expo Router pages (file-based routing)
│   │   ├── _layout.tsx        # Root layout with navigation
│   │   ├── index.tsx          # Home screen (dashboard)
│   │   ├── products.tsx       # Products collection browser
│   │   ├── vectors.tsx        # Vectors collection browser
│   │   ├── myitems.tsx        # User-captured items
│   │   ├── search.tsx         # Visual search screen
│   │   └── settings.tsx       # Sync & database settings
│   ├── providers/
│   │   ├── DatabaseProvider.tsx  # React context for DB access
│   │   └── SettingsProvider.tsx  # App settings context
│   ├── services/
│   │   ├── database.service.ts   # Couchbase Lite operations
│   │   └── local-embedding.service.ts  # On-device CLIP inference
│   ├── assets/                # Icons and images
│   ├── ios/                   # iOS native project
│   ├── android/               # Android native project
│   ├── app.json               # Expo configuration
│   └── package.json           # Dependencies
├── patches/                   # Patch files for dependencies
├── mobileclip-s1.tflite       # MobileCLIP TensorFlow Lite model
├── AGENTS.md                  # AI assistant instructions
├── RUN.md                     # Visual search implementation details
└── README.md                  # This file

Database Schema

Property	Value
Database	db
Scope	catalog

Collections

Collection	Description	Key Fields
products	Product catalog data	sku, name, type, model, image_url
vectors	512-dim embeddings	sku, embedding (float array)
myItems	User-captured items	owner, image (blob), embedding

Getting Started

Prerequisites

• Node.js 18+
• Xcode 15+ (for iOS)
• Android Studio (for Android)
• CocoaPods (for iOS)

---

⚠️ REQUIRED FOR ONLINE EMBEDDING MODE

You MUST have these services running to use the ONLINE (API) embedding mode:

Service	Repository
Vector Embedding API	https://github.com/anujsahni/vector-embedding
Vector Search API	https://github.com/anujsahni/vector-search

Clone and run these services before enabling ONLINE mode in Settings.

---

Installation

# Clone the repository
git clone https://github.com/your-username/cb_cko_demo.git
cd cb_cko_demo/cb_cko_demo_app

# Install dependencies
npm install

# Generate native projects
npx expo prebuild --clean

# Install iOS pods
cd ios && pod install && cd ..

Running the App

# Start Metro bundler
npm start

# Run on iOS simulator
npm run ios

# Run on Android emulator
npm run android

⚠️ Note: The cbl-reactnative plugin requires native modules and cannot run in Expo Go. Use development builds (expo run:ios or expo run:android).

Configuration

Sync Gateway

The app is pre-configured to sync with a Capella deployment:

Setting	Value
Endpoint	wss://vexlc6f-ekguwo9l.apps.cloud.couchbase.com:4984/cko
Auth	Basic (username/password)
Mode	Push and pull replication

Configure credentials in the Settings screen or update defaults in services/database.service.ts.

Embedding APIs

The app supports multiple embedding generation modes:

Mode	Description	Latency
Local (On-Device)	MobileCLIP via TensorFlow Lite	~50-100ms
API (Remote)	Server-side CLIP embedding	~200-500ms

Toggle between modes in the Settings screen.

Key Features Explained

Visual Search Flow

1. Image Capture: Select or capture an image via expo-image-picker
2. Embedding Generation:
   • On-device: MobileCLIP model generates 512-dim vector
   • Remote: POST to embedding API endpoint
3. Vector Query: Query catalog.vectors using APPROX_VECTOR_DISTANCE()
4. Result Display: Show matching products with similarity scores

Vector Index Configuration

const vectorIndex = new VectorIndex({
  expression: 'embedding',
  dimensions: 512,
  centroids: 1,
  metric: DistanceMetric.Cosine,
  encoding: { type: 'none' },
  isLazy: false,
});

SQL++ Vector Search Query

SELECT META().id AS id, *, 
       APPROX_VECTOR_DISTANCE(embedding, $vector, "COSINE") AS distance
FROM catalog.vectors
ORDER BY APPROX_VECTOR_DISTANCE(embedding, $vector, "COSINE")
LIMIT 10

Development

Available Scripts

Script	Description
npm start	Start Metro bundler
npm run ios	Build and run on iOS
npm run android	Build and run on Android
npm run web	Start web version (limited functionality)

Adding a New Screen

1. Create a new file in app/ directory (e.g., app/newscreen.tsx)
2. Export a default React component
3. Expo Router automatically creates the route

Modifying Database Operations

All Couchbase Lite operations are centralized in services/database.service.ts:

• initializeDatabase() - Open DB and create collections
• runOneTimeSync() - Execute push/pull replication
• searchSimilarVectors() - Vector similarity search
• getDocumentById() - Fetch single document

Project Phases

Phase	Status	Description
Crawl	✅ Complete	Basic setup, database init, sync button
Walk	✅ Complete	Collection viewers, settings page, improved UX
Run	🚧 In Progress	Visual product search (camera → vector → results)

See RUN.md for detailed Run phase implementation.

Troubleshooting

"Vector index not trained"

The vector index requires at least centroids × 25 documents with embeddings. With 1 centroid, you need 25+ vectors in the collection.

Build fails on iOS

# Clean and rebuild
cd ios && pod deintegrate && pod install && cd ..
npx expo prebuild --clean
npm run ios

Sync Gateway connection issues

• Verify WebSocket URL includes wss:// protocol
• Check username/password credentials
• Ensure network connectivity to Capella endpoint

cbl-reactnative not found

The plugin links to a local path. Ensure cbl-reactnative is available at ../../cbl-reactnative or update package.json:

"cbl-reactnative": "file:../../cbl-reactnative"

Resources

• Couchbase Lite React Native SDK
• Couchbase Lite Vector Search Guide
• Expo Router Documentation
• MobileCLIP on TensorFlow Hub
• react-native-fast-tflite

License

This project is for demonstration purposes.

---

Built with ❤️ using Couchbase Lite and React Native