# sumanentc/travel-planner architecture

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

- Interactive diagram: https://gitdiagram.com/sumanentc/travel-planner
- Repository: https://github.com/sumanentc/travel-planner

## Overview

RoamWise is a Chainlit travel-planning chat application. A user query enters the LangGraph workflow, which validates intent, classifies travel queries, gathers trip details, and guides the user through transport, accommodation, and itinerary recommendations with approval and feedback loops. The workflow also supports decision routing and emailing a completed itinerary. Shared models, prompts, tools, and OpenAI configuration support the agents. The README documents SQLite chat-history persistence and the human-approval stages; source excerpts do not show their complete runtime wiring, so those links are omitted or marked unverified.

Main entry points: [`workflow.py`](https://github.com/sumanentc/travel-planner/blob/main/workflow.py) (Travel workflow), [`agents/query_analyzer.py`](https://github.com/sumanentc/travel-planner/blob/main/agents/query_analyzer.py) (Query analyzer), [`agents/prompts.py`](https://github.com/sumanentc/travel-planner/blob/main/agents/prompts.py) (Agent prompts), [`models/agent_models.py`](https://github.com/sumanentc/travel-planner/blob/main/models/agent_models.py) (Travel state models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Chat interface"]
  node_chainlit["Chat interface<br/>[app.py]"]
  node_chat_history[("Chat history<br/>[config.toml]")]
end

subgraph group_orchestration["Workflow orchestration"]
  node_workflow["Travel workflow<br/>[workflow.py]"]
end

subgraph group_planning["Travel planning agents"]
  node_validator["Intent validator<br/>[validator.py]"]
  node_query_analyzer["Query analyzer<br/>[query_analyzer.py]"]
  node_entity_identifier["Entity identifier"]
  node_decision["Decision router<br/>[decision.py]"]
  node_transport["Transport planner<br/>[transport.py]"]
  node_accommodation["Accommodation planner<br/>[accomodation.py]"]
  node_itinerary["Itinerary planner<br/>[itinerary.py]"]
  node_email["Itinerary email<br/>[email_agent.py]"]
end

subgraph group_shared["Shared agent services"]
  node_agent_prompts["Agent prompts<br/>[prompts.py]"]
  node_agent_models["Travel state models<br/>[agent_models.py]"]
  node_tools["Search and research tools<br/>[custom_tools.py]"]
  node_model_config["OpenAI model setup<br/>[utils.py]"]
end

node_traveler(("Traveler"))
node_openai{{"OpenAI"}}
node_search_services{{"Web search services"}}
node_brevo{{"Brevo email service"}}

node_traveler -->|"submits queries"| node_chainlit
node_chainlit -.->|"starts planning"| node_workflow
node_traveler -->|"approves or revises"| node_workflow
node_workflow -->|"dispatches"| node_validator
node_workflow -->|"dispatches"| node_query_analyzer
node_workflow -->|"dispatches"| node_entity_identifier
node_workflow -->|"dispatches"| node_decision
node_workflow -->|"dispatches"| node_transport
node_workflow -->|"dispatches"| node_accommodation
node_workflow -->|"dispatches"| node_itinerary
node_workflow -->|"dispatches"| node_email
node_workflow -->|"routes after validation"| node_query_analyzer
node_workflow -->|"routes after analysis"| node_entity_identifier
node_workflow -->|"routes after entity approval"| node_transport
node_workflow -->|"routes after transport approval"| node_itinerary
node_workflow -->|"routes for email"| node_email
node_validator -->|"uses prompt"| node_agent_prompts
node_validator -->|"uses state model"| node_agent_models
node_query_analyzer -->|"uses prompt"| node_agent_prompts
node_query_analyzer -->|"uses intent model"| node_agent_models
node_query_analyzer -->|"uses search tool"| node_tools
node_query_analyzer -->|"gets model"| node_model_config
node_entity_identifier -->|"uses prompt"| node_agent_prompts
node_entity_identifier -->|"uses inquiry model"| node_agent_models
node_transport -->|"uses prompt"| node_agent_prompts
node_transport -->|"uses state model"| node_agent_models
node_transport -->|"uses research tools"| node_tools
node_accommodation -->|"uses prompt"| node_agent_prompts
node_accommodation -->|"uses state model"| node_agent_models
node_accommodation -->|"uses search tools"| node_tools
node_itinerary -->|"uses prompt"| node_agent_prompts
node_itinerary -->|"uses itinerary model"| node_agent_models
node_email -->|"uses prompt"| node_agent_prompts
node_email -->|"uses email model"| node_agent_models
node_email -->|"sends itinerary"| node_brevo
node_tools -->|"searches and researches"| node_search_services
node_validator -.->|"queries model"| node_openai
node_query_analyzer -.->|"queries model"| node_openai
node_traveler -.->|"resumes conversations"| node_chat_history

click node_chainlit "https://github.com/sumanentc/travel-planner/blob/main/app.py"
click node_chat_history "https://github.com/sumanentc/travel-planner/blob/main/.chainlit/config.toml"
click node_workflow "https://github.com/sumanentc/travel-planner/blob/main/workflow.py"
click node_validator "https://github.com/sumanentc/travel-planner/blob/main/agents/validator.py"
click node_query_analyzer "https://github.com/sumanentc/travel-planner/blob/main/agents/query_analyzer.py"
click node_entity_identifier "https://github.com/sumanentc/travel-planner/blob/main/agents/entity_identifier.py"
click node_decision "https://github.com/sumanentc/travel-planner/blob/main/agents/decision.py"
click node_transport "https://github.com/sumanentc/travel-planner/blob/main/agents/transport.py"
click node_accommodation "https://github.com/sumanentc/travel-planner/blob/main/agents/accomodation.py"
click node_itinerary "https://github.com/sumanentc/travel-planner/blob/main/agents/itinerary.py"
click node_email "https://github.com/sumanentc/travel-planner/blob/main/agents/email_agent.py"
click node_agent_prompts "https://github.com/sumanentc/travel-planner/blob/main/agents/prompts.py"
click node_agent_models "https://github.com/sumanentc/travel-planner/blob/main/models/agent_models.py"
click node_tools "https://github.com/sumanentc/travel-planner/blob/main/tools/custom_tools.py"
click node_model_config "https://github.com/sumanentc/travel-planner/blob/main/utils.py"

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_chainlit,node_chat_history toneBlue
class node_workflow toneAmber
class node_validator,node_query_analyzer,node_entity_identifier,node_decision,node_transport,node_accommodation,node_itinerary,node_email toneMint
class node_agent_prompts,node_agent_models,node_tools,node_model_config toneRose
class node_traveler,node_openai,node_search_services,node_brevo toneIndigo
```

## Components

### Chat interface

- [Chat interface](https://github.com/sumanentc/travel-planner/blob/main/app.py): `app.py`
- [Chat history](https://github.com/sumanentc/travel-planner/blob/main/.chainlit/config.toml): `.chainlit/config.toml`

### Workflow orchestration

- [Travel workflow](https://github.com/sumanentc/travel-planner/blob/main/workflow.py): `workflow.py`

### Travel planning agents

- [Intent validator](https://github.com/sumanentc/travel-planner/blob/main/agents/validator.py): `agents/validator.py`
- [Query analyzer](https://github.com/sumanentc/travel-planner/blob/main/agents/query_analyzer.py): `agents/query_analyzer.py`
- [Entity identifier](https://github.com/sumanentc/travel-planner/blob/main/agents/entity_identifier.py): `agents/entity_identifier.py`
- [Decision router](https://github.com/sumanentc/travel-planner/blob/main/agents/decision.py): `agents/decision.py`
- [Transport planner](https://github.com/sumanentc/travel-planner/blob/main/agents/transport.py): `agents/transport.py`
- [Accommodation planner](https://github.com/sumanentc/travel-planner/blob/main/agents/accomodation.py): `agents/accomodation.py`
- [Itinerary planner](https://github.com/sumanentc/travel-planner/blob/main/agents/itinerary.py): `agents/itinerary.py`
- [Itinerary email](https://github.com/sumanentc/travel-planner/blob/main/agents/email_agent.py): `agents/email_agent.py`

### Shared agent services

- [Agent prompts](https://github.com/sumanentc/travel-planner/blob/main/agents/prompts.py): `agents/prompts.py`
- [Travel state models](https://github.com/sumanentc/travel-planner/blob/main/models/agent_models.py): `models/agent_models.py`
- [Search and research tools](https://github.com/sumanentc/travel-planner/blob/main/tools/custom_tools.py): `tools/custom_tools.py`
- [OpenAI model setup](https://github.com/sumanentc/travel-planner/blob/main/utils.py): `utils.py`

### Other components

- **Traveler**
- **OpenAI**
- **Web search services**
- **Brevo email service**

## Connections

- Traveler → Chat interface: submits queries (evidence: `README.md`)
- Chat interface → Travel workflow: starts planning (evidence: `app.py`)
- Traveler → Travel workflow: approves or revises (evidence: `README.md`)
- Travel workflow → Intent validator: dispatches (evidence: `workflow.py`)
- Travel workflow → Query analyzer: dispatches (evidence: `workflow.py`)
- Travel workflow → Entity identifier: dispatches (evidence: `workflow.py`)
- Travel workflow → Decision router: dispatches (evidence: `workflow.py`)
- Travel workflow → Transport planner: dispatches (evidence: `workflow.py`)
- Travel workflow → Accommodation planner: dispatches (evidence: `workflow.py`)
- Travel workflow → Itinerary planner: dispatches (evidence: `workflow.py`)
- Travel workflow → Itinerary email: dispatches (evidence: `workflow.py`)
- Travel workflow → Query analyzer: routes after validation (evidence: `README.md`)
- Travel workflow → Entity identifier: routes after analysis (evidence: `README.md`)
- Travel workflow → Transport planner: routes after entity approval (evidence: `README.md`)
- Travel workflow → Itinerary planner: routes after transport approval (evidence: `README.md`)
- Travel workflow → Itinerary email: routes for email (evidence: `README.md`)
- Intent validator → Agent prompts: uses prompt (evidence: `agents/validator.py`)
- Intent validator → Travel state models: uses state model (evidence: `agents/validator.py`)
- Query analyzer → Agent prompts: uses prompt (evidence: `agents/query_analyzer.py`)
- Query analyzer → Travel state models: uses intent model (evidence: `agents/query_analyzer.py`)
- Query analyzer → Search and research tools: uses search tool (evidence: `agents/query_analyzer.py`)
- Query analyzer → OpenAI model setup: gets model (evidence: `agents/query_analyzer.py`)
- Entity identifier → Agent prompts: uses prompt (evidence: `agents/entity_identifier.py`)
- Entity identifier → Travel state models: uses inquiry model (evidence: `agents/entity_identifier.py`)
- Transport planner → Agent prompts: uses prompt (evidence: `agents/transport.py`)
- Transport planner → Travel state models: uses state model (evidence: `agents/transport.py`)
- Transport planner → Search and research tools: uses research tools (evidence: `agents/transport.py`)
- Accommodation planner → Agent prompts: uses prompt (evidence: `agents/accomodation.py`)
- Accommodation planner → Travel state models: uses state model (evidence: `agents/accomodation.py`)
- Accommodation planner → Search and research tools: uses search tools (evidence: `agents/accomodation.py`)
- Itinerary planner → Agent prompts: uses prompt (evidence: `agents/itinerary.py`)
- Itinerary planner → Travel state models: uses itinerary model (evidence: `agents/itinerary.py`)
- Itinerary email → Agent prompts: uses prompt (evidence: `agents/email_agent.py`)
- Itinerary email → Travel state models: uses email model (evidence: `agents/email_agent.py`)
- Itinerary email → Brevo email service: sends itinerary (evidence: `agents/email_agent.py`)
- Search and research tools → Web search services: searches and researches (evidence: `tools/custom_tools.py`)
- Intent validator → OpenAI: queries model
- Query analyzer → OpenAI: queries model
- Traveler → Chat history: resumes conversations (evidence: `README.md`)
