# arpan65/tripai-multi-agent-ai-travel-planner architecture

> Architecture diagram of the GitHub repository arpan65/tripai-multi-agent-ai-travel-planner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arpan65/tripai-multi-agent-ai-travel-planner
- Repository: https://github.com/arpan65/tripai-multi-agent-ai-travel-planner

## Overview

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: [`app/api.py`](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/api.py) (API server), [`app/agent/pipeline.py`](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/agent/pipeline.py) (Travel agent), [`app/agent/executor.py`](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/agent/executor.py) (Tool executor), [`frontend/src/App.jsx`](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/frontend/src/App.jsx) (Trip form)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_main["Main UI<br/>React entry<br/>[main.jsx]"]
  node_frontend_app["Trip form<br/>React controller<br/>[App.jsx]"]
  node_frontend_result["Trip result<br/>React view<br/>[TripResult.jsx]"]
end

subgraph group_api["API Layer"]
  node_api_entry["API server<br/>FastAPI app<br/>[api.py]"]
  node_api_boot["App startup<br/>ASGI boot<br/>[main.py]"]
  node_session_store[("Session state<br/>session mgr<br/>[api.py]")]
end

subgraph group_agent["Agent Pipeline"]
  node_travel_agent{{"Travel agent<br/>orchestrator<br/>[pipeline.py]"}}
  node_phase_runner["Phase runner<br/>agent loop<br/>[runner.py]"]
  node_tool_executor["Tool executor<br/>dispatch<br/>[executor.py]"]
  node_phase_prompts["Prompts<br/>[prompts.py]"]
  node_agent_config["Agent config<br/>limits/config<br/>[config.py]"]
  node_mcp_shim["MCP shim<br/>compat layer<br/>[mcp_agent.py]"]
end

subgraph group_persistence["Persistence"]
  node_run_db[("Run store<br/>storage adapter<br/>[db.py]")]
  node_core_config["Core config<br/>app config<br/>[config.py]"]
  node_sqlite_db[("SQLite<br/>local store")]
  node_dynamodb[("DynamoDB<br/>cloud store")]
end

subgraph group_delivery["Runtime & Infra"]
  node_dockerfile["Container image<br/>docker build"]
  node_compose["Compose run<br/>local runtime<br/>[docker-compose.yml]"]
  node_deploy_script["Deploy script<br/>release flow<br/>[deploy.sh]"]
  node_infra_entry["CDK entry<br/>infra entry<br/>[infra.ts]"]
  node_infra_stack{{"Infra stack<br/>aws cdk stack<br/>[infra-stack.ts]"}}
end

node_playwright_mcp["Browser MCP<br/>external tool"]
node_calculator_mcp(("Calc MCP<br/>external tool"))

node_frontend_main -->|"mounts"| node_frontend_app
node_frontend_app -->|"chat/stream"| node_api_entry
node_api_boot -->|"starts"| node_api_entry
node_api_entry -->|"tracks"| node_session_store
node_api_entry -->|"orchestrates"| node_travel_agent
node_travel_agent -->|"runs phases"| node_phase_runner
node_travel_agent -->|"loads prompts"| node_phase_prompts
node_travel_agent -->|"applies limits"| node_agent_config
node_travel_agent -.->|"compatibility"| node_mcp_shim
node_phase_runner -->|"dispatches"| node_tool_executor
node_tool_executor -->|"browser research"| node_playwright_mcp
node_tool_executor -->|"math"| node_calculator_mcp
node_tool_executor -.->|"records"| node_run_db
node_run_db -->|"local"| node_sqlite_db
node_run_db -->|"production"| node_dynamodb
node_api_entry -.->|"observes"| node_run_db
node_frontend_app -->|"renders"| node_frontend_result
node_api_entry -->|"streams events"| node_frontend_app
node_dockerfile -->|"packages"| node_compose
node_compose -->|"runs backend"| node_api_boot
node_deploy_script -->|"builds"| node_dockerfile
node_infra_entry -->|"defines"| node_infra_stack
node_infra_stack -->|"provisions"| node_dynamodb

click node_frontend_main "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/frontend/src/main.jsx"
click node_frontend_app "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/frontend/src/App.jsx"
click node_frontend_result "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/frontend/src/TripResult.jsx"
click node_api_entry "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/api.py"
click node_api_boot "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/main.py"
click node_session_store "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/api.py"
click node_travel_agent "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/agent/pipeline.py"
click node_phase_runner "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/agent/runner.py"
click node_tool_executor "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/agent/executor.py"
click node_phase_prompts "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/agent/prompts.py"
click node_agent_config "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/agent/config.py"
click node_mcp_shim "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/agent/mcp_agent.py"
click node_run_db "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/db.py"
click node_core_config "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/core/config.py"
click node_dockerfile "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/tree/main/Dockerfile"
click node_compose "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/docker-compose.yml"
click node_deploy_script "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/deploy.sh"
click node_infra_entry "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/infra/bin/infra.ts"
click node_infra_stack "https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/infra/lib/infra-stack.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_frontend_main,node_frontend_app,node_frontend_result toneBlue
class node_api_entry,node_api_boot,node_session_store toneAmber
class node_travel_agent,node_phase_runner,node_tool_executor,node_phase_prompts,node_agent_config,node_mcp_shim toneMint
class node_run_db,node_core_config,node_sqlite_db,node_dynamodb toneRose
class node_dockerfile,node_compose,node_deploy_script,node_infra_entry,node_infra_stack toneIndigo
class node_playwright_mcp,node_calculator_mcp toneNeutral
```

## Components

### Frontend

React/Vite UI that collects trip requests and renders streamed updates and final dossiers.

- [Main UI](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/frontend/src/main.jsx): React entry · Bootstraps the browser app and mounts the main interface. · `frontend/src/main.jsx`
- [Trip form](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/frontend/src/App.jsx): React controller · Collects trip input, opens the chat/stream session, and coordinates UI state. · `frontend/src/App.jsx`
- [Trip result](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/frontend/src/TripResult.jsx): React view · 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](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/api.py): FastAPI app · Defines health, chat, stream, latest-run, and reset endpoints. · `app/api.py`
- [App startup](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/main.py): ASGI boot · Process entrypoint that starts the backend service. · `app/main.py`
- [Session state](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/api.py): session mgr · Bounds active sessions, TTL eviction, and streaming lifecycle state. · `app/api.py`

### Agent Pipeline

Four-phase orchestration, prompts, execution, and tool dispatch.

- [Travel agent](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/agent/pipeline.py): orchestrator · Coordinates the four phases and manages MCP server lifecycle. · `app/agent/pipeline.py`
- [Phase runner](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/agent/runner.py): agent loop · Runs each role-specific phase as a single-role loop. · `app/agent/runner.py`
- [Tool executor](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/agent/executor.py): dispatch · Invokes tools, records calls, and bridges model actions to external services. · `app/agent/executor.py`
- [Prompts](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/agent/prompts.py): system prompts · Holds phase-specific instructions for planning, pricing, budgeting, and aggregation. · `app/agent/prompts.py`
- [Agent config](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/agent/config.py): limits/config · Defines model limits and MCP-related configuration for the pipeline. · `app/agent/config.py`
- [MCP shim](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/agent/mcp_agent.py): compat layer · 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](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/db.py): storage adapter · Abstracts best-effort persistence for runs, calls, and replay metadata. · `app/db.py`
- [Core config](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/app/core/config.py): app config · Shared backend configuration used by the application runtime. · `app/core/config.py`
- **SQLite**: local store · Local-development persistence backend.
- **DynamoDB**: cloud store · Production persistence backend for run and tool telemetry.

### Runtime & Infra

Container runtime, deployment scripts, and AWS infrastructure for production hosting.

- [Container image](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/tree/main/Dockerfile): docker build · Builds the backend runtime image and installs browser dependencies. · `Dockerfile`
- [Compose run](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/docker-compose.yml): local runtime · Local container orchestration for backend and supporting services. · `docker-compose.yml`
- [Deploy script](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/deploy.sh): release flow · Automates image rebuild, push, and service restart for hosted runs. · `deploy.sh`
- [CDK entry](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/infra/bin/infra.ts): infra entry · AWS CDK app entrypoint for cloud deployment. · `infra/bin/infra.ts`
- [Infra stack](https://github.com/arpan65/tripai-multi-agent-ai-travel-planner/blob/main/infra/lib/infra-stack.ts): aws cdk stack · Defines EC2, ECR, DynamoDB, and CloudFront deployment resources. · `infra/lib/infra-stack.ts`

### Other components

- **Browser MCP**: external tool · Browser-based research over live sites and search results.
- **Calc MCP**: external tool · Arithmetic service used for budget calculations.

## Connections

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