# seed123-psy/smart-trip-planner architecture

> Architecture diagram of the GitHub repository seed123-psy/smart-trip-planner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/seed123-psy/smart-trip-planner
- Repository: https://github.com/seed123-psy/smart-trip-planner

## Overview

Smart Trip Planner is a browser-based trip-planning application with a Node.js API and MySQL-backed accounts and saved trips. Its main workflow takes a user’s city, dates, preferences and optional hotel; searches current places, builds and checks an itinerary with real routes, then returns a plan with food and preparation guidance. The UI also supports editing, maps, weather, PDF export and trip sharing. Edges reflect the excerpts, SOURCE INDEX references and README; several UI and administration internals are unsampled, so their links are shown only where documented.

Main entry points: [`scripts/app.js`](https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/app.js) (Trip view), [`tools/planner.js`](https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/planner.js) (Planning orchestrator), [`api/plan.js`](https://github.com/seed123-psy/smart-trip-planner/blob/main/api/plan.js) (Plan endpoint), [`scripts/plan-client.js`](https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/plan-client.js) (Plan client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Trip experience"]
  node_landing["Planning entry<br/>[landing-flow.js]"]
  node_planclient["Plan client<br/>[plan-client.js]"]
  node_tripview["Trip view<br/>[app.js]"]
  node_editor["Trip editor<br/>[editor.js]"]
  node_timeline["Timeline<br/>[timeline.js]"]
  node_map["Map and routes<br/>[map.js]"]
  node_routeclient["Route lookup<br/>[route.js]"]
  node_weather["Weather<br/>[weather.js]"]
  node_prepview["Preparation view<br/>[prep.js]"]
  node_foodview["Food view<br/>[food.js]"]
  node_pdf["PDF export<br/>[export-pdf.js]"]
end

subgraph group_planning["Planning workflow"]
  node_catalog["Place discovery<br/>[planner.js]"]
  node_schedule["Itinerary scheduling<br/>[planner.js]"]
  node_routeengine["Route and checks<br/>[planner.js]"]
  node_foodprep["Food and prep agents<br/>[planner.js]"]
  node_planner["Planning orchestrator<br/>[planner.js]"]
end

subgraph group_services["API and integrations"]
  node_api["API routing<br/>[api-router.js]"]
  node_server["Local server<br/>[serve.js]"]
  node_planapi["Plan endpoint<br/>[plan.js]"]
  node_amapproxy["Amap proxy<br/>[amap-proxy.js]"]
end

subgraph group_identity["Accounts and data"]
  node_login["Login and account<br/>[login.js]"]
  node_auth["Authentication<br/>[auth.js]"]
  node_sessions["Sessions<br/>[sessions.js]"]
  node_db[("MySQL database<br/>[db.js]")]
  node_trips["Saved trips<br/>[trips.js]"]
  node_tripdata["Example trip data<br/>[itinerary.js]"]
  node_poidata["Place data<br/>[poi.js]"]
  node_prepdata["Preparation data<br/>[prep.js]"]
end

node_traveler(("Traveler"))
node_amap{{"Amap services"}}
node_deepseek{{"DeepSeek"}}

node_traveler -->|"enters request"| node_landing
node_landing -->|"submits plan"| node_planclient
node_planclient -->|"requests plan"| node_planapi
node_planapi -->|"runs planning"| node_planner
node_planner -->|"searches places"| node_catalog
node_catalog -->|"queries places"| node_amap
node_planner -->|"selects and schedules"| node_schedule
node_planner -->|"calls model"| node_deepseek
node_planner -->|"checks and repairs"| node_routeengine
node_routeengine -->|"calculates routes"| node_amap
node_planner -->|"runs final agents"| node_foodprep
node_planapi -->|"saves result"| node_trips
node_planapi -->|"streams result"| node_planclient
node_planclient -->|"opens itinerary"| node_tripview
node_tripview -->|"renders days"| node_timeline
node_tripview -->|"shows map"| node_map
node_map -.->|"loads road routes"| node_routeclient
node_routeclient -->|"requests routing"| node_server
node_server -->|"forwards requests"| node_amapproxy
node_amapproxy -->|"proxies requests"| node_amap
node_tripview -->|"shows forecast"| node_weather
node_tripview -->|"edits itinerary"| node_editor
node_tripview -->|"opens preparation"| node_prepview
node_tripview -->|"shows food"| node_foodview
node_tripview -->|"exports PDF"| node_pdf
node_tripdata -->|"provides example"| node_tripview
node_poidata -.->|"supplements places"| node_planner
node_prepdata -->|"provides guidance"| node_prepview
node_traveler -->|"signs in"| node_login
node_login -->|"uses account APIs"| node_api
node_server -->|"dispatches API"| node_api
node_api -->|"authenticates requests"| node_auth
node_auth -->|"resolves sessions"| node_sessions
node_auth -->|"reads users"| node_db
node_sessions -->|"stores sessions"| node_db
node_trips -->|"stores trips"| node_db
node_api -->|"serves trip actions"| node_trips

click node_landing "https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/landing-flow.js"
click node_planclient "https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/plan-client.js"
click node_tripview "https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/app.js"
click node_editor "https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/editor.js"
click node_timeline "https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/timeline.js"
click node_map "https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/map.js"
click node_routeclient "https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/route.js"
click node_weather "https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/weather.js"
click node_prepview "https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/prep.js"
click node_foodview "https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/food.js"
click node_pdf "https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/export-pdf.js"
click node_catalog "https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/planner.js"
click node_schedule "https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/planner.js"
click node_routeengine "https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/planner.js"
click node_foodprep "https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/planner.js"
click node_planner "https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/planner.js"
click node_api "https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/api-router.js"
click node_server "https://github.com/seed123-psy/smart-trip-planner/blob/main/serve.js"
click node_planapi "https://github.com/seed123-psy/smart-trip-planner/blob/main/api/plan.js"
click node_amapproxy "https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/amap-proxy.js"
click node_login "https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/login.js"
click node_auth "https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/auth.js"
click node_sessions "https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/sessions.js"
click node_db "https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/db.js"
click node_trips "https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/trips.js"
click node_tripdata "https://github.com/seed123-psy/smart-trip-planner/blob/main/data/itinerary.js"
click node_poidata "https://github.com/seed123-psy/smart-trip-planner/blob/main/data/poi.js"
click node_prepdata "https://github.com/seed123-psy/smart-trip-planner/blob/main/data/prep.js"

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_landing,node_planclient,node_tripview,node_editor,node_timeline,node_map,node_routeclient,node_weather,node_prepview,node_foodview,node_pdf toneBlue
class node_catalog,node_schedule,node_routeengine,node_foodprep,node_planner toneAmber
class node_api,node_server,node_planapi,node_amapproxy toneMint
class node_login,node_auth,node_sessions,node_db,node_trips,node_tripdata,node_poidata,node_prepdata toneRose
class node_traveler,node_amap,node_deepseek toneIndigo
```

## Components

### Trip experience

- [Planning entry](https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/landing-flow.js): `scripts/landing-flow.js`
- [Plan client](https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/plan-client.js): `scripts/plan-client.js`
- [Trip view](https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/app.js): `scripts/app.js`
- [Trip editor](https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/editor.js): `scripts/editor.js`
- [Timeline](https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/timeline.js): `scripts/timeline.js`
- [Map and routes](https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/map.js): `scripts/map.js`
- [Route lookup](https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/route.js): `scripts/route.js`
- [Weather](https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/weather.js): `scripts/weather.js`
- [Preparation view](https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/prep.js): `scripts/prep.js`
- [Food view](https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/food.js): `scripts/food.js`
- [PDF export](https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/export-pdf.js): `scripts/export-pdf.js`

### Planning workflow

- [Place discovery](https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/planner.js): `tools/planner.js`
- [Itinerary scheduling](https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/planner.js): `tools/planner.js`
- [Route and checks](https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/planner.js): `tools/planner.js`
- [Food and prep agents](https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/planner.js): `tools/planner.js`
- [Planning orchestrator](https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/planner.js): `tools/planner.js`

### API and integrations

- [API routing](https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/api-router.js): `tools/api-router.js`
- [Local server](https://github.com/seed123-psy/smart-trip-planner/blob/main/serve.js): `serve.js`
- [Plan endpoint](https://github.com/seed123-psy/smart-trip-planner/blob/main/api/plan.js): `api/plan.js`
- [Amap proxy](https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/amap-proxy.js): `tools/amap-proxy.js`

### Accounts and data

- [Login and account](https://github.com/seed123-psy/smart-trip-planner/blob/main/scripts/login.js): `scripts/login.js`
- [Authentication](https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/auth.js): `tools/auth.js`
- [Sessions](https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/sessions.js): `tools/sessions.js`
- [MySQL database](https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/db.js): `tools/db.js`
- [Saved trips](https://github.com/seed123-psy/smart-trip-planner/blob/main/tools/trips.js): `tools/trips.js`
- [Example trip data](https://github.com/seed123-psy/smart-trip-planner/blob/main/data/itinerary.js): `data/itinerary.js`
- [Place data](https://github.com/seed123-psy/smart-trip-planner/blob/main/data/poi.js): `data/poi.js`
- [Preparation data](https://github.com/seed123-psy/smart-trip-planner/blob/main/data/prep.js): `data/prep.js`

### Other components

- **Traveler**
- **Amap services**
- **DeepSeek**

## Connections

- Traveler → Planning entry: enters request (evidence: `README.md`)
- Planning entry → Plan client: submits plan (evidence: `README.md`)
- Plan client → Plan endpoint: requests plan (evidence: `scripts/plan-client.js`)
- Plan endpoint → Planning orchestrator: runs planning (evidence: `api/plan.js`)
- Planning orchestrator → Place discovery: searches places (evidence: `README.md`)
- Place discovery → Amap services: queries places (evidence: `README.md`)
- Planning orchestrator → Itinerary scheduling: selects and schedules (evidence: `README.md`)
- Planning orchestrator → DeepSeek: calls model (evidence: `tools/planner.js`)
- Planning orchestrator → Route and checks: checks and repairs (evidence: `README.md`)
- Route and checks → Amap services: calculates routes (evidence: `README.md`)
- Planning orchestrator → Food and prep agents: runs final agents (evidence: `README.md`)
- Plan endpoint → Saved trips: saves result (evidence: `api/plan.js`)
- Plan endpoint → Plan client: streams result (evidence: `api/plan.js`)
- Plan client → Trip view: opens itinerary (evidence: `README.md`)
- Trip view → Timeline: renders days (evidence: `README.md`)
- Trip view → Map and routes: shows map (evidence: `README.md`)
- Map and routes → Route lookup: loads road routes
- Route lookup → Local server: requests routing (evidence: `README.md`)
- Local server → Amap proxy: forwards requests (evidence: `serve.js`)
- Amap proxy → Amap services: proxies requests (evidence: `tools/amap-proxy.js`)
- Trip view → Weather: shows forecast (evidence: `README.md`)
- Trip view → Trip editor: edits itinerary (evidence: `README.md`)
- Trip view → Preparation view: opens preparation (evidence: `README.md`)
- Trip view → Food view: shows food (evidence: `README.md`)
- Trip view → PDF export: exports PDF (evidence: `README.md`)
- Example trip data → Trip view: provides example (evidence: `README.md`)
- Place data → Planning orchestrator: supplements places
- Preparation data → Preparation view: provides guidance (evidence: `README.md`)
- Traveler → Login and account: signs in (evidence: `README.md`)
- Login and account → API routing: uses account APIs (evidence: `README.md`)
- Local server → API routing: dispatches API (evidence: `serve.js`)
- API routing → Authentication: authenticates requests (evidence: `tools/api-router.js`)
- Authentication → Sessions: resolves sessions (evidence: `tools/auth.js`)
- Authentication → MySQL database: reads users (evidence: `tools/auth.js`)
- Sessions → MySQL database: stores sessions (evidence: `tools/sessions.js`)
- Saved trips → MySQL database: stores trips (evidence: `tools/trips.js`)
- API routing → Saved trips: serves trip actions (evidence: `tools/api-router.js`)