Open World Map | Technical Overview

Architecture Overview

Client Layer

PWA (Mobile + Desktop)

Web Browser

Home Screen Install

Frontend

Next.js 14

React 18

Tailwind CSS

shadcn/ui

Backend

Supabase

Auth

Realtime

Storage

Edge Functions

Data Layer

PostgreSQL + PostGIS

Spatial Queries

Row Level Security

External

Mapbox

Firebase FCM

Firebase Analytics

Twilio

PWA-First Approach: Progressive Web App delivers native-like experience across iOS, Android, and desktop from a single codebase. Enables offline support, push notifications, and home screen installation without app store deployment.

Stack Summary

Layer	Technology	Why
Frontend	React + Next.js 14	Industry standard, SSR, great DX
Styling	Tailwind CSS + shadcn/ui	Rapid development, consistency
State	Zustand + React Query	Lightweight, server state caching
Database	PostgreSQL (Supabase)	PostGIS, real-time, auth included
ORM	Prisma	Type-safe, great DX
Auth	Firebase Auth	Phone OTP, OAuth, Google integration
Real-time	Supabase Realtime	WebSocket, presence
Maps	Mapbox GL JS	Best customization, clustering
Storage	Firebase Storage	CDN, auth integration
Hosting	Firebase Hosting	Global CDN, unified billing
Push	Firebase FCM	Free, unlimited
SMS	Twilio	Reliable, global
Analytics	Firebase Analytics	Free, integrated
Monitoring	Cloud Error Reporting	Google integrated

Core Stack Components

N

Next.js 14

React Framework

Full-stack React framework with server-side rendering, API routes, and optimized performance out of the box.

App Router Server Components API Routes Image Optimization

Version

14.x (App Router)

Rendering

Hybrid SSR/SSG/CSR

TypeScript

Full support

PWA Plugin

next-pwa

Alternatives Considered

Remix Nuxt SvelteKit

S

Supabase

Backend as a Service

Open-source Firebase alternative providing PostgreSQL database, authentication, realtime subscriptions, and storage.

PostgreSQL Auth Realtime Storage Edge Functions

Database

PostgreSQL 15+

Spatial

PostGIS extension

Auth Providers

Email, Phone, OAuth

Security

Row Level Security

Alternatives Considered

Firebase AWS Amplify PlanetScale

M

Mapbox + MapLibre

Mapping Platform

Hybrid mapping approach using Mapbox for premium features and MapLibre GL JS for cost-effective base maps.

Vector Tiles Custom Styling Clustering Offline Maps

Base Maps

MapLibre GL JS

Tile Source

OpenStreetMap

Premium

Mapbox (50K free)

Geofencing

Radar.io

Alternatives Considered

Google Maps HERE Maps Leaflet

T

Tailwind CSS + shadcn/ui

Styling System

Utility-first CSS framework paired with accessible, customizable component library for consistent UI.

Utility Classes Radix Primitives Dark Mode Accessible

Tailwind

v3.x

Components

shadcn/ui

Icons

Lucide React

Animations

Framer Motion

Alternatives Considered

Chakra UI MUI Mantine

Z

Zustand + React Query

State Management

Lightweight client state with Zustand, server state caching with TanStack Query for optimal data handling.

Client State Server Cache Optimistic Updates Background Sync

Client State

Zustand

Server State

TanStack Query v5

Bundle Impact

~3KB + ~12KB

SSR Support

Hydration ready

Alternatives Considered

Redux Toolkit Jotai SWR

A

Firebase Auth

Authentication

Google's battle-tested identity platform with phone OTP, OAuth, and seamless integration with Firebase services.

Email/Password Phone OTP Google OAuth Apple Sign-In

Primary

Email + Password

Secondary

Phone OTP (Kenya)

Tokens

Firebase ID tokens (JWT)

Free Tier

10K OTP/month

Alternatives Considered

Supabase Auth Clerk Auth0

R

Supabase Realtime

Live Updates

WebSocket-based realtime subscriptions for live location sharing, instant notifications, and collaborative features.

Presence Broadcast DB Changes Channels

Protocol

WebSocket

Presence

"Who's Around"

Broadcast

SOS alerts

Channels

City-based rooms

Alternatives Considered

Pusher Ably Socket.io

F

Firebase Hosting

Deployment Platform

Global CDN deployment with unified Google billing, preview channels, and automatic SSL.

Global CDN Preview Channels Auto SSL Unified Billing

Plan

Pro

Regions

EU (Malta), Africa

CI/CD

GitHub integration

Rollback

Instant

Alternatives Considered

Netlify Railway AWS Amplify

P

PostgreSQL + PostGIS

Spatial Database

Enterprise-grade relational database with PostGIS extension for geospatial queries and location indexing.

Spatial Indexes Proximity Search Geofencing JSONB

Version

PostgreSQL 15+

Extension

PostGIS 3.x

Index

GiST spatial

SRID

4326 (WGS84)

Alternatives Considered

MongoDB MySQL Spatial CockroachDB

External Services

Firebase Cloud Messaging

Push notifications for engagement, alerts, and SOS broadcasts

Free: Unlimited messages

Firebase Analytics

Product analytics, user behavior, engagement metrics

Free: Unlimited events

Twilio

SMS fallback for SOS alerts when push unavailable

Pay-per-use: ~$0.05/SMS

Cloud Error Reporting

Error tracking, performance monitoring, crash reporting

Free tier included with Firebase

Mapbox

Maps with clustering, custom styling, geolocation

Free tier: 50K loads/month

Security & Performance

Security Specifications

Data Encryption AES-256 at rest, TLS 1.3 in transit

Authentication JWT + Refresh tokens

Database Security Row Level Security (RLS)

API Protection Rate limiting, CORS

Content Moderation AI-assisted + manual review

Compliance GDPR-ready architecture

Performance Targets

Initial Load <3 seconds

Time to Interactive <5 seconds

Realtime Updates <500ms

Map Pin Updates <2 seconds

SOS Alert Delivery <3 seconds

API Uptime 99.9%

PWA Capabilities

Install Prompt iOS + Android

Offline Mode Phase 2 (cached content)

Push Notifications Full support

Background Sync Queued actions

Geolocation Foreground tracking

Camera Access Photo capture

Background Location Note: PWAs have limited background location capabilities. Phase 1 uses foreground tracking with user consent. Native app wrappers (Phase 2) enable continuous background tracking for "Who's Around" feature.

Project Structure

app/

(auth)/ login, register

(main)/ feed, map, post, profile

(merchant)/ dashboard

api/ posts, pins, users

components/

ui/ shadcn components

feed/ feed components

map/ map components

shared/ shared components

lib/

supabase/ database client

utils/ helper functions

stores/

Zustand stores state management

types/

TypeScript types type definitions

prisma/

schema.prisma database schema

Development Tools

TypeScript

Type-safe JavaScript for better DX and fewer bugs

Strict mode enabled

Vitest + Playwright

Unit testing and E2E testing framework

CI/CD integrated

ESLint + Prettier

Code linting and formatting standards

Pre-commit hooks

GitHub Actions

Automated testing, linting, and deployment

PR checks + deploy

Storybook

Component documentation and visual testing

UI component library

Claude Code

AI-assisted development acceleration

Development workflow

Infrastructure Cost Estimation

MVP (0-1,000 users)

Firebase (Free tier)$0

Supabase Free$0

Mapbox Free$0

Twilio~$20

Total~$20/month

Growth (1,000-10,000 users)

Firebase Blaze~$15

Supabase Pro$25

Mapbox~$50

Twilio~$50

Total~$140/month

Scale (10,000-100,000 users)

Firebase Blaze~$100

Supabase Pro+$100

Mapbox~$300

Twilio~$150

Total~$650/month

Alternatives Considered

Category	Selected	Alternatives	Reason
Database	Supabase	PlanetScale, MongoDB	All-in-one, PostGIS support
Maps	Mapbox	Google Maps	Best clustering, cheaper at scale
Auth	Firebase Auth	Supabase Auth, Clerk	Best phone OTP, Google integration
Hosting	Firebase Hosting	Vercel, Netlify	Unified Google billing