How arpan65/tripai-multi-agent-ai-travel-planner works
1. High-level shape
- TripAI is a two-tier application: a React/Vite frontend talks to a FastAPI backend, and the backend runs a four-phase Claude-based agent pipeline to produce a structured travel dossier.
- The main data flow is: user request → streamed backend orchestration → live web/tool lookup → budget synthesis → final JSON result → UI rendering.
2. Frontend boundary
- The frontend/src app is responsible for collecting the trip request, opening an SSE connection, and rendering the streaming phase updates and final trip result.
- App.jsx is the main UI controller; TripResult.jsx displays the final dossier, including tiered budget breakdowns and export/view logic.
- The frontend is a presentation layer only; it does not own travel logic or persistence.
3. Backend API boundary
- app/api.py is the primary backend entrypoint and session manager.
- It exposes /health, /api/chat, /api/chat/stream, /api/latest-run, and /api/reset.
- /api/chat/stream is the key integration point: it emits server-sent events as each agent phase completes, rather than waiting for a single blocking response.
4. Agent orchestration subsystem
- app/agent/pipeline.py contains the central TravelAgent orchestrator that coordinates the four phases and manages MCP server lifecycle.
- runner.py implements the single-role agent loop for each phase, while executor.py handles tool dispatch and recording.
- prompts.py holds the role-specific system prompts; config.py defines model limits and MCP configuration; mcp_agent.py is a compatibility shim.
- This layer is where the core business logic lives: planning, price discovery, arithmetic, and final dossier assembly.
5. Four-phase execution model
- Phase 1, Planner: converts the user’s natural-language trip request into a strict JSON manifest.
- Phase 2, Pricer: uses browser automation to perform live searches for transport, lodging, and activities.
- Phase 3, Budget: uses calculator tooling to derive economy, mid-range, and comfort budgets.
- Phase 4, Aggregator: merges all outputs into a validated final JSON payload for the client.
- This phased design is the key architectural boundary for diagramming the system.
6. Tooling and external agent services
- The backend does not scrape directly; it uses MCP tools.
- @playwright/mcp provides browser-based research against live websites and Google search results.
- calculator-mcp-server provides arithmetic so budget math is performed through tool calls rather than model “mental math.”
- These tools are invoked only by the agent pipeline, not by the frontend or persistence layer.
7. Persistence and observability
- app/db.py abstracts storage across two backends: SQLite for local development and DynamoDB for production.
- Persisted tables track runs, agent calls, and tool calls, primarily for replay, observability, and test mode.
- The README indicates writes are best-effort and wrapped so storage failures do not break the user request path.
8. Session and streaming behavior
- The backend maintains bounded session state with TTL-based eviction and a maximum concurrent session count.
- SSE keepalive messages are used to keep long-running browser searches alive through proxies and CloudFront timeouts.
- This makes streaming an architectural concern, not just a transport detail, because the agent pipeline can outlive a short HTTP request window.
9. Local runtime and containerization
- The project uses a Dockerized Python backend plus a separate frontend dev server for local development, or a combined container for production-style runs.
- Dockerfile, docker-compose.yml, and docker-entrypoint.sh manage the runtime image, Chromium installation for Playwright MCP, and service startup.
- The browser volume is persisted so Chromium does not need to be reinstalled on every container rebuild.
10. Cloud deployment topology
- infra/ defines AWS CDK infrastructure: EC2 runs the container, ECR stores the image, DynamoDB stores run data, and CloudFront fronts the service.
- The architecture is optimized for a single backend instance rather than horizontal app scaling.
- Deployment scripts rebuild the image, push to ECR, and restart the EC2-hosted service; destruction keeps DynamoDB tables unless explicitly removed.
11. Data flow summary for a diagram
- User input enters the React app, which posts to FastAPI.
- FastAPI starts or resumes a session, then streams phase events while the pipeline executes.
- The agent pipeline calls external tools through MCP, records optional telemetry in SQLite/DynamoDB, and returns a final JSON dossier.
- The frontend consumes the stream and renders progressive status plus the final trip recommendation.
12. Key architectural boundaries
- UI vs API: React handles interaction and display; FastAPI handles orchestration.
- Orchestration vs tools: agent code decides what to do; MCP servers perform browser/search and arithmetic work.
- Runtime vs storage: persistence is observational and non-blocking, not part of the core success path.
- Local vs cloud: SQLite and local Chromium are development conveniences; DynamoDB and EC2/CloudFront represent production deployment.
Main entry points: api.py API server · pipeline.py Travel agent · executor.py Tool executor · App.jsx Trip form
Components 23
Frontend
React/Vite UI that collects trip requests and renders streamed updates and final dossiers.
- Main UI · Bootstraps the browser app and mounts the main interface.
frontend/src/main.jsx - Trip form · Collects trip input, opens the chat/stream session, and coordinates UI state.
frontend/src/App.jsx - Trip result · Displays the final structured dossier, budget tiers, and export/view actions.
frontend/src/TripResult.jsx
API Layer
FastAPI entrypoint, session management, and SSE transport.
- API server · Defines health, chat, stream, latest-run, and reset endpoints.
app/api.py - App startup · Process entrypoint that starts the backend service.
app/main.py - Session state · Bounds active sessions, TTL eviction, and streaming lifecycle state.
app/api.py
Agent Pipeline
Four-phase orchestration, prompts, execution, and tool dispatch.
- Travel agent · Coordinates the four phases and manages MCP server lifecycle.
app/agent/pipeline.py - Phase runner · Runs each role-specific phase as a single-role loop.
app/agent/runner.py - Tool executor · Invokes tools, records calls, and bridges model actions to external services.
app/agent/executor.py - Prompts · Holds phase-specific instructions for planning, pricing, budgeting, and aggregation.
app/agent/prompts.py - Agent config · Defines model limits and MCP-related configuration for the pipeline.
app/agent/config.py - MCP shim · Compatibility wrapper used by the agent runtime.
app/agent/mcp_agent.py
Persistence
Best-effort run and tool telemetry storage across local and cloud backends.
- Run store · Abstracts best-effort persistence for runs, calls, and replay metadata.
app/db.py - Core config · Shared backend configuration used by the application runtime.
app/core/config.py - SQLite · Local-development persistence backend.
- DynamoDB · Production persistence backend for run and tool telemetry.
Runtime & Infra
Container runtime, deployment scripts, and AWS infrastructure for production hosting.
- Container image · Builds the backend runtime image and installs browser dependencies.
Dockerfile - Compose run · Local container orchestration for backend and supporting services.
docker-compose.yml - Deploy script · Automates image rebuild, push, and service restart for hosted runs.
deploy.sh - CDK entry · AWS CDK app entrypoint for cloud deployment.
infra/bin/infra.ts - Infra stack · Defines EC2, ECR, DynamoDB, and CloudFront deployment resources.
infra/lib/infra-stack.ts
Other components
- Browser MCP · Browser-based research over live sites and search results.
- Calc MCP · Arithmetic service used for budget calculations.
Connections 23
- Main UI → Trip form: mounts · Bootstraps the main application shell.
- Trip form → API server: chat/stream · Sends trip requests and opens the SSE connection.
- App startup → API server: starts · Launches the FastAPI service process.
- API server → Session state: tracks · Creates and resumes bounded session state.
- API server → Travel agent: orchestrates · Hands work to the multi-phase travel pipeline.
- Travel agent → Phase runner: runs phases · Executes planner, pricer, budget, and aggregator roles.
- Travel agent → Prompts: loads prompts · Uses role-specific instructions for each phase.
- Travel agent → Agent config: applies limits · Reads model and MCP configuration.
- Travel agent → MCP shim: compatibility · Uses the MCP wrapper when initializing tool services.
- Phase runner → Tool executor: dispatches · Sends tool calls through the executor.
- Tool executor → Browser MCP: browser research · Performs live web lookup and site inspection.
- Tool executor → Calc MCP: math · Performs budget arithmetic through tool calls.
- Tool executor → Run store: records · Writes optional telemetry and replay data.
- Run store → SQLite: local · Uses SQLite in development environments.
- Run store → DynamoDB: production · Uses DynamoDB in hosted deployments.
- API server → Run store: observes · Stores request and run metadata without blocking success path.
- Trip form → Trip result: renders · Displays the final dossier and budget tiers.
- API server → Trip form: streams events · Emits phase updates and final payloads over SSE.
- Container image → Compose run: packages · Builds the container used by local compose runs.
- Compose run → App startup: runs backend · Starts the containerized backend service locally.
- Deploy script → Container image: builds · Rebuilds the runtime image for release.
- CDK entry → Infra stack: defines · Instantiates the AWS deployment stack.
- Infra stack → DynamoDB: provisions · Creates the cloud persistence backend.