# saptarshi-mandal-1234/spotland architecture

> Architecture diagram of the GitHub repository saptarshi-mandal-1234/spotland, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saptarshi-mandal-1234/spotland
- Repository: https://github.com/saptarshi-mandal-1234/spotland

## Overview

SPOTLAND is an India-focused travel PWA. Users explore nearby places, then can get directions, view events and venues, plan trips, save favorites, read or submit reviews, and use safety, SOS, and live-sharing tools. The browser app calls a same-origin API routed to a Cloudflare Worker; the Worker handles domain APIs and provider access, with D1-backed persistence and private R2 photo storage. The README and source index establish capabilities and some module links, but many feature implementations were not excerpted, so uncertain internal connections are omitted.

Main entry points: [`web/src/App.tsx`](https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/App.tsx) (App shell), [`worker/src/index.ts`](https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/index.ts) (API router), [`worker/src/routing.ts`](https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/routing.ts) (Routing service), [`worker/src/review-photos.ts`](https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/review-photos.ts) (Review photos)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Travel app"]
  node_app["App shell<br/>[App.tsx]"]
  node_explore["Nearby explore<br/>[Explore.tsx]"]
  node_account["Account &amp; favorites<br/>[Account.tsx]"]
  node_trips["Trip planner<br/>[TripPlanner.tsx]"]
  node_events["Events &amp; calendar<br/>[Events.tsx]"]
  node_venues["Venue discovery<br/>[Venues.tsx]"]
  node_reviews["Reviews &amp; photos<br/>[Reviews.tsx]"]
  node_safety["Safety tools<br/>[Safety.tsx]"]
  node_sos["SOS<br/>[SOS.tsx]"]
  node_live["Live sharing<br/>[LiveShare.tsx]"]
end

subgraph group_domain["Shared domain"]
  node_place_model["Place model<br/>[places.ts]"]
  node_route_model["Route model<br/>[routes.ts]"]
  node_review_model["Review model<br/>[reviews.ts]"]
  node_sos_model["SOS model<br/>[sos.ts]"]
end

subgraph group_api["Worker services"]
  node_router["API router<br/>[index.ts]"]
  node_providers["Place providers<br/>[providers.ts]"]
  node_routing["Routing service<br/>[routing.ts]"]
  node_accounts["Account service<br/>[accounts.ts]"]
  node_event_service["Events service<br/>[events.ts]"]
  node_review_service["Review photos<br/>[review-photos.ts]"]
  node_sos_service["SOS service<br/>[sos.ts]"]
end

subgraph group_storage["Persistence"]
  node_db_helpers["D1 helpers<br/>[db.ts]"]
  node_d1[("Cloudflare D1")]
  node_r2[("Private R2")]
end

subgraph group_external["External services"]
  node_map_providers{{"Map &amp; place providers"}}
  node_osrm{{"OSRM"}}
  node_google{{"Google sign-in"}}
end

node_traveler(("Traveler"))

node_traveler -->|"uses"| node_app
node_app -->|"opens"| node_explore
node_app -->|"opens"| node_account
node_app -->|"opens"| node_trips
node_app -->|"opens"| node_events
node_app -->|"opens"| node_venues
node_app -->|"opens"| node_safety
node_app -->|"opens"| node_sos
node_app -->|"opens"| node_live
node_traveler -->|"submits"| node_reviews
node_explore -.->|"requests places"| node_router
node_trips -.->|"requests routes"| node_router
node_reviews -->|"uploads photos"| node_review_service
node_sos -->|"uses sharing"| node_live
node_router -->|"dispatches"| node_providers
node_router -->|"dispatches"| node_routing
node_router -->|"dispatches"| node_event_service
node_router -->|"dispatches"| node_review_service
node_router -->|"dispatches"| node_sos_service
node_providers -->|"reads cache"| node_db_helpers
node_routing -->|"reads cache"| node_db_helpers
node_db_helpers -->|"reads and writes"| node_d1
node_review_service -.->|"stores photos"| node_r2
node_providers -.->|"queries"| node_map_providers
node_routing -->|"requests routes"| node_osrm
node_accounts -->|"verifies sign-in"| node_google
node_explore -.->|"uses place data"| node_place_model
node_routing -->|"returns route"| node_route_model
node_review_service -->|"validates reviews"| node_review_model
node_sos_service -->|"uses SOS rules"| node_sos_model

