# gurugouthamkanchi/project-radar architecture

> Architecture diagram of the GitHub repository gurugouthamkanchi/project-radar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gurugouthamkanchi/project-radar
- Repository: https://github.com/gurugouthamkanchi/project-radar

## Overview

#### 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.

Main entry points: [`app/room/[code]/page.tsx`](https://github.com/gurugouthamkanchi/project-radar/blob/main/app/room/%5Bcode%5D/page.tsx) (Active room orchestrator), [`lib/useLocation.ts`](https://github.com/gurugouthamkanchi/project-radar/blob/main/lib/useLocation.ts) (Geolocation capture), [`lib/crypto.ts`](https://github.com/gurugouthamkanchi/project-radar/blob/main/lib/crypto.ts) (Client encryption), [`lib/firebaseLocation.ts`](https://github.com/gurugouthamkanchi/project-radar/blob/main/lib/firebaseLocation.ts) (Validated RTDB sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser client"]
  node_room["Active room orchestrator<br/>Client page<br/>[page.tsx]"]
  node_location["Geolocation capture<br/>Client hook<br/>[useLocation.ts]"]
  node_crypto["Client encryption<br/>Crypto module<br/>[crypto.ts]"]
  node_sync["Validated RTDB sync<br/>Client data module"]
  node_spatial["Radar, map &amp; proximity<br/>Visualization layer<br/>[RadarMap.tsx]"]
  node_alerts["Foreground alerts<br/>UI component<br/>[AlertBanner.tsx]"]
  node_pushclient["Browser push integration<br/>Client module<br/>[push.ts]"]
  node_serviceworker["PWA service worker<br/>[sw.js]"]
end

subgraph group_next["Next.js on Vercel"]
  node_landing["Landing &amp; room creation<br/>Next page<br/>[page.tsx]"]
  node_share["Share-link view<br/>Next page<br/>[page.tsx]"]
  node_aiapi{{"AI analyst &amp; commands<br/>Route handlers<br/>[route.ts]"}}
  node_pushapi{{"Push subscription &amp; delivery<br/>Route handlers<br/>[route.ts]"}}
  node_cleanup{{"Inactive room cleanup<br/>Route handler<br/>[route.ts]"}}
end

subgraph group_external["External services"]
  node_rtdb[("Firebase RTDB<br/>Realtime database")]
  node_rules["RTDB write rules<br/>Firebase rules"]
  node_gemini["Google Gemini 2.5 Flash<br/>AI provider"]
  node_webpush["Web Push / VAPID<br/>Push service"]
end

node_landing -->|"creates / navigates"| node_room
node_share -->|"opens room"| node_room
node_room -->|"starts sharing"| node_location
node_location -->|"coordinates"| node_crypto
node_crypto -->|"ciphertext"| node_sync
node_sync -->|"live room state"| node_rtdb
node_rules -.->|"enforces writes"| node_rtdb
node_rtdb -->|"peer ciphertext updates"| node_room
node_room -->|"decrypted peer positions"| node_spatial
node_spatial -->|"proximity / SOS state"| node_alerts
node_room -->|"radar context and commands"| node_aiapi
node_aiapi -->|"server-only API key"| node_gemini
node_room -->|"notification consent"| node_pushclient
node_pushclient -->|"subscription"| node_pushapi
node_pushapi -->|"VAPID delivery"| node_webpush
node_webpush -->|"background push"| node_serviceworker
node_cleanup -->|"deletes stale rooms"| node_rtdb

click node_landing "https://github.com/gurugouthamkanchi/project-radar/blob/main/app/page.tsx"
click node_room "https://github.com/gurugouthamkanchi/project-radar/blob/main/app/room/%5Bcode%5D/page.tsx"
click node_share "https://github.com/gurugouthamkanchi/project-radar/blob/main/app/room/%5Bcode%5D/share/page.tsx"
click node_location "https://github.com/gurugouthamkanchi/project-radar/blob/main/lib/useLocation.ts"
click node_crypto "https://github.com/gurugouthamkanchi/project-radar/blob/main/lib/crypto.ts"
click node_sync "https://github.com/gurugouthamkanchi/project-radar/blob/main/lib/firebaseLocation.ts"
click node_rules "https://github.com/gurugouthamkanchi/project-radar/blob/main/firebase.rules.json"
click node_spatial "https://github.com/gurugouthamkanchi/project-radar/blob/main/components/RadarMap.tsx"
click node_alerts "https://github.com/gurugouthamkanchi/project-radar/blob/main/components/AlertBanner.tsx"
click node_pushclient "https://github.com/gurugouthamkanchi/project-radar/blob/main/lib/push.ts"
click node_serviceworker "https://github.com/gurugouthamkanchi/project-radar/blob/main/public/sw.js"
click node_aiapi "https://github.com/gurugouthamkanchi/project-radar/blob/main/app/api/ai-analyst/route.ts"
click node_pushapi "https://github.com/gurugouthamkanchi/project-radar/blob/main/app/api/push/notify/route.ts"
click node_cleanup "https://github.com/gurugouthamkanchi/project-radar/blob/main/app/api/cleanup-rooms/route.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_room,node_location,node_crypto,node_sync,node_spatial,node_alerts,node_pushclient,node_serviceworker toneBlue
class node_landing,node_share,node_aiapi,node_pushapi,node_cleanup toneAmber
class node_rtdb,node_rules,node_gemini,node_webpush toneMint
```

## Components

### Browser client

Consent, GPS, encryption, and live room UI run client-side.

- [Active room orchestrator](https://github.com/gurugouthamkanchi/project-radar/blob/main/app/room/%5Bcode%5D/page.tsx): Client page · Coordinates identity, consent, sync, alerts, map state, and AI. · `app/room/[code]/page.tsx`
- [Geolocation capture](https://github.com/gurugouthamkanchi/project-radar/blob/main/lib/useLocation.ts): Client hook · `lib/useLocation.ts`
- [Client encryption](https://github.com/gurugouthamkanchi/project-radar/blob/main/lib/crypto.ts): Crypto module · AES-GCM encrypts location payloads before synchronization. · `lib/crypto.ts`
- [Validated RTDB sync](https://github.com/gurugouthamkanchi/project-radar/blob/main/lib/firebaseLocation.ts): Client data module · Validates payloads and manages live writes, subscriptions, and disconnect cleanup. · `lib/firebaseLocation.ts`
- [Radar, map & proximity](https://github.com/gurugouthamkanchi/project-radar/blob/main/components/RadarMap.tsx): Visualization layer · Decrypts peer positions for radar/map rendering and distance alerts. · `components/RadarMap.tsx`
- [Foreground alerts](https://github.com/gurugouthamkanchi/project-radar/blob/main/components/AlertBanner.tsx): UI component · Presents proximity and SOS state. · `components/AlertBanner.tsx`
- [Browser push integration](https://github.com/gurugouthamkanchi/project-radar/blob/main/lib/push.ts): Client module · Registers Push API subscriptions through the application API. · `lib/push.ts`
- [PWA service worker](https://github.com/gurugouthamkanchi/project-radar/blob/main/public/sw.js): Service worker · Receives background push events. · `public/sw.js`

### Next.js on Vercel

App Router pages and trusted route handlers.

- [Landing & room creation](https://github.com/gurugouthamkanchi/project-radar/blob/main/app/page.tsx): Next page · `app/page.tsx`
- [Share-link view](https://github.com/gurugouthamkanchi/project-radar/blob/main/app/room/%5Bcode%5D/share/page.tsx): Next page · Joins a room by dynamic code; the E2E secret stays in the URL hash. · `app/room/[code]/share/page.tsx`
- [AI analyst & commands](https://github.com/gurugouthamkanchi/project-radar/blob/main/app/api/ai-analyst/route.ts): Route handlers · Keeps Gemini access server-side and receives radar-derived context. · `app/api/ai-analyst/route.ts`
- [Push subscription & delivery](https://github.com/gurugouthamkanchi/project-radar/blob/main/app/api/push/notify/route.ts): Route handlers · Registers subscriptions and sends rate-limited VAPID notifications. · `app/api/push/notify/route.ts`
- [Inactive room cleanup](https://github.com/gurugouthamkanchi/project-radar/blob/main/app/api/cleanup-rooms/route.ts): Route handler · Deletes stale rooms using a server-only cleanup secret. · `app/api/cleanup-rooms/route.ts`

### External services

- **Firebase RTDB**: Realtime database · Stores room state and encrypted peer locations.
- [RTDB write rules](https://github.com/gurugouthamkanchi/project-radar/blob/main/firebase.rules.json): Firebase rules · Constrain permitted room and participant writes. · `firebase.rules.json`
- **Google Gemini 2.5 Flash**: AI provider
- **Web Push / VAPID**: Push service

## Connections

- Landing & room creation → Active room orchestrator: creates / navigates
- Share-link view → Active room orchestrator: opens room
- Active room orchestrator → Geolocation capture: starts sharing
- Geolocation capture → Client encryption: coordinates
- Client encryption → Validated RTDB sync: ciphertext
- Validated RTDB sync → Firebase RTDB: live room state
- RTDB write rules → Firebase RTDB: enforces writes
- Firebase RTDB → Active room orchestrator: peer ciphertext updates
- Active room orchestrator → Radar, map & proximity: decrypted peer positions
- Radar, map & proximity → Foreground alerts: proximity / SOS state
- Active room orchestrator → AI analyst & commands: radar context and commands
- AI analyst & commands → Google Gemini 2.5 Flash: server-only API key
- Active room orchestrator → Browser push integration: notification consent
- Browser push integration → Push subscription & delivery: subscription
- Push subscription & delivery → Web Push / VAPID: VAPID delivery
- Web Push / VAPID → PWA service worker: background push
- Inactive room cleanup → Firebase RTDB: deletes stale rooms