gurugouthamkanchi/project-radar

Purpose and runtime

ProximaX is a consent-based, browser-first real-time group location radar. It is a Next.js 14 App Router TypeScript application, hosted for server/API execution on Vercel, with Firebase Realtime Database (RTDB) for live room state. Clients render a radar and map, acquire GPS, encrypt location payloads, and synchronize ciphertext with peers.

Primary UI entry points:

• Landing/room creation: app/page.tsx

• Active shared room: app/room/[code]/page.tsx

• Share-link view: app/room/[code]/share/page.tsx

• Global shell/PWA styling: app/layout.tsx, app/globals.css, public/sw.js

Room and client session model

A room is addressed by its dynamic code; participants join through a shareable URL. The E2E secret is held in the URL hash, deliberately outside server requests. The room page is the client orchestration boundary: consent, participant identity, live Firebase subscriptions, location sharing lifecycle, SOS/proximity behavior, map state, and AI interaction converge there.

Relevant paths:

• app/room/[code]/page.tsx

• app/room/[code]/share/page.tsx

• lib/firebase.ts

Location capture, validation, and encrypted sync

Browser geolocation is encapsulated in lib/useLocation.ts. Before RTDB writes, coordinates and participant payloads are constrained by validation; location data is AES-GCM encrypted client-side, so Firebase stores ciphertext only. Session cleanup uses RTDB connection/disconnect semantics; stale rooms are also eligible for server cleanup.

Relevant paths:

• lib/useLocation.ts

• lib/locationValidator.ts

• lib/crypto.ts

• lib/firebaseLocation.ts

• firebase.rules.json

Live spatial visualization and alerts

The active room converts decrypted peer positions into radar and Leaflet-style map visualizations. Geodesic distance calculations drive proximity checks and radius-based alerts; UI components present peer cards, alert banners, radius controls, and tracked mini-map state.

Relevant paths:

• components/RadarMap.tsx

• components/TrackedMiniMap.tsx

• components/RadiusSlider.tsx

• components/PersonCard.tsx

• lib/haversine.ts

Server-side operational APIs

Next route handlers form the trusted boundary for capabilities that must not expose secrets to browsers:

• Gemini-backed analyst summaries and natural-language command interpretation: app/api/ai-analyst/route.ts, app/api/ai-command/route.ts

• Push subscription registration and notification delivery, using VAPID credentials: app/api/push/subscribe/route.ts, app/api/push/notify/route.ts

• Inactive-room deletion, protected by a cleanup secret: app/api/cleanup-rooms/route.ts

AI receives radar-derived context server-side; its Gemini API key remains server-only. Push delivery is rate-limited per the application design.

Notification and PWA boundary

The browser obtains a push subscription through the application API, while the service worker receives background push events. Foreground proximity/SOS state is also surfaced in the application UI. lib/push.ts centralizes browser-side push integration.

Relevant paths:

• lib/push.ts

• public/sw.js

• public/manifest.json

• components/AlertBanner.tsx

External dependencies and trust boundaries

• Browser: Geolocation, Web Crypto/AES-GCM, Notifications, Push API, service worker.

• Firebase RTDB: real-time room/peer synchronization; rules in firebase.rules.json enforce write constraints, but cannot decrypt coordinate ciphertext.

• Google Gemini 2.5 Flash: accessed only through Next.js API routes.

• Web Push/VAPID: server sends notifications; browser holds subscriptions.

• Vercel/Next.js: hosts pages and route handlers. Environment configuration supplies Firebase public settings, VAPID server keys, Gemini key, and cleanup secret.