click node_app "https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/App.tsx"
click node_explore "https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/Explore.tsx"
click node_account "https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/Account.tsx"
click node_trips "https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/TripPlanner.tsx"
click node_events "https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/Events.tsx"
click node_venues "https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/Venues.tsx"
click node_reviews "https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/Reviews.tsx"
click node_safety "https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/Safety.tsx"
click node_sos "https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/SOS.tsx"
click node_live "https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/LiveShare.tsx"
click node_place_model "https://github.com/saptarshi-mandal-1234/spotland/blob/main/shared/places.ts"
click node_route_model "https://github.com/saptarshi-mandal-1234/spotland/blob/main/shared/routes.ts"
click node_review_model "https://github.com/saptarshi-mandal-1234/spotland/blob/main/shared/reviews.ts"
click node_sos_model "https://github.com/saptarshi-mandal-1234/spotland/blob/main/shared/sos.ts"
click node_router "https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/index.ts"
click node_providers "https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/providers.ts"
click node_routing "https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/routing.ts"
click node_accounts "https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/accounts.ts"
click node_event_service "https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/events.ts"
click node_review_service "https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/review-photos.ts"
click node_sos_service "https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/sos.ts"
click node_db_helpers "https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/db.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_app,node_explore,node_account,node_trips,node_events,node_venues,node_reviews,node_safety,node_sos,node_live toneBlue
class node_place_model,node_route_model,node_review_model,node_sos_model toneAmber
class node_router,node_providers,node_routing,node_accounts,node_event_service,node_review_service,node_sos_service toneMint
class node_db_helpers,node_d1,node_r2 toneRose
class node_map_providers,node_osrm,node_google,node_traveler toneIndigo
```

## Components

### Travel app

- [App shell](https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Nearby explore](https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/Explore.tsx): `web/src/Explore.tsx`
- [Account & favorites](https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/Account.tsx): `web/src/Account.tsx`
- [Trip planner](https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/TripPlanner.tsx): `web/src/TripPlanner.tsx`
- [Events & calendar](https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/Events.tsx): `web/src/Events.tsx`
- [Venue discovery](https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/Venues.tsx): `web/src/Venues.tsx`
- [Reviews & photos](https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/Reviews.tsx): `web/src/Reviews.tsx`
- [Safety tools](https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/Safety.tsx): `web/src/Safety.tsx`
- [SOS](https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/SOS.tsx): `web/src/SOS.tsx`
- [Live sharing](https://github.com/saptarshi-mandal-1234/spotland/blob/main/web/src/LiveShare.tsx): `web/src/LiveShare.tsx`

### Shared domain

- [Place model](https://github.com/saptarshi-mandal-1234/spotland/blob/main/shared/places.ts): `shared/places.ts`
- [Route model](https://github.com/saptarshi-mandal-1234/spotland/blob/main/shared/routes.ts): `shared/routes.ts`
- [Review model](https://github.com/saptarshi-mandal-1234/spotland/blob/main/shared/reviews.ts): `shared/reviews.ts`
- [SOS model](https://github.com/saptarshi-mandal-1234/spotland/blob/main/shared/sos.ts): `shared/sos.ts`

### Worker services

- [API router](https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/index.ts): `worker/src/index.ts`
- [Place providers](https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/providers.ts): `worker/src/providers.ts`
- [Routing service](https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/routing.ts): `worker/src/routing.ts`
- [Account service](https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/accounts.ts): `worker/src/accounts.ts`
- [Events service](https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/events.ts): `worker/src/events.ts`
- [Review photos](https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/review-photos.ts): `worker/src/review-photos.ts`
- [SOS service](https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/sos.ts): `worker/src/sos.ts`

### Persistence

- [D1 helpers](https://github.com/saptarshi-mandal-1234/spotland/blob/main/worker/src/db.ts): `worker/src/db.ts`
- **Cloudflare D1**
- **Private R2**

### External services

- **Map & place providers**
- **OSRM**
- **Google sign-in**

### Other components

- **Traveler**

## Connections

- Traveler → App shell: uses (evidence: `README.md`)
- App shell → Nearby explore: opens (evidence: `web/src/App.tsx`)
- App shell → Account & favorites: opens (evidence: `web/src/App.tsx`)
- App shell → Trip planner: opens (evidence: `web/src/App.tsx`)
- App shell → Events & calendar: opens (evidence: `web/src/App.tsx`)
- App shell → Venue discovery: opens (evidence: `web/src/App.tsx`)
- App shell → Safety tools: opens (evidence: `web/src/App.tsx`)
- App shell → SOS: opens (evidence: `web/src/App.tsx`)
- App shell → Live sharing: opens (evidence: `web/src/App.tsx`)
- Traveler → Reviews & photos: submits (evidence: `README.md`)
- Nearby explore → API router: requests places
- Trip planner → API router: requests routes
- Reviews & photos → Review photos: uploads photos (evidence: `web/src/Reviews.tsx`)
- SOS → Live sharing: uses sharing (evidence: `web/src/SOS.tsx`)
- API router → Place providers: dispatches (evidence: `worker/src/index.ts`)
- API router → Routing service: dispatches (evidence: `worker/src/index.ts`)
- API router → Events service: dispatches (evidence: `worker/src/index.ts`)
- API router → Review photos: dispatches (evidence: `worker/src/index.ts`)
- API router → SOS service: dispatches (evidence: `worker/src/index.ts`)
- Place providers → D1 helpers: reads cache (evidence: `worker/src/providers.ts`)
- Routing service → D1 helpers: reads cache (evidence: `worker/src/routing.ts`)
- D1 helpers → Cloudflare D1: reads and writes (evidence: `README.md`)
- Review photos → Private R2: stores photos
- Place providers → Map & place providers: queries
- Routing service → OSRM: requests routes (evidence: `worker/src/routing.ts`)
- Account service → Google sign-in: verifies sign-in (evidence: `worker/src/accounts.ts`)
- Nearby explore → Place model: uses place data
- Routing service → Route model: returns route (evidence: `worker/src/routing.ts`)
- Review photos → Review model: validates reviews (evidence: `worker/src/review-photos.ts`)
- SOS service → SOS model: uses SOS rules (evidence: `worker/src/sos.ts`)
