How tiammomo/moyuan-travel-agent works
1. This is a three-tier monorepo: a Next.js/React frontend, a FastAPI backend, and a Python agent runtime package. The user-facing product is a travel decision assistant, not just a chat app, so the architecture centers on structured travel artifacts, session persistence, and comparison/replay flows.
2. The frontend lives in frontend/ and is built around two main workspaces: ChatArea for conversational planning and TravelPlanToolkit/CityExplorer for structured decision support. The app shell is thin; most behavior is pushed into feature folders like chat-area/, travel-plan-toolkit/, and city-explorer/, which act as view adapters over API data and artifact contracts.
3. The main user flow is: user input in the chat UI → POST /api/chat/stream → backend streaming SSE events → frontend stream parser and runtime state hooks → rendered assistant messages plus diagnostics/artifacts. The frontend does not just display text; it reconstructs runtime state, execution receipts, and artifact history for replay, hydration, compare, and share views.
4. The backend under web/moyuan_web/ is the HTTP boundary. It exposes routes for chat, session management, artifacts, city data, maps, share links, model info, and health/metrics. Internally it is split into routes, services, repositories, storage, and bootstrap/dependency wiring, so the diagram should show a clear API layer over service orchestration and persistent state.
5. The chat backend is the most important runtime path. chat_service.py and its chat submodules coordinate SSE streaming, diagnostics, history sync, plan preview, and finalization. This layer serializes a typed stream contract, emits request/trace IDs, and persists enough metadata to let the frontend restore a session without re-running the whole conversation.
6. The agent subsystem is in agent/travel_agent/ and is intentionally separated from the web layer. Its core architecture is a supervisor-driven runtime that can execute different modes (direct, react, plan), call tools, invoke subagents, and emit execution receipts. The codebase is actively moving from a legacy LangGraph runtime toward a narrower AgentRuntime plus typed bridge/contracts boundary.
7. Inside the agent package, the key seams are contracts, runtime bridge, graph, memory, subagents, skills, and tools. contracts/ defines request/event/receipt schemas; runtime/ adapts the stable runtime API; graph/legacy_runtime.py and runtime/legacy_bridge.py preserve compatibility; subagents/ encapsulate planning, research, budget, and verification roles; skills/registry.py and contracts/skills.py formalize skill selection; tools/ provides travel API and route/map capability.
8. Memory and artifacts are first-class architectural concerns. The backend persists session state and artifact history; the agent has memory conflict resolution and checkpointer support; the frontend prefers artifact-first hydration and compare paths. This means the system is not purely ephemeral SSE chat: it has durable state for latest artifact, historical artifact snapshots, and share/replay recovery.
9. The structured travel-planning product is built around artifact contracts. The agent produces itinerary-like outputs, execution receipts, confidence/risk metadata, budget summaries, conflicts, reminders, and checklist content. The frontend toolkit consumes a shared delivery bundle so that overview cards, itinerary day cards, budget panels, comparison tables, share/export, and replay all derive from the same structured payload.
10. City exploration is a separate domain subsystem. The backend exposes city catalog/query services, and the frontend provides curated city cards, filters, shortlist/compare, and detail drawers. This path is designed as a decision funnel: browse cities first, then continue into trip generation with a selected city or a shortlist.
11. Map and route functionality are isolated as a service boundary. The backend has map services and an AMap client, used for route previews and travel-distance-aware reordering. In the architecture diagram, this should appear as an external geospatial/provider dependency used by trip refinement rather than by the core chat loop.
12. Persistence and operational state are handled through config, local data, and support services rather than a heavyweight database stack in the repo surface. config/ holds server and LLM settings, data/ is the runtime state area, and session/storage/repository modules abstract persistence. Share links and artifacts are materialized through backend services so they can be replayed independently of the original chat stream.
13. Observability is built into the backend and deployment layer. The API exposes health, readiness, live, and metrics endpoints; request/trace IDs are propagated; and ops/observability/ contains Prometheus and Grafana assets. CI and release workflows also validate container builds, snapshots, and runtime contracts, so ops artifacts are part of the architecture, not afterthoughts.
14. The repo has strong governance and quality boundaries that affect architecture stability. Scripts under scripts/ enforce runtime doctor checks, contract snapshots, benchmark/replay fixtures, complexity budgets, docstring audits, skills-market audits, and release evidence generation. These are part of the system’s “guardrail layer” and are important to show if you are diagramming delivery or evolution boundaries.
15. The external dependencies that materially shape the design are the LLM provider via an Anthropic-compatible MiniMax endpoint, the AMap mapping API, and the local observability stack. Everything else is mostly internal orchestration around those providers, with the frontend, backend, and agent runtime kept decoupled through typed contracts and API/SSE boundaries.
Main entry points: routes API Routes · chat_service.py Chat Service · agent_runtime.py Agent Runtime · api API Clients
Components 20
Frontend
Next.js/React app with chat, travel planning, and city exploration views.
- App Shell · Thin app wrapper for layout, context, and top-level navigation.
frontend/src/app - Chat Area · Conversational planning surface that streams runtime state and replayable messages.
frontend/src/components/chat-area - Plan Toolkit · Structured itinerary, budget, conflict, reminder, and compare views over shared delivery artifacts.
frontend/src/components/travel-plan-toolkit - City Explorer · Browse, filter, shortlist, and compare cities before trip generation.
frontend/src/components/city-explorer - API Clients · Typed clients, stream parser, delivery models, and session/history hydration helpers.
frontend/src/services/api
Backend
FastAPI HTTP boundary, services, and persistent session/artifact state.
- Web App · Backend bootstrap and application wiring for the HTTP boundary.
web/moyuan_web/main.py - API Routes · Chat, session, artifact, city, map, share, model, and health endpoints.
web/moyuan_web/routes - Chat Service · Main runtime path for SSE chat streaming, diagnostics, history sync, and finalization.
web/moyuan_web/services/chat_service.py - Session Service · Session lifecycle, hydration, persistence, and memory sync coordination.
web/moyuan_web/services/session - Artifact Service · Materializes structured travel artifacts and shareable snapshots.
web/moyuan_web/services/artifact_service.py - City + Map · City catalog/query plus AMap-backed route preview and geospatial refinement.
web/moyuan_web/services/city_service.py - Storage Layer · Session repository and local storage abstraction for durable state.
web/moyuan_web/storage/session_storage.py
Agent Runtime
Standalone Python agent package with runtime, contracts, and tool execution.
- Agent Runtime · Supervisor-driven agent execution with direct, react, and plan modes.
agent/travel_agent/runtime/agent_runtime.py - Agent Contracts · Request, event, receipt, and skill contract definitions for the runtime boundary.
agent/travel_agent/contracts - Legacy Bridge · Compatibility path from legacy LangGraph runtime to the narrower runtime API.
agent/travel_agent/runtime/legacy_bridge.py - Supervisor · Supervisor graph and node logic that coordinates execution and subagent handoffs.
agent/travel_agent/supervisor - Subagents · Planning, research, budget, and verification roles used during trip reasoning.
agent/travel_agent/subagents - Tools · Travel API, route/map helpers, and external capability adapters.
agent/travel_agent/tools
Ops
Observability assets and deployment/runtime support.
- Observability · Health, readiness, metrics, Prometheus, and Grafana assets for operations.
ops/observability
Guardrails
Scripts and quality gates used to validate contracts, runtime, and releases.
- Guardrails · Benchmarking, replay, snapshot export, audits, and release evidence scripts.
scripts
Connections 27
- App Shell → Chat Area: hosts · App shell renders the main conversation surface.
- App Shell → Plan Toolkit: hosts · App shell renders the structured planning toolkit.
- App Shell → City Explorer: hosts · App shell renders the city discovery funnel.
- Chat Area → API Clients: streams · Conversation UI consumes chat stream, session hydration, and artifact history.
- Plan Toolkit → API Clients: hydrates · Toolkit consumes shared artifact delivery and compare payloads.
- City Explorer → API Clients: queries · Explorer fetches city data, models, and share/session state.
- API Clients → API Routes: calls · Frontend clients talk to typed backend endpoints.
- Web App → API Routes: mounts · FastAPI bootstrap wires route modules into the app.
- API Routes → Chat Service: delegates · Chat endpoint delegates streaming orchestration to the chat service.
- API Routes → Session Service: delegates · Session endpoints manage lifecycle and hydration through session services.
- API Routes → Artifact Service: delegates · Artifact and share endpoints persist and materialize structured outputs.
- API Routes → City + Map: delegates · City and map endpoints expose catalog and geospatial refinement services.
- Chat Service → Agent Runtime: invokes · Chat stream execution is driven by the agent runtime.
- Chat Service → Storage Layer: persists · Chat service stores session metadata and replayable state.
- Session Service → Storage Layer: reads/writes · Session lifecycle uses repository and storage abstractions.
- Artifact Service → Storage Layer: reads/writes · Artifacts and snapshots are stored for replay and sharing.
- City + Map → Tools: uses · Route preview and map refinement depend on travel tool integrations.
- Agent Runtime → Agent Contracts: speaks · Runtime is governed by typed request, event, and receipt contracts.
- Agent Runtime → Supervisor: orchestrates · Runtime hands work to supervisor-driven execution graphs.
- Supervisor → Subagents: dispatches · Supervisor delegates to planning, research, budget, and verification roles.
- Supervisor → Tools: calls · Supervisor executes external tools and travel integrations.
- Legacy Bridge → Agent Runtime: adapts · Legacy bridge preserves compatibility while the runtime evolves.
- Chat Service → Observability: emits · Chat path propagates request/trace IDs and health/metrics signals.
- Web App → Observability: exposes · Backend exposes readiness, health, live, and metrics endpoints.
- Guardrails → Agent Contracts: validates · Scripts snapshot and audit runtime contracts and execution receipts.
- Guardrails → Chat Service: replays · Benchmarks and replay tools exercise the chat stream contract.
- Guardrails → Observability: checks · Release and runtime scripts validate observability and operational assets.