# hsu-isaac/tripmap architecture

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

- Interactive diagram: https://gitdiagram.com/hsu-isaac/tripmap
- Repository: https://github.com/hsu-isaac/tripmap

## Overview

TripMap is a map-based trip-planning application. Users create trips, search for places, organize points into layers and categories, plan routes, and view the result on an interactive map; they can share trips with different visibility settings. The graph includes documented collaboration, cloning, and mobile capabilities. Source excerpts show API, authentication, and persistence behavior, but not most client-to-API wiring, so those links are omitted or marked unverified.

Main entry points: [`src/lib/auth/middleware.ts`](https://github.com/hsu-isaac/tripmap/blob/main/src/lib/auth/middleware.ts) (Authentication), [`src/lib/api/helpers.ts`](https://github.com/hsu-isaac/tripmap/blob/main/src/lib/api/helpers.ts) (API access and validation), [`src/app/trips/[tripId]/TripDetailClient.tsx`](https://github.com/hsu-isaac/tripmap/blob/main/src/app/trips/%5BtripId%5D/TripDetailClient.tsx) (Trip detail client), [`src/app/api/trips/route.ts`](https://github.com/hsu-isaac/tripmap/blob/main/src/app/api/trips/route.ts) (Trip management API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Trip experience"]
  node_trip_pages["Trip pages<br/>[page.tsx]"]
  node_trip_client["Trip detail client"]
  node_map["Interactive map<br/>[TripMap.tsx]"]
  node_trip_list["Trip listing<br/>[TripsClient.tsx]"]
  node_mobile["Mobile views"]
end

subgraph group_planning["Trip planning"]
  node_trip_controls["Trip editing controls<br/>[TripSidebar.tsx]"]
  node_drag_logic["Drag-and-drop logic<br/>[useDragHandlers.ts]"]
  node_place_entry["Location search<br/>[LocationSearch.tsx]"]
  node_route_entry["Route planning<br/>[AddRouteModal.tsx]"]
  node_sharing["Sharing controls<br/>[ShareModal.tsx]"]
end

subgraph group_api["API workflows"]
  node_trip_api["Trip management API<br/>[route.ts]"]
  node_trip_detail_api["Trip detail API<br/>[route.ts]"]
  node_point_api["Point API<br/>[route.ts]"]
  node_route_api["Route API<br/>[route.ts]"]
  node_geocode_api["Place search API<br/>[route.ts]"]
  node_clone_api["Trip cloning API<br/>[route.ts]"]
  node_invite_api["Invitations API<br/>[route.ts]"]
end

subgraph group_platform["Identity and access"]
  node_auth["Authentication<br/>[middleware.ts]"]
  node_api_helpers["API access and validation<br/>[helpers.ts]"]
  node_supabase["Supabase client<br/>[server.ts]"]
  node_database[("Trip data store")]
end

subgraph group_integrations["External services"]
  node_google_places["Google Places"]
  node_google_maps["Google Maps"]
end

node_traveler(("Traveler"))

node_traveler -->|"browses trips"| node_trip_list
node_traveler -->|"plans a trip"| node_trip_pages
node_trip_pages -.->|"renders"| node_trip_client
node_trip_client -.->|"uses controls"| node_trip_controls
node_trip_client -->|"shows locations"| node_map
node_trip_client -->|"adapts for mobile"| node_mobile
node_trip_client -.->|"loads trip"| node_trip_detail_api
node_trip_list -.->|"loads and creates trips"| node_trip_api
node_trip_controls -.->|"handles rearrangement"| node_drag_logic
node_drag_logic -->|"invokes reorder or move"| node_trip_controls
node_trip_controls -.->|"updates points"| node_point_api
node_place_entry -.->|"searches places"| node_geocode_api
node_geocode_api -->|"requests suggestions"| node_google_places
node_trip_controls -.->|"opens route planning"| node_route_entry
node_route_entry -.->|"saves routes"| node_route_api
node_sharing -.->|"manages invitations"| node_invite_api
node_sharing -.->|"sets visibility"| node_trip_detail_api
node_trip_api -->|"requires authentication"| node_auth
node_trip_api -->|"reads and writes trips"| node_database
node_trip_api -->|"creates default layer"| node_database
node_trip_api -->|"validates and formats errors"| node_api_helpers
node_trip_detail_api -->|"creates client"| node_supabase
node_trip_detail_api -->|"reads trip and contents"| node_database
node_trip_detail_api -->|"checks access"| node_api_helpers
node_point_api -->|"requires authentication"| node_auth
node_point_api -->|"checks access and validates"| node_api_helpers
node_point_api -->|"reads and writes points"| node_database
node_route_api -->|"requires authentication"| node_auth
node_route_api -->|"reads and writes routes"| node_database
node_route_api -->|"validates requests"| node_api_helpers
node_geocode_api -->|"requires authentication"| node_auth
node_geocode_api -->|"formats errors"| node_api_helpers
node_clone_api -->|"requires authentication"| node_auth
node_clone_api -->|"checks access and validates"| node_api_helpers
node_clone_api -->|"copies trip content"| node_database
node_auth -->|"creates client"| node_supabase
node_supabase -->|"connects to"| node_database
node_map -->|"renders map"| node_google_maps

click node_trip_pages "https://github.com/hsu-isaac/tripmap/blob/main/src/app/trips/%5BtripId%5D/page.tsx"
click node_trip_client "https://github.com/hsu-isaac/tripmap/blob/main/src/app/trips/%5BtripId%5D/TripDetailClient.tsx"
click node_map "https://github.com/hsu-isaac/tripmap/blob/main/src/components/map/TripMap.tsx"
click node_trip_list "https://github.com/hsu-isaac/tripmap/blob/main/src/app/trips/TripsClient.tsx"
click node_mobile "https://github.com/hsu-isaac/tripmap/blob/main/src/components/trip-detail/MobileTripContent.tsx"
click node_trip_api "https://github.com/hsu-isaac/tripmap/blob/main/src/app/api/trips/route.ts"
click node_trip_detail_api "https://github.com/hsu-isaac/tripmap/blob/main/src/app/api/trips/%5BtripId%5D/route.ts"
click node_point_api "https://github.com/hsu-isaac/tripmap/blob/main/src/app/api/trips/%5BtripId%5D/points/route.ts"
click node_route_api "https://github.com/hsu-isaac/tripmap/blob/main/src/app/api/trips/%5BtripId%5D/routes/route.ts"
click node_geocode_api "https://github.com/hsu-isaac/tripmap/blob/main/src/app/api/geocode/route.ts"
click node_clone_api "https://github.com/hsu-isaac/tripmap/blob/main/src/app/api/trips/%5BtripId%5D/clone/route.ts"
click node_invite_api "https://github.com/hsu-isaac/tripmap/blob/main/src/app/api/trips/%5BtripId%5D/invitations/route.ts"
click node_trip_controls "https://github.com/hsu-isaac/tripmap/blob/main/src/components/trip-detail/TripSidebar.tsx"
click node_drag_logic "https://github.com/hsu-isaac/tripmap/blob/main/src/hooks/useDragHandlers.ts"
click node_place_entry "https://github.com/hsu-isaac/tripmap/blob/main/src/components/trip-detail/LocationSearch.tsx"
click node_route_entry "https://github.com/hsu-isaac/tripmap/blob/main/src/components/trip-detail/AddRouteModal.tsx"
click node_sharing "https://github.com/hsu-isaac/tripmap/blob/main/src/components/trip-detail/ShareModal.tsx"
click node_auth "https://github.com/hsu-isaac/tripmap/blob/main/src/lib/auth/middleware.ts"
click node_api_helpers "https://github.com/hsu-isaac/tripmap/blob/main/src/lib/api/helpers.ts"
click node_supabase "https://github.com/hsu-isaac/tripmap/blob/main/src/lib/supabase/server.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_trip_pages,node_trip_client,node_map,node_trip_list,node_mobile toneBlue
class node_trip_controls,node_drag_logic,node_place_entry,node_route_entry,node_sharing toneAmber
class node_trip_api,node_trip_detail_api,node_point_api,node_route_api,node_geocode_api,node_clone_api,node_invite_api toneMint
class node_auth,node_api_helpers,node_supabase,node_database toneRose
class node_google_places,node_google_maps,node_traveler toneIndigo
```

## Components

### Trip experience

- [Trip pages](https://github.com/hsu-isaac/tripmap/blob/main/src/app/trips/%5BtripId%5D/page.tsx): `src/app/trips/[tripId]/page.tsx`
- [Trip detail client](https://github.com/hsu-isaac/tripmap/blob/main/src/app/trips/%5BtripId%5D/TripDetailClient.tsx): `src/app/trips/[tripId]/TripDetailClient.tsx`
- [Interactive map](https://github.com/hsu-isaac/tripmap/blob/main/src/components/map/TripMap.tsx): `src/components/map/TripMap.tsx`
- [Trip listing](https://github.com/hsu-isaac/tripmap/blob/main/src/app/trips/TripsClient.tsx): `src/app/trips/TripsClient.tsx`
- [Mobile views](https://github.com/hsu-isaac/tripmap/blob/main/src/components/trip-detail/MobileTripContent.tsx): `src/components/trip-detail/MobileTripContent.tsx`

### Trip planning

- [Trip editing controls](https://github.com/hsu-isaac/tripmap/blob/main/src/components/trip-detail/TripSidebar.tsx): `src/components/trip-detail/TripSidebar.tsx`
- [Drag-and-drop logic](https://github.com/hsu-isaac/tripmap/blob/main/src/hooks/useDragHandlers.ts): `src/hooks/useDragHandlers.ts`
- [Location search](https://github.com/hsu-isaac/tripmap/blob/main/src/components/trip-detail/LocationSearch.tsx): `src/components/trip-detail/LocationSearch.tsx`
- [Route planning](https://github.com/hsu-isaac/tripmap/blob/main/src/components/trip-detail/AddRouteModal.tsx): `src/components/trip-detail/AddRouteModal.tsx`
- [Sharing controls](https://github.com/hsu-isaac/tripmap/blob/main/src/components/trip-detail/ShareModal.tsx): `src/components/trip-detail/ShareModal.tsx`

### API workflows

- [Trip management API](https://github.com/hsu-isaac/tripmap/blob/main/src/app/api/trips/route.ts): `src/app/api/trips/route.ts`
- [Trip detail API](https://github.com/hsu-isaac/tripmap/blob/main/src/app/api/trips/%5BtripId%5D/route.ts): `src/app/api/trips/[tripId]/route.ts`
- [Point API](https://github.com/hsu-isaac/tripmap/blob/main/src/app/api/trips/%5BtripId%5D/points/route.ts): `src/app/api/trips/[tripId]/points/route.ts`
- [Route API](https://github.com/hsu-isaac/tripmap/blob/main/src/app/api/trips/%5BtripId%5D/routes/route.ts): `src/app/api/trips/[tripId]/routes/route.ts`
- [Place search API](https://github.com/hsu-isaac/tripmap/blob/main/src/app/api/geocode/route.ts): `src/app/api/geocode/route.ts`
- [Trip cloning API](https://github.com/hsu-isaac/tripmap/blob/main/src/app/api/trips/%5BtripId%5D/clone/route.ts): `src/app/api/trips/[tripId]/clone/route.ts`
- [Invitations API](https://github.com/hsu-isaac/tripmap/blob/main/src/app/api/trips/%5BtripId%5D/invitations/route.ts): `src/app/api/trips/[tripId]/invitations/route.ts`

### Identity and access

- [Authentication](https://github.com/hsu-isaac/tripmap/blob/main/src/lib/auth/middleware.ts): `src/lib/auth/middleware.ts`
- [API access and validation](https://github.com/hsu-isaac/tripmap/blob/main/src/lib/api/helpers.ts): `src/lib/api/helpers.ts`
- [Supabase client](https://github.com/hsu-isaac/tripmap/blob/main/src/lib/supabase/server.ts): `src/lib/supabase/server.ts`
- **Trip data store**

### External services

- **Google Places**
- **Google Maps**

### Other components

- **Traveler**

## Connections

- Traveler → Trip listing: browses trips (evidence: `README.md`)
- Traveler → Trip pages: plans a trip (evidence: `README.md`)
- Trip pages → Trip detail client: renders
- Trip detail client → Trip editing controls: uses controls
- Trip detail client → Interactive map: shows locations (evidence: `README.md`)
- Trip detail client → Mobile views: adapts for mobile (evidence: `README.md`)
- Trip detail client → Trip detail API: loads trip
- Trip listing → Trip management API: loads and creates trips
- Trip editing controls → Drag-and-drop logic: handles rearrangement
- Drag-and-drop logic → Trip editing controls: invokes reorder or move (evidence: `src/hooks/useDragHandlers.ts`)
- Trip editing controls → Point API: updates points
- Location search → Place search API: searches places
- Place search API → Google Places: requests suggestions (evidence: `src/app/api/geocode/route.ts`)
- Trip editing controls → Route planning: opens route planning
- Route planning → Route API: saves routes
- Sharing controls → Invitations API: manages invitations
- Sharing controls → Trip detail API: sets visibility
- Trip management API → Authentication: requires authentication (evidence: `src/app/api/trips/route.ts`)
- Trip management API → Trip data store: reads and writes trips (evidence: `src/app/api/trips/route.ts`)
- Trip management API → Trip data store: creates default layer (evidence: `src/app/api/trips/route.ts`)
- Trip management API → API access and validation: validates and formats errors (evidence: `src/app/api/trips/route.ts`)
- Trip detail API → Supabase client: creates client (evidence: `src/app/api/trips/[tripId]/route.ts`)
- Trip detail API → Trip data store: reads trip and contents (evidence: `src/app/api/trips/[tripId]/route.ts`)
- Trip detail API → API access and validation: checks access (evidence: `src/app/api/trips/[tripId]/route.ts`)
- Point API → Authentication: requires authentication (evidence: `src/app/api/trips/[tripId]/points/route.ts`)
- Point API → API access and validation: checks access and validates (evidence: `src/app/api/trips/[tripId]/points/route.ts`)
- Point API → Trip data store: reads and writes points (evidence: `src/app/api/trips/[tripId]/points/route.ts`)
- Route API → Authentication: requires authentication (evidence: `src/app/api/trips/[tripId]/routes/route.ts`)
- Route API → Trip data store: reads and writes routes (evidence: `src/app/api/trips/[tripId]/routes/route.ts`)
- Route API → API access and validation: validates requests (evidence: `src/app/api/trips/[tripId]/routes/route.ts`)
- Place search API → Authentication: requires authentication (evidence: `src/app/api/geocode/route.ts`)
- Place search API → API access and validation: formats errors (evidence: `src/app/api/geocode/route.ts`)
- Trip cloning API → Authentication: requires authentication (evidence: `src/app/api/trips/[tripId]/clone/route.ts`)
- Trip cloning API → API access and validation: checks access and validates (evidence: `src/app/api/trips/[tripId]/clone/route.ts`)
- Trip cloning API → Trip data store: copies trip content (evidence: `src/app/api/trips/[tripId]/clone/route.ts`)
- Authentication → Supabase client: creates client (evidence: `src/lib/auth/middleware.ts`)
- Supabase client → Trip data store: connects to (evidence: `src/lib/supabase/server.ts`)
- Interactive map → Google Maps: renders map (evidence: `README.md`)
