# tiammomo/moyuan-travel-agent architecture

> Architecture diagram of the GitHub repository tiammomo/moyuan-travel-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tiammomo/moyuan-travel-agent
- Repository: https://github.com/tiammomo/moyuan-travel-agent

## Overview

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: [`web/moyuan_web/routes`](https://github.com/tiammomo/moyuan-travel-agent/tree/main/web/moyuan_web/routes) (API Routes), [`web/moyuan_web/services/chat_service.py`](https://github.com/tiammomo/moyuan-travel-agent/blob/main/web/moyuan_web/services/chat_service.py) (Chat Service), [`agent/travel_agent/runtime/agent_runtime.py`](https://github.com/tiammomo/moyuan-travel-agent/blob/main/agent/travel_agent/runtime/agent_runtime.py) (Agent Runtime), [`frontend/src/services/api`](https://github.com/tiammomo/moyuan-travel-agent/tree/main/frontend/src/services/api) (API Clients)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_shell["App Shell<br/>Next.js shell"]
  node_chat_area["Chat Area<br/>conversation UI"]
  node_travel_toolkit["Plan Toolkit<br/>artifact UI"]
  node_city_explorer["City Explorer<br/>decision funnel UI"]
  node_frontend_api["API Clients<br/>frontend adapters"]
end

subgraph group_backend["Backend"]
  node_backend_entry["Web App<br/>FastAPI app<br/>[main.py]"]
  node_api_routes["API Routes<br/>route layer"]
  node_chat_service["Chat Service<br/>stream orchestration<br/>[chat_service.py]"]
  node_session_service["Session Service<br/>session state"]
  node_artifact_service["Artifact Service<br/>artifact persistence"]
  node_city_map_services["City + Map<br/>domain services<br/>[city_service.py]"]
  node_storage_repo["Storage Layer<br/>repository/storage<br/>[session_storage.py]"]
end

subgraph group_agent["Agent Runtime"]
  node_agent_runtime["Agent Runtime<br/>runtime core<br/>[agent_runtime.py]"]
  node_agent_contracts["Agent Contracts<br/>typed schemas"]
  node_agent_bridge["Legacy Bridge<br/>compat layer<br/>[legacy_bridge.py]"]
  node_agent_supervisor["Supervisor<br/>orchestration graph"]
  node_agent_subagents["Subagents<br/>specialized roles"]
  node_agent_tools["Tools<br/>travel integrations"]
end

subgraph group_ops["Ops"]
  node_observability["Observability<br/>metrics+dashboards"]
end

subgraph group_governance["Guardrails"]
  node_guardrails["Guardrails<br/>quality scripts"]
end

node_frontend_shell -->|"hosts"| node_chat_area
node_frontend_shell -->|"hosts"| node_travel_toolkit
node_frontend_shell -->|"hosts"| node_city_explorer
node_chat_area -->|"streams"| node_frontend_api
node_travel_toolkit -->|"hydrates"| node_frontend_api
node_city_explorer -->|"queries"| node_frontend_api
node_frontend_api -->|"calls"| node_api_routes
node_backend_entry -->|"mounts"| node_api_routes
node_api_routes -->|"delegates"| node_chat_service
node_api_routes -->|"delegates"| node_session_service
node_api_routes -->|"delegates"| node_artifact_service
node_api_routes -->|"delegates"| node_city_map_services
node_chat_service -->|"invokes"| node_agent_runtime
node_chat_service -->|"persists"| node_storage_repo
node_session_service -->|"reads/writes"| node_storage_repo
node_artifact_service -->|"reads/writes"| node_storage_repo
node_city_map_services -->|"uses"| node_agent_tools
node_agent_runtime -->|"speaks"| node_agent_contracts
node_agent_runtime -->|"orchestrates"| node_agent_supervisor
node_agent_supervisor -->|"dispatches"| node_agent_subagents
node_agent_supervisor -->|"calls"| node_agent_tools
node_agent_bridge -->|"adapts"| node_agent_runtime
node_chat_service -->|"emits"| node_observability
node_backend_entry -->|"exposes"| node_observability
node_guardrails -->|"validates"| node_agent_contracts
node_guardrails -->|"replays"| node_chat_service
node_guardrails -->|"checks"| node_observability

click node_frontend_shell "https://github.com/tiammomo/moyuan-travel-agent/tree/main/frontend/src/app"
click node_chat_area "https://github.com/tiammomo/moyuan-travel-agent/tree/main/frontend/src/components/chat-area"
click node_travel_toolkit "https://github.com/tiammomo/moyuan-travel-agent/tree/main/frontend/src/components/travel-plan-toolkit"
click node_city_explorer "https://github.com/tiammomo/moyuan-travel-agent/tree/main/frontend/src/components/city-explorer"
click node_frontend_api "https://github.com/tiammomo/moyuan-travel-agent/tree/main/frontend/src/services/api"
click node_backend_entry "https://github.com/tiammomo/moyuan-travel-agent/blob/main/web/moyuan_web/main.py"
click node_api_routes "https://github.com/tiammomo/moyuan-travel-agent/tree/main/web/moyuan_web/routes"
click node_chat_service "https://github.com/tiammomo/moyuan-travel-agent/blob/main/web/moyuan_web/services/chat_service.py"
click node_session_service "https://github.com/tiammomo/moyuan-travel-agent/tree/main/web/moyuan_web/services/session"
click node_artifact_service "https://github.com/tiammomo/moyuan-travel-agent/blob/main/web/moyuan_web/services/artifact_service.py"
click node_city_map_services "https://github.com/tiammomo/moyuan-travel-agent/blob/main/web/moyuan_web/services/city_service.py"
click node_storage_repo "https://github.com/tiammomo/moyuan-travel-agent/blob/main/web/moyuan_web/storage/session_storage.py"
click node_agent_runtime "https://github.com/tiammomo/moyuan-travel-agent/blob/main/agent/travel_agent/runtime/agent_runtime.py"
click node_agent_contracts "https://github.com/tiammomo/moyuan-travel-agent/tree/main/agent/travel_agent/contracts"
click node_agent_bridge "https://github.com/tiammomo/moyuan-travel-agent/blob/main/agent/travel_agent/runtime/legacy_bridge.py"
click node_agent_supervisor "https://github.com/tiammomo/moyuan-travel-agent/tree/main/agent/travel_agent/supervisor"
click node_agent_subagents "https://github.com/tiammomo/moyuan-travel-agent/tree/main/agent/travel_agent/subagents"
click node_agent_tools "https://github.com/tiammomo/moyuan-travel-agent/tree/main/agent/travel_agent/tools"
click node_observability "https://github.com/tiammomo/moyuan-travel-agent/tree/main/ops/observability"
click node_guardrails "https://github.com/tiammomo/moyuan-travel-agent/tree/main/scripts"

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_frontend_shell,node_chat_area,node_travel_toolkit,node_city_explorer,node_frontend_api toneBlue
class node_backend_entry,node_api_routes,node_chat_service,node_session_service,node_artifact_service,node_city_map_services,node_storage_repo toneAmber
class node_agent_runtime,node_agent_contracts,node_agent_bridge,node_agent_supervisor,node_agent_subagents,node_agent_tools toneMint
class node_observability toneRose
class node_guardrails toneIndigo
```

## Components

### Frontend

Next.js/React app with chat, travel planning, and city exploration views.

- [App Shell](https://github.com/tiammomo/moyuan-travel-agent/tree/main/frontend/src/app): Next.js shell · Thin app wrapper for layout, context, and top-level navigation. · `frontend/src/app`
- [Chat Area](https://github.com/tiammomo/moyuan-travel-agent/tree/main/frontend/src/components/chat-area): conversation UI · Conversational planning surface that streams runtime state and replayable messages. · `frontend/src/components/chat-area`
- [Plan Toolkit](https://github.com/tiammomo/moyuan-travel-agent/tree/main/frontend/src/components/travel-plan-toolkit): artifact UI · Structured itinerary, budget, conflict, reminder, and compare views over shared delivery artifacts. · `frontend/src/components/travel-plan-toolkit`
- [City Explorer](https://github.com/tiammomo/moyuan-travel-agent/tree/main/frontend/src/components/city-explorer): decision funnel UI · Browse, filter, shortlist, and compare cities before trip generation. · `frontend/src/components/city-explorer`
- [API Clients](https://github.com/tiammomo/moyuan-travel-agent/tree/main/frontend/src/services/api): frontend adapters · 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](https://github.com/tiammomo/moyuan-travel-agent/blob/main/web/moyuan_web/main.py): FastAPI app · Backend bootstrap and application wiring for the HTTP boundary. · `web/moyuan_web/main.py`
- [API Routes](https://github.com/tiammomo/moyuan-travel-agent/tree/main/web/moyuan_web/routes): route layer · Chat, session, artifact, city, map, share, model, and health endpoints. · `web/moyuan_web/routes`
- [Chat Service](https://github.com/tiammomo/moyuan-travel-agent/blob/main/web/moyuan_web/services/chat_service.py): stream orchestration · Main runtime path for SSE chat streaming, diagnostics, history sync, and finalization. · `web/moyuan_web/services/chat_service.py`
- [Session Service](https://github.com/tiammomo/moyuan-travel-agent/tree/main/web/moyuan_web/services/session): session state · Session lifecycle, hydration, persistence, and memory sync coordination. · `web/moyuan_web/services/session`
- [Artifact Service](https://github.com/tiammomo/moyuan-travel-agent/blob/main/web/moyuan_web/services/artifact_service.py): artifact persistence · Materializes structured travel artifacts and shareable snapshots. · `web/moyuan_web/services/artifact_service.py`
- [City + Map](https://github.com/tiammomo/moyuan-travel-agent/blob/main/web/moyuan_web/services/city_service.py): domain services · City catalog/query plus AMap-backed route preview and geospatial refinement. · `web/moyuan_web/services/city_service.py`
- [Storage Layer](https://github.com/tiammomo/moyuan-travel-agent/blob/main/web/moyuan_web/storage/session_storage.py): repository/storage · 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](https://github.com/tiammomo/moyuan-travel-agent/blob/main/agent/travel_agent/runtime/agent_runtime.py): runtime core · Supervisor-driven agent execution with direct, react, and plan modes. · `agent/travel_agent/runtime/agent_runtime.py`
- [Agent Contracts](https://github.com/tiammomo/moyuan-travel-agent/tree/main/agent/travel_agent/contracts): typed schemas · Request, event, receipt, and skill contract definitions for the runtime boundary. · `agent/travel_agent/contracts`
- [Legacy Bridge](https://github.com/tiammomo/moyuan-travel-agent/blob/main/agent/travel_agent/runtime/legacy_bridge.py): compat layer · Compatibility path from legacy LangGraph runtime to the narrower runtime API. · `agent/travel_agent/runtime/legacy_bridge.py`
- [Supervisor](https://github.com/tiammomo/moyuan-travel-agent/tree/main/agent/travel_agent/supervisor): orchestration graph · Supervisor graph and node logic that coordinates execution and subagent handoffs. · `agent/travel_agent/supervisor`
- [Subagents](https://github.com/tiammomo/moyuan-travel-agent/tree/main/agent/travel_agent/subagents): specialized roles · Planning, research, budget, and verification roles used during trip reasoning. · `agent/travel_agent/subagents`
- [Tools](https://github.com/tiammomo/moyuan-travel-agent/tree/main/agent/travel_agent/tools): travel integrations · Travel API, route/map helpers, and external capability adapters. · `agent/travel_agent/tools`

### Ops

Observability assets and deployment/runtime support.

- [Observability](https://github.com/tiammomo/moyuan-travel-agent/tree/main/ops/observability): metrics+dashboards · Health, readiness, metrics, Prometheus, and Grafana assets for operations. · `ops/observability`

### Guardrails

Scripts and quality gates used to validate contracts, runtime, and releases.

- [Guardrails](https://github.com/tiammomo/moyuan-travel-agent/tree/main/scripts): quality scripts · Benchmarking, replay, snapshot export, audits, and release evidence scripts. · `scripts`

## Connections

- 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.
