Platform Overview
B4UGO is a location-based shopping reminder app. Users add items to their shopping list and associate them with stores. Using geofencing, the app reminds users to buy items exactly when they're near the relevant store.
"Never forget to buy essentials again. B4UGO reminds you to shop when you are near the store."
Geofencing alerts when near a store
Only notifies when the user can take action
Auto-groups items by store category
Location processed locally on device
OS-level region monitoring (app sleeps until arrival)
Gemini-powered store categorization
Tech Stack
| Layer | Technology | Version |
|---|---|---|
| Mobile App | React Native + Expo | Expo SDK 54, RN 0.81 |
| Admin Dashboard | Next.js + React + Tailwind CSS v4 | Next.js 16, React 19 |
| Marketing Website | Next.js + React + Tailwind CSS v4 | Next.js 16, React 19 |
| Backend Services | NestJS (TypeScript) | NestJS 11, Node 20 |
| ORM | Prisma | v7.2 |
| Database | PostgreSQL 16 + PostGIS | Cloud SQL |
| Cache | Redis (Upstash Serverless) | via ioredis |
| AI | Google Gemini API | @google/generative-ai |
| Maps | Google Maps Services JS + Leaflet | - |
| Monitoring | Sentry | @sentry/nestjs, @sentry/react-native |
| Language | TypeScript (100%) | v5.x |
Voice Assistant and Deep Linking
Frictionless Operation & Seamless Sharing: Empower users to stay hands-free and highly productive. By bridging the gap between natural language and core app capabilities, B4UGO allows users to instantly capture items on the go, safely navigate lists while driving, and effortlessly share specific store contexts with friends and family—all without tapping a single button.
Natively integrated with iOS 16+ using Swift AppIntents. Features 6 distinct shortcuts including AddItem, AddStore, AdjustProximity (up/down), and AdjustMaxResults (up/down). Changes sync immediately across the app via native React Native event listeners.
Custom Alexa skill ecosystem mapped to the AddItem intent, allowing users to populate their smart shopping lists directly from smart home devices before they even step out the door.
Custom URL schemes (b4ugo://) integrated with React Navigation to programmatically transition users from external intents to state-aware screens. Supported deep links include aggregated store views (/shop), dynamic location contexts (/shop/:storeId), and frictionless creation flows (/add-item, /add-store), facilitating seamless cross-user sharing.
AI & LLM Integration
Next-Gen Intelligence: B4UGO leverages advanced generative AI to seamlessly map the real world to user intent. By integrating proprietary and generalized LLMs, the platform transforms manual shopping planning into an automated, highly accurate process.
TaxonomyAiService
Proprietary LLM pipeline that instantly categorizes generic items into accurate store taxonomies (e.g., mapping "Aspirin" to "Pharmacy"), enabling high-precision GPS geofencing triggers.
RecipeAiService
An advanced parser that processes unstructured text from user-pasted recipes, intelligently extracting individual ingredients and mapping them automatically into the user's shopping list.
TranslationAiService
Universal semantic translation models ensure lists written in any language are perfectly understood by the underlying item-to-store mapping engines for global usability.
IntelligenceService
Deep telemetry analysis of scan pipeline events and driving patterns to derive smart insights, optimizing battery consumption and minimizing background noise through predictive gating.
Architecture
Monorepo Structure
B4UGO/
├── apps/
│ ├── auth-service/ # NestJS - Authentication & Users
│ ├── items-service/ # NestJS - Items, Stores, Maps, Barcodes
│ ├── scan-service/ # NestJS - Store Scanning & AI Categorization
│ ├── admin-web/ # Next.js - Admin Dashboard
│ ├── website/ # Next.js - Public Marketing Website
│ └── mobile/ # React Native / Expo - Mobile App
├── deploy/cloudrun/ # Cloud Run service YAML definitions
├── .github/workflows/ # CI/CD pipeline definitions
├── firebase.json # Firebase Hosting routing config
└── tests/load/ # k6 load testing scriptsMicroservices Architecture
React Native / Expo
Next.js
Next.js
PostgreSQL 16 + PostGIS
b4ugo-uploads
Architecture Diagrams
Service Breakdown
🔐 auth-service
User identity, OAuth social logins, token lifecycle, push notifications, analytics events.
📦 items-service
Core business logic - shopping items, stores, maps, chains, barcodes, feedback, file uploads.
🔍 scan-service
AI-powered store scanning/categorization, taxonomy management, analytics dashboards.
Database Design
Schema Architecture
Single PostgreSQL 16 instance with multiple schemas - each service connects via Prisma with its own isolated schema (bounded context):
| Prisma Config | DB Schema | Service |
|---|---|---|
auth-service/prisma/schema.prisma |
auth |
auth-service |
items-service/prisma/schema.prisma |
items + public |
items-service |
scan-service/prisma/schema.prisma |
scan |
scan-service |
Infrastructure
GCP Deployment Architecture
PostgreSQL 16 + PostGIS
DevOps & CI/CD
Pipeline Overview
- Backend: Lint & Test (matrix: auth, items, scan)
- Web: Lint & Build (matrix: admin-web, website)
- Mobile: Jest Tests
- Docker Build Smoke Test (all 5 services)
- Detect Changed Services (
git diff HEAD~1) - GCP Auth via WIF (Keyless OIDC)
- Cloud Build → Artifact Registry
gcloud run services replace- Health Check (curl all endpoints)
- EAS Build (iOS / Android)
- TestFlight Submit (optional)
Observability & Quality
Admin Dashboard — System Health
A custom-built Next.js admin portal (admin.buyb4ugo.com)
provides comprehensive real-time observability across the entire platform. Key dashboards:
Real-time liveness checks across 8 endpoints (Auth, Items, Scan, Admin, Website, Redis Cache, PostGIS, Firebase) with 30-second auto-refresh. Tracks per-service response time, status, aggregate uptime %, and average response.
User engagement metrics — DAU, WAU, MAU, and stickiness ratios. Event analytics with daily trends
(7d/30d/90d) tracking scan_triggered, app_open, item_added,
item_completed, settings_changed, and screen_view. Growth &
activity panels showing scan volume, items created, completion rate, and Redis cache efficiency.
Per-user trace-level scan execution logging. Each log entry records scan type (Auto / Background), outcome (No Stores / Found / Notified), speed, driving tier, and GPS mode. Filterable by type and outcome with pagination and CSV export for offline analysis.
GitHub Actions pipeline status (CI + Deploy), EAS mobile build history, test count tracking (419 tests / 32 suites), Sentry bug integrations, and database backup management to GCS. All surfaced in-app — no need to leave the admin portal.
Error Tracking & Monitoring
| Tool | Scope | Details |
|---|---|---|
| Sentry | Backend (×3) + Mobile | @sentry/nestjs on auth, items, scan services. @sentry/react-native on
mobile app. Source maps uploaded via CI. Error counts surfaced in DevOps dashboard. |
| Cloud Run Health Probes | All 5 Cloud Run services | Liveness probes on /health endpoints. Auto-restart on failure. Post-deploy validation
in CI pipeline via curl. |
| Admin API Health Monitor | 8 service endpoints | Custom dashboard with 30s polling, response time tracking, aggregate session uptime %, and Fast/Moderate/Slow latency classification. |
Testing Strategy
Every push to main triggers a full CI matrix. Tests gate all merges and
deployments.
| App | Framework | Suites | Tests |
|---|---|---|---|
| Mobile | Jest | 5 | 126 |
| Admin Web | Jest | 16 | 118 |
| scan-service | Jest | 6 | 79 |
| items-service | Jest | 3 | 63 |
| auth-service | Jest | 2 | 33 |
| Total | 32 | 419 |
Load Testing
k6 load testing scripts live in tests/load/ alongside the
monorepo. Ramp-up scenarios exercise health, auth, items, stores, and scan endpoints concurrently against
the production Cloud Run cluster.
Key Architectural Decisions
Multi-schema Single DB
Each service has its own Prisma schema (auth, items, scan) as
bounded contexts, sharing one PostgreSQL instance for cost efficiency.
Firebase Hosting as Ingress
Global CDN + SSL + path routing - needed because me-west1 doesn't support direct Cloud Run
domain mappings.
Shared JWT Secret
All backend services verify tokens independently without inter-service calls.
Upstash over Memorystore
Serverless Redis for cost efficiency and TLS-native from Cloud Run.
Selective Deployment
git diff-based change detection deploys only affected services.
Monorepo
All services, web apps, and mobile app in one repo with scoped linting and selective CI/CD.