falah-mobile/halal-monitor-brief.md

# Halal Monitor — Strategic Brief

## Vision
Rebrand the existing World Monitor project as **Halal Monitor** — a premium feature of FalahMobile. A global map-based dashboard for the Muslim ummah to find halal restaurants, mosques, and prayer spaces anywhere in the world.

## Core Features

### Phase 1 — MVP (Map + Data)
| Feature | Description | Data Source | API Cost |
|---|---|---|---|
| **Mosques & Prayer Places** | Map of nearby mosques worldwide with name, address, prayer times | Overpass API (OpenStreetMap) | **Free** |
| **Halal Restaurants** | Halal-certified/muslim-owned restaurants in major cities | Google Places API + OSM tags | Google: ~$7/1K calls (free $200/mo credit) |
| **Search by City** | Search bar + autocomplete for city/mosque/restaurant | Nominatim (OSM geocoder) | **Free** |
| **Current Location** | "Near me" — geolocate user and show nearby places | Browser Geolocation API | **Free** |

### Phase 2 — Premium Enhancements (FalahMobile Premium)
| Feature | Description |
|---|---|
| **Halal Certifications** | Verified halal certification badges per restaurant |
| **User Reviews & Ratings** | Community-driven halal rating system |
| **Bookmarks & Favorites** | Save places, get alerts when new verified places added |
| **Trip Planner** | Plan routes with halal restaurants + prayer stops along the way |
| **Crowd-Sourced Updates** | Premium users can submit new halal places for verification |

### Phase 3 — Platform
| Feature | Description |
|---|---|
| **Weekly Digest** | New halal places in your city, emailed/notified |
| **Monthly Trends** | Most-reviewed, top-rated, newly certified |
| **Ambassador Program** | Community mods who verify new submissions |

## Architecture

### Integration into FalahMobile

```
FalahMobile (Next.js 16 App Router)
├── /halal-monitor          → Page (gated: isPremium required)
├── /api/halal/places       → Nearby places API (Overpass + Google)
├── /api/halal/bookmarks    → User bookmarks CRUD
├── /api/halal/usage        → Track API usage/quotas (for free tier)
└── lib/halal-monitor.ts    → Shared helpers (geocoding, map utils)
```

### Tech Choices

| Concern | Choice | Why |
|---|---|---|
| **Map renderer** | **Leaflet** (react-leaflet) | Free, no API key, light (~40KB gzip), works with OSM tiles |
| **Map tiles** | OpenStreetMap tile layer | Free tier, no API key, or optional MapTiler ($) for styled maps |
| **Mosque data** | **Overpass API** | OpenStreetMap query language, query `amenity=place_of_worship + religion=muslim` |
| **Halal restaurant data** | OSM tags (`diet:halal=yes`) + Google Places fallback | OSM free but less complete; Google fills gaps |
| **Geocoding** | Nominatim (OSM) | Free, 1 req/sec limit — fine for single-user |
| **Premium gating** | `user.isPremium` in AuthContext | Already exists in Prisma schema |
| **Map markers clustering** | `leaflet.markercluster` | Handles 1000+ markers smoothly |
| **Styling** | TailwindCSS dark theme (existing) | Consistent with FalahMobile design |

### Data Flow

```
User opens /halal-monitor
  → Auth check: user.isPremium? No → Show upgrade CTA
  → Yes → Browser geolocates (or city search)
  → Fetch /api/halal/places?lat=X&lng=Y&radius=5000
    → Server queries Overpass API for mosques + halal restaurants
    → Caches results in SQLite (expire after 24h)
    → Returns GeoJSON
  → Render map with Leaflet + clustered markers
  → Two marker layers: mosques (green) / restaurants (blue)
```

## Premium Gating Strategy

### What's Free vs Premium

| Feature | Free Users | Premium Users |
|---|---|---|
| View map | ✅ | ✅ |
| Search cities | ✅ | ✅ |
| See mosques | ✅ | ✅ |
| See halal restaurants | ❌ | ✅ |
| Bookmarks | ❌ (view-only) | ✅ (save & organize) |
| API calls/day | 20 | Unlimited |
| Crowd-sourced edits | ❌ | ✅ |
| Trip planner | ❌ | ✅ |

### Upgrade CTA Placement
- **Souq page** — small "Upgrade to Premium" badge in sidebar
- **Halal Monitor page** — if not premium, show map with greyed-out restaurant layer + upgrade prompt
- **Navbar** — crown icon next to user name for premium users; "✨ Upgrade" for free users

## Monetization
- **Premium subscription** — unlocks full Halal Monitor + other premium features
- **Price** — TBD (existing isPremium/isPro fields support multiple tiers)
- **Listing fee discount** — premium users pay 5% platform fee instead of 10%

## Implementation Phases

### Phase 1 (build in this session)
1. ✅ Create this strategic brief
2. **Halal Monitor page** — `/halal-monitor` with Leaflet map, premium gate
3. **API route** — `/api/halal/places` querying Overpass API for mosques
4. **Navbar update** — add Halal Monitor link (with premium badge)
5. **Premium gating** — `isPremium` check on page access
6. **Deploy** — rebuild image, push to Synology, update Dockge stack
7. **QA** — test map rendering, mosque search, premium gate

### Phase 2 (next session)
1. Halal restaurants layer (Google Places API)
2. Bookmarks CRUD
3. Crowd-sourced submission form
4. Trip planner

### Phase 3 (future)
1. Community review system
2. Weekly digests
3. Ambassador verification program

## Data & Privacy
- No user location data stored server-side — geolocation is ephemeral (browser)
- Bookmark data stored in SQLite (existing FalahMobile DB)
- Overpass API calls are anonymous
- Rate limiting: 60 req/min per user on free tier (enforced server-side)

## Key Risks & Mitigations
| Risk | Mitigation |
|---|---|
| OSM data incomplete for halal restaurants | Add Google Places API fallback + crowd-sourced submissions |
| Overpass API rate limits (1 req/sec) | Server-side caching (24h TTL), batch queries |
| Free users burning API quota | Hard cap at 20 req/day for free, tracked via usage table |
| iCloud datalock on World Monitor source | Build fresh from OSM + Google APIs — don't depend on old code |
| Premium adoption low | Cross-sell on Souq page, make Halal Monitor a visible premium showcase |

---

*Last updated: June 8, 2026*
*Status: Strategic Brief — Ready for Phase 1 implementation*