# rishikgrandhi/tripmind architecture

> Architecture diagram of the GitHub repository rishikgrandhi/tripmind, 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/rishikgrandhi/tripmind
- Repository: https://github.com/rishikgrandhi/tripmind

## Overview

TripMind turns a natural-language travel request into a constraint-checked itinerary, repairs violations within configured bounds, scores feasible plans, explains the result, and retains completed or infeasible plans in SQLite. The frontend submits requests and presents the itinerary, validation, agent trace, replanning history, and saved plans. The README documents the main planning stages and optional integrations; the detailed internal call graph is limited to relationships visible in the provided excerpts and SOURCE INDEX.

Main entry points: [`backend/app/planning/coordinator.py`](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/planning/coordinator.py) (Planning coordinator), [`frontend/src/App.tsx`](https://github.com/rishikgrandhi/tripmind/blob/main/frontend/src/App.tsx) (Trip planner UI), [`backend/app/tools/registry.py`](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/tools/registry.py) (Tool registry), [`backend/app/api/trips.py`](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/api/trips.py) (Trip endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Planning UI"]
  node_app["Trip planner UI<br/>[App.tsx]"]
  node_requestform["Request form<br/>[RequestForm.tsx]"]
  node_planviews["Plan and trace views"]
  node_historyview["Recent plans view<br/>[RecentPlans.tsx]"]
  node_clientapi["Trip API client<br/>[tripmind.ts]"]
end

subgraph group_request["Request handling"]
  node_tripapi["Trip endpoints<br/>[trips.py]"]
  node_extract["Intent extraction<br/>[service.py]"]
  node_intentmodels["Extraction models<br/>[models.py]"]
  node_llm["LLM providers<br/>[base.py]"]
end

subgraph group_engine["Planning engine"]
  node_coordinator["Planning coordinator<br/>[coordinator.py]"]
  node_agentloop["Agent action loop<br/>[agent_loop.py]"]
  node_candidate["Candidate builder"]
  node_validation["Constraint validation<br/>[rules.py]"]
  node_cost["Cost breakdown<br/>[cost_engine.py]"]
  node_replanning["Bounded replanning<br/>[replanner.py]"]
  node_scoring["Preference scoring<br/>[scorer.py]"]
  node_explanation["Plan explanation<br/>[generator.py]"]
end

subgraph group_providers["Travel tools"]
  node_registry["Tool registry<br/>[registry.py]"]
  node_localtools["Local travel tools<br/>[local.py]"]
  node_catalog["Local travel catalog<br/>[local_data.py]"]
  node_live["Live travel adapters<br/>[adapters.py]"]
end

subgraph group_history["State and history"]
  node_domain["Trip state and models<br/>[models.py]"]
  node_sqlite[("Planning history store<br/>[models.py]")]
  node_repository["Session repository<br/>[repository.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

node_traveler(("Traveler"))

node_traveler -->|"enters request"| node_app
node_app -->|"renders"| node_requestform
node_app -->|"submits and loads"| node_clientapi
node_clientapi -->|"calls API"| node_tripapi
node_tripapi -->|"plans natural language"| node_extract
node_extract -->|"validates intent"| node_intentmodels
node_extract -->|"selects provider"| node_llm
node_extract -->|"plans request"| node_coordinator
node_coordinator -->|"runs agent loop"| node_agentloop
node_coordinator -->|"builds candidate"| node_candidate
node_coordinator -->|"checks constraints"| node_validation
node_coordinator -->|"repairs violations"| node_replanning
node_coordinator -->|"scores feasible plan"| node_scoring
node_coordinator -->|"explains outcome"| node_explanation
node_agentloop -->|"uses builder"| node_candidate
node_agentloop -->|"dispatches tools"| node_registry
node_candidate -->|"searches options"| node_registry
node_registry -->|"selects local tools"| node_localtools
node_registry -.->|"selects live adapters"| node_live
node_localtools -->|"reads records"| node_catalog
node_validation -->|"calculates costs"| node_cost
node_validation -->|"checks travel data"| node_catalog
node_coordinator -->|"maintains trip state"| node_domain
node_tripapi -.->|"persists plan history"| node_repository
node_repository -->|"reads and writes"| node_sqlite
node_repository -->|"serializes trip state"| node_domain
node_settings -->|"configures providers"| node_registry
node_settings -->|"sets planning limits"| node_coordinator
node_app -->|"renders result trace"| node_planviews
node_app -->|"renders saved plans"| node_historyview
node_tripapi -->|"returns plan response"| node_app

click node_app "https://github.com/rishikgrandhi/tripmind/blob/main/frontend/src/App.tsx"
click node_requestform "https://github.com/rishikgrandhi/tripmind/blob/main/frontend/src/components/RequestForm.tsx"
click node_planviews "https://github.com/rishikgrandhi/tripmind/blob/main/frontend/src/components/PlanningPipeline.tsx"
click node_historyview "https://github.com/rishikgrandhi/tripmind/blob/main/frontend/src/components/RecentPlans.tsx"
click node_clientapi "https://github.com/rishikgrandhi/tripmind/blob/main/frontend/src/api/tripmind.ts"
click node_tripapi "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/api/trips.py"
click node_extract "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/extraction/service.py"
click node_intentmodels "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/extraction/models.py"
click node_llm "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/llm/base.py"
click node_coordinator "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/planning/coordinator.py"
click node_agentloop "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/planning/agent_loop.py"
click node_candidate "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/planning/candidate_builder.py"
click node_validation "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/planning/validation/rules.py"
click node_cost "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/planning/cost_engine.py"
click node_replanning "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/planning/replanning/replanner.py"
click node_scoring "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/planning/scoring/scorer.py"
click node_explanation "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/planning/explanation/generator.py"
click node_domain "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/domain/models.py"
click node_registry "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/tools/registry.py"
click node_localtools "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/tools/local.py"
click node_catalog "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/tools/local_data.py"
click node_live "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/tools/external/adapters.py"
click node_sqlite "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/persistence/models.py"
click node_repository "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/persistence/repository.py"
click node_settings "https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/core/config.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_app,node_requestform,node_planviews,node_historyview,node_clientapi toneBlue
class node_tripapi,node_extract,node_intentmodels,node_llm toneAmber
class node_coordinator,node_agentloop,node_candidate,node_validation,node_cost,node_replanning,node_scoring,node_explanation toneMint
class node_registry,node_localtools,node_catalog,node_live toneRose
class node_domain,node_sqlite,node_repository,node_settings,node_traveler toneIndigo
```

## Components

### Planning UI

- [Trip planner UI](https://github.com/rishikgrandhi/tripmind/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Request form](https://github.com/rishikgrandhi/tripmind/blob/main/frontend/src/components/RequestForm.tsx): `frontend/src/components/RequestForm.tsx`
- [Plan and trace views](https://github.com/rishikgrandhi/tripmind/blob/main/frontend/src/components/PlanningPipeline.tsx): `frontend/src/components/PlanningPipeline.tsx`
- [Recent plans view](https://github.com/rishikgrandhi/tripmind/blob/main/frontend/src/components/RecentPlans.tsx): `frontend/src/components/RecentPlans.tsx`
- [Trip API client](https://github.com/rishikgrandhi/tripmind/blob/main/frontend/src/api/tripmind.ts): `frontend/src/api/tripmind.ts`

### Request handling

- [Trip endpoints](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/api/trips.py): `backend/app/api/trips.py`
- [Intent extraction](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/extraction/service.py): `backend/app/extraction/service.py`
- [Extraction models](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/extraction/models.py): `backend/app/extraction/models.py`
- [LLM providers](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/llm/base.py): `backend/app/llm/base.py`

### Planning engine

- [Planning coordinator](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/planning/coordinator.py): `backend/app/planning/coordinator.py`
- [Agent action loop](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/planning/agent_loop.py): `backend/app/planning/agent_loop.py`
- [Candidate builder](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/planning/candidate_builder.py): `backend/app/planning/candidate_builder.py`
- [Constraint validation](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/planning/validation/rules.py): `backend/app/planning/validation/rules.py`
- [Cost breakdown](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/planning/cost_engine.py): `backend/app/planning/cost_engine.py`
- [Bounded replanning](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/planning/replanning/replanner.py): `backend/app/planning/replanning/replanner.py`
- [Preference scoring](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/planning/scoring/scorer.py): `backend/app/planning/scoring/scorer.py`
- [Plan explanation](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/planning/explanation/generator.py): `backend/app/planning/explanation/generator.py`

### Travel tools

- [Tool registry](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/tools/registry.py): `backend/app/tools/registry.py`
- [Local travel tools](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/tools/local.py): `backend/app/tools/local.py`
- [Local travel catalog](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/tools/local_data.py): `backend/app/tools/local_data.py`
- [Live travel adapters](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/tools/external/adapters.py): `backend/app/tools/external/adapters.py`

### State and history

- [Trip state and models](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/domain/models.py): `backend/app/domain/models.py`
- [Planning history store](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/persistence/models.py): `backend/app/persistence/models.py`
- [Session repository](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/persistence/repository.py): `backend/app/persistence/repository.py`
- [Runtime settings](https://github.com/rishikgrandhi/tripmind/blob/main/backend/app/core/config.py): `backend/app/core/config.py`

### Other components

- **Traveler**

## Connections

- Traveler → Trip planner UI: enters request
- Trip planner UI → Request form: renders (evidence: `frontend/src/App.tsx`)
- Trip planner UI → Trip API client: submits and loads (evidence: `frontend/src/App.tsx`)
- Trip API client → Trip endpoints: calls API
- Trip endpoints → Intent extraction: plans natural language (evidence: `backend/app/api/trips.py`)
- Intent extraction → Extraction models: validates intent (evidence: `backend/app/extraction/service.py`)
- Intent extraction → LLM providers: selects provider (evidence: `backend/app/extraction/service.py`)
- Intent extraction → Planning coordinator: plans request (evidence: `backend/app/extraction/service.py`)
- Planning coordinator → Agent action loop: runs agent loop (evidence: `backend/app/planning/coordinator.py`)
- Planning coordinator → Candidate builder: builds candidate (evidence: `backend/app/planning/coordinator.py`)
- Planning coordinator → Constraint validation: checks constraints (evidence: `backend/app/planning/coordinator.py`)
- Planning coordinator → Bounded replanning: repairs violations (evidence: `backend/app/planning/coordinator.py`)
- Planning coordinator → Preference scoring: scores feasible plan (evidence: `backend/app/planning/coordinator.py`)
- Planning coordinator → Plan explanation: explains outcome (evidence: `backend/app/planning/coordinator.py`)
- Agent action loop → Candidate builder: uses builder (evidence: `backend/app/planning/agent_loop.py`)
- Agent action loop → Tool registry: dispatches tools (evidence: `backend/app/planning/agent_loop.py`)
- Candidate builder → Tool registry: searches options
- Tool registry → Local travel tools: selects local tools (evidence: `backend/app/tools/registry.py`)
- Tool registry → Live travel adapters: selects live adapters (evidence: `backend/app/tools/registry.py`)
- Local travel tools → Local travel catalog: reads records (evidence: `backend/app/tools/local.py`)
- Constraint validation → Cost breakdown: calculates costs (evidence: `backend/app/planning/validation/rules.py`)
- Constraint validation → Local travel catalog: checks travel data (evidence: `backend/app/planning/validation/rules.py`)
- Planning coordinator → Trip state and models: maintains trip state (evidence: `backend/app/planning/coordinator.py`)
- Trip endpoints → Session repository: persists plan history
- Session repository → Planning history store: reads and writes (evidence: `backend/app/persistence/repository.py`)
- Session repository → Trip state and models: serializes trip state (evidence: `backend/app/persistence/repository.py`)
- Runtime settings → Tool registry: configures providers (evidence: `backend/app/tools/registry.py`)
- Runtime settings → Planning coordinator: sets planning limits (evidence: `backend/app/planning/coordinator.py`)
- Trip planner UI → Plan and trace views: renders result trace (evidence: `frontend/src/App.tsx`)
- Trip planner UI → Recent plans view: renders saved plans (evidence: `frontend/src/App.tsx`)
- Trip endpoints → Trip planner UI: returns plan response
