# evanpanlabs-design/riddle_trip_planner architecture

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

- Interactive diagram: https://gitdiagram.com/evanpanlabs-design/riddle_trip_planner
- Repository: https://github.com/evanpanlabs-design/riddle_trip_planner

## Overview

Riddle is a travel-planning copilot: a user describes a trip, the agent generates plans and tool calls, Jev gates changes, and accepted plans are validated and stored as an editable event-tree itinerary. The README documents additional checklist, pending-question, audit/undo, map, and operations capabilities. Some wiring is based on the README because the sampled excerpts are partial; uncertain links are omitted.

Main entry points: [`APP/src/agent.ts`](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/agent.ts) (Agent loop), [`APP/src/jev/client.ts`](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/jev/client.ts) (Jev client), [`APP/src/server.ts`](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/server.ts) (Project server), [`APP/src/scheduler/scheduler.ts`](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/scheduler/scheduler.ts) (Pending queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation and decisions"]
  node_agent["Agent loop<br/>[agent.ts]"]
  node_jevclient["Jev client<br/>[client.ts]"]
  node_questions["Judgment questions<br/>[questions.ts]"]
  node_fallback["LLM judge fallback<br/>[llm-judge.ts]"]
  node_scheduler[("Pending queue<br/>[scheduler.ts]")]
end

subgraph group_planning["Planning and trip state"]
  node_tripstore[("Trip event store<br/>[trip-store.ts]")]
  node_eventmodel["Event-tree model<br/>[event-v2.ts]"]
  node_edits["Co-editing operations<br/>[edits.ts]"]
  node_eventdocs[("Event wiki<br/>[event-docs.ts]")]
end

subgraph group_geography["Geography and validation"]
  node_geo["Geographic checks<br/>[geo-checks.ts]"]
  node_amap["AMap tools<br/>[amap.ts]"]
  node_baidu["Baidu transit<br/>[baidu.ts]"]
  node_osm["OSM boundaries<br/>[osm-aoi.ts]"]
end

subgraph group_operations["Projects and settings"]
  node_server["Project server<br/>[server.ts]"]
  node_settings[("Settings<br/>[settings.ts]")]
end

node_traveler(("Traveler"))
node_llm["Generation model"]
node_jevservice["Jev service"]
node_mapservice["Map services"]
node_baiduservice["Baidu Maps"]
node_osmservice["OpenStreetMap"]

node_traveler -->|"sends trip input"| node_server
node_server -->|"prompts agent"| node_agent
node_agent -->|"generates drafts"| node_llm
node_agent -->|"requests judgments"| node_jevclient
node_jevclient -->|"builds questions"| node_questions
node_jevclient -->|"submits judgments"| node_jevservice
node_jevclient -.->|"can fall back"| node_fallback
node_agent -->|"queues blocked actions"| node_scheduler
node_scheduler -->|"checks pending replies"| node_jevclient
node_agent -->|"assembles and validates"| node_eventmodel
node_agent -->|"applies trip changes"| node_tripstore
node_agent -->|"dispatches edits"| node_edits
node_agent -->|"reads and writes notes"| node_eventdocs
node_agent -->|"validates geography"| node_geo
node_agent -->|"searches places"| node_amap
node_agent -->|"requests intercity routes"| node_baidu
node_amap -->|"queries places"| node_mapservice
node_baidu -->|"queries transit"| node_baiduservice
node_geo -.->|"requests boundaries"| node_osm
node_osm -->|"fetches boundaries"| node_osmservice
node_server -->|"reads and saves"| node_settings
node_agent -->|"resolves model config"| node_settings

click node_server "https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/server.ts"
click node_agent "https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/agent.ts"
click node_jevclient "https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/jev/client.ts"
click node_questions "https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/jev/questions.ts"
click node_fallback "https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/jev/llm-judge.ts"
click node_scheduler "https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/scheduler/scheduler.ts"
click node_tripstore "https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/memory/trip-store.ts"
click node_eventmodel "https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/memory/event-v2.ts"
click node_edits "https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/memory/edits.ts"
click node_eventdocs "https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/memory/event-docs.ts"
click node_geo "https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/memory/geo-checks.ts"
click node_amap "https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/tools/amap.ts"
click node_baidu "https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/tools/baidu.ts"
click node_osm "https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/tools/osm-aoi.ts"
click node_settings "https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/settings.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_agent,node_jevclient,node_questions,node_fallback,node_scheduler toneBlue
class node_tripstore,node_eventmodel,node_edits,node_eventdocs toneAmber
class node_geo,node_amap,node_baidu,node_osm toneMint
class node_server,node_settings toneRose
class node_traveler,node_llm,node_jevservice,node_mapservice,node_baiduservice,node_osmservice toneIndigo
```

## Components

### Conversation and decisions

- [Agent loop](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/agent.ts): `APP/src/agent.ts`
- [Jev client](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/jev/client.ts): `APP/src/jev/client.ts`
- [Judgment questions](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/jev/questions.ts): `APP/src/jev/questions.ts`
- [LLM judge fallback](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/jev/llm-judge.ts): `APP/src/jev/llm-judge.ts`
- [Pending queue](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/scheduler/scheduler.ts): `APP/src/scheduler/scheduler.ts`

### Planning and trip state

- [Trip event store](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/memory/trip-store.ts): `APP/src/memory/trip-store.ts`
- [Event-tree model](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/memory/event-v2.ts): `APP/src/memory/event-v2.ts`
- [Co-editing operations](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/memory/edits.ts): `APP/src/memory/edits.ts`
- [Event wiki](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/memory/event-docs.ts): `APP/src/memory/event-docs.ts`

### Geography and validation

- [Geographic checks](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/memory/geo-checks.ts): `APP/src/memory/geo-checks.ts`
- [AMap tools](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/tools/amap.ts): `APP/src/tools/amap.ts`
- [Baidu transit](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/tools/baidu.ts): `APP/src/tools/baidu.ts`
- [OSM boundaries](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/tools/osm-aoi.ts): `APP/src/tools/osm-aoi.ts`

### Projects and settings

- [Project server](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/server.ts): `APP/src/server.ts`
- [Settings](https://github.com/evanpanlabs-design/riddle_trip_planner/blob/main/APP/src/settings.ts): `APP/src/settings.ts`

### Other components

- **Traveler**
- **Generation model**
- **Jev service**
- **Map services**
- **Baidu Maps**
- **OpenStreetMap**

## Connections

- Traveler → Project server: sends trip input
- Project server → Agent loop: prompts agent
- Agent loop → Generation model: generates drafts
- Agent loop → Jev client: requests judgments
- Jev client → Judgment questions: builds questions
- Jev client → Jev service: submits judgments
- Jev client → LLM judge fallback: can fall back
- Agent loop → Pending queue: queues blocked actions
- Pending queue → Jev client: checks pending replies
- Agent loop → Event-tree model: assembles and validates
- Agent loop → Trip event store: applies trip changes
- Agent loop → Co-editing operations: dispatches edits
- Agent loop → Event wiki: reads and writes notes
- Agent loop → Geographic checks: validates geography
- Agent loop → AMap tools: searches places
- Agent loop → Baidu transit: requests intercity routes
- AMap tools → Map services: queries places
- Baidu transit → Baidu Maps: queries transit
- Geographic checks → OSM boundaries: requests boundaries
- OSM boundaries → OpenStreetMap: fetches boundaries
- Project server → Settings: reads and saves
- Agent loop → Settings: resolves model config