# 25pradnyesh/travel-ai- architecture

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

- Interactive diagram: https://gitdiagram.com/25pradnyesh/travel-ai-
- Repository: https://github.com/25pradnyesh/travel-ai-

## Overview

Travel AI turns public Instagram Reel URLs into verified destination recommendations and travel dossiers, primarily through its mobile app and Python intelligence engine. The documented flow combines speech, OCR, and caption evidence; resolves and verifies places; adds travel guidance and nearby points of interest; then presents results on maps and supports offline saves. The README also describes Explore and place-detail surfaces. Source excerpts and index references establish key engine ownership; mobile links largely follow explicit README flow because several screens were not sampled.

Main entry points: [`engine/app/pipelines/location_pipeline.py`](https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/pipelines/location_pipeline.py) (Location pipeline), [`engine/app/services/location/location_resolver.py`](https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/location/location_resolver.py) (Place resolution), [`mobile/app/analyze/results.tsx`](https://github.com/25pradnyesh/travel-ai-/blob/main/mobile/app/analyze/results.tsx) (Results dossier), [`engine/app/services/extraction/evidence_builder.py`](https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/extraction/evidence_builder.py) (Evidence builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mobile app"]
  node_mobile_analyze["Reel submission<br/>[index.tsx]"]
  node_mobile_results["Results dossier<br/>[results.tsx]"]
  node_mobile_map["Interactive map<br/>[map.tsx]"]
  node_mobile_saved[("Offline saved places<br/>[saved-places.ts]")]
  node_mobile_explore["Explore feed<br/>[explore.tsx]"]
  node_mobile_detail["Place detail<br/>[&#91;id&#93;.tsx]"]
end

subgraph group_engine["Intelligence engine"]
  node_api["Analyze API<br/>[analyze.py]"]
  node_pipeline["Location pipeline"]
  node_provider["Instagram provider<br/>[manager.py]"]
end

subgraph group_evidence["Evidence extraction"]
  node_evidence_builder["Evidence builder"]
  node_frames["Frame extraction<br/>[frame_extractor.py]"]
  node_ocr["OCR service<br/>[ocr_service.py]"]
end

subgraph group_places["Place intelligence"]
  node_candidate["Candidate generation"]
  node_resolver["Place resolution"]
  node_scoring["Candidate scoring<br/>[scoring_service.py]"]
  node_nearby["Nearby search"]
  node_gemini["Gemini verification<br/>[gemini_verifier.py]"]
end

subgraph group_presentation["Travel presentation"]
  node_travel["Travel intelligence"]
  node_response["Response builder"]
end

node_traveler(("Traveler"))
node_places_api["Google Places"]
node_gemini_api["Gemini service"]

node_traveler -->|"submits Reel"| node_mobile_analyze
node_mobile_analyze -->|"POSTs URL"| node_api
node_api -->|"invokes analysis"| node_pipeline
node_pipeline -->|"requests media"| node_provider
node_provider -.->|"supplies media"| node_evidence_builder
node_pipeline -->|"builds evidence"| node_evidence_builder
node_evidence_builder -->|"extracts frames"| node_frames
node_frames -->|"reads frame text"| node_ocr
node_pipeline -->|"resolves evidence"| node_resolver
node_resolver -->|"generates candidates"| node_candidate
node_candidate -->|"scores candidates"| node_scoring
node_resolver -->|"finds nearby places"| node_nearby
node_nearby -->|"searches places"| node_places_api
node_pipeline -->|"verifies destination"| node_gemini
node_gemini -.->|"requests vision analysis"| node_gemini_api
node_resolver -->|"enriches destination"| node_travel
node_travel -.->|"provides enrichment"| node_response
node_pipeline -->|"builds result"| node_response
node_response -->|"returns dossier"| node_mobile_results
node_mobile_results -->|"opens map"| node_mobile_map
node_mobile_map -->|"opens place detail"| node_mobile_detail
node_mobile_results -->|"saves places"| node_mobile_saved
node_mobile_explore -.->|"opens place detail"| node_mobile_detail

click node_mobile_analyze "https://github.com/25pradnyesh/travel-ai-/blob/main/mobile/app/(tabs)/index.tsx"
click node_mobile_results "https://github.com/25pradnyesh/travel-ai-/blob/main/mobile/app/analyze/results.tsx"
click node_mobile_map "https://github.com/25pradnyesh/travel-ai-/blob/main/mobile/app/analyze/map.tsx"
click node_mobile_saved "https://github.com/25pradnyesh/travel-ai-/blob/main/mobile/lib/storage/saved-places.ts"
click node_mobile_explore "https://github.com/25pradnyesh/travel-ai-/blob/main/mobile/app/(tabs)/explore.tsx"
click node_mobile_detail "https://github.com/25pradnyesh/travel-ai-/blob/main/mobile/app/place/%5Bid%5D.tsx"
click node_api "https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/api/analyze.py"
click node_pipeline "https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/pipelines/location_pipeline.py"
click node_provider "https://github.com/25pradnyesh/travel-ai-/blob/main/engine/providers/manager.py"
click node_evidence_builder "https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/extraction/evidence_builder.py"
click node_frames "https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/extraction/frame_extractor.py"
click node_ocr "https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/ocr/ocr_service.py"
click node_candidate "https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/location/candidate_service.py"
click node_resolver "https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/location/location_resolver.py"
click node_scoring "https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/scoring/scoring_service.py"
click node_nearby "https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/maps/nearby_search_service.py"
click node_gemini "https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/gemini/gemini_verifier.py"
click node_travel "https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/travel/travel_intelligence_service.py"
click node_response "https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/response/response_builder.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_mobile_analyze,node_mobile_results,node_mobile_map,node_mobile_saved,node_mobile_explore,node_mobile_detail toneBlue
class node_api,node_pipeline,node_provider toneAmber
class node_evidence_builder,node_frames,node_ocr toneMint
class node_candidate,node_resolver,node_scoring,node_nearby,node_gemini toneRose
class node_travel,node_response,node_traveler,node_places_api,node_gemini_api toneIndigo
```

## Components

### Mobile app

- [Reel submission](https://github.com/25pradnyesh/travel-ai-/blob/main/mobile/app/(tabs)/index.tsx): `mobile/app/(tabs)/index.tsx`
- [Results dossier](https://github.com/25pradnyesh/travel-ai-/blob/main/mobile/app/analyze/results.tsx): `mobile/app/analyze/results.tsx`
- [Interactive map](https://github.com/25pradnyesh/travel-ai-/blob/main/mobile/app/analyze/map.tsx): `mobile/app/analyze/map.tsx`
- [Offline saved places](https://github.com/25pradnyesh/travel-ai-/blob/main/mobile/lib/storage/saved-places.ts): `mobile/lib/storage/saved-places.ts`
- [Explore feed](https://github.com/25pradnyesh/travel-ai-/blob/main/mobile/app/(tabs)/explore.tsx): `mobile/app/(tabs)/explore.tsx`
- [Place detail](https://github.com/25pradnyesh/travel-ai-/blob/main/mobile/app/place/%5Bid%5D.tsx): `mobile/app/place/[id].tsx`

### Intelligence engine

- [Analyze API](https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/api/analyze.py): `engine/app/api/analyze.py`
- [Location pipeline](https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/pipelines/location_pipeline.py): `engine/app/pipelines/location_pipeline.py`
- [Instagram provider](https://github.com/25pradnyesh/travel-ai-/blob/main/engine/providers/manager.py): `engine/providers/manager.py`

### Evidence extraction

- [Evidence builder](https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/extraction/evidence_builder.py): `engine/app/services/extraction/evidence_builder.py`
- [Frame extraction](https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/extraction/frame_extractor.py): `engine/app/services/extraction/frame_extractor.py`
- [OCR service](https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/ocr/ocr_service.py): `engine/app/services/ocr/ocr_service.py`

### Place intelligence

- [Candidate generation](https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/location/candidate_service.py): `engine/app/services/location/candidate_service.py`
- [Place resolution](https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/location/location_resolver.py): `engine/app/services/location/location_resolver.py`
- [Candidate scoring](https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/scoring/scoring_service.py): `engine/app/services/scoring/scoring_service.py`
- [Nearby search](https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/maps/nearby_search_service.py): `engine/app/services/maps/nearby_search_service.py`
- [Gemini verification](https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/gemini/gemini_verifier.py): `engine/app/services/gemini/gemini_verifier.py`

### Travel presentation

- [Travel intelligence](https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/travel/travel_intelligence_service.py): `engine/app/services/travel/travel_intelligence_service.py`
- [Response builder](https://github.com/25pradnyesh/travel-ai-/blob/main/engine/app/services/response/response_builder.py): `engine/app/services/response/response_builder.py`

### Other components

- **Traveler**
- **Google Places**
- **Gemini service**

## Connections

- Traveler → Reel submission: submits Reel (evidence: `README.md`)
- Reel submission → Analyze API: POSTs URL (evidence: `README.md`)
- Analyze API → Location pipeline: invokes analysis (evidence: `engine/app/api/analyze.py`)
- Location pipeline → Instagram provider: requests media (evidence: `README.md`)
- Instagram provider → Evidence builder: supplies media
- Location pipeline → Evidence builder: builds evidence (evidence: `engine/app/pipelines/location_pipeline.py`)
- Evidence builder → Frame extraction: extracts frames (evidence: `engine/app/services/extraction/evidence_builder.py`)
- Frame extraction → OCR service: reads frame text (evidence: `engine/app/services/extraction/frame_extractor.py`)
- Location pipeline → Place resolution: resolves evidence (evidence: `engine/app/pipelines/location_pipeline.py`)
- Place resolution → Candidate generation: generates candidates (evidence: `engine/app/services/location/location_resolver.py`)
- Candidate generation → Candidate scoring: scores candidates (evidence: `engine/app/services/location/candidate_service.py`)
- Place resolution → Nearby search: finds nearby places (evidence: `engine/app/services/location/location_resolver.py`)
- Nearby search → Google Places: searches places (evidence: `engine/app/services/maps/nearby_search_service.py`)
- Location pipeline → Gemini verification: verifies destination (evidence: `engine/app/pipelines/location_pipeline.py`)
- Gemini verification → Gemini service: requests vision analysis
- Place resolution → Travel intelligence: enriches destination (evidence: `engine/app/services/location/location_resolver.py`)
- Travel intelligence → Response builder: provides enrichment (evidence: `engine/app/services/response/response_builder.py`)
- Location pipeline → Response builder: builds result (evidence: `engine/app/pipelines/location_pipeline.py`)
- Response builder → Results dossier: returns dossier (evidence: `README.md`)
- Results dossier → Interactive map: opens map (evidence: `README.md`)
- Interactive map → Place detail: opens place detail (evidence: `README.md`)
- Results dossier → Offline saved places: saves places (evidence: `README.md`)
- Explore feed → Place detail: opens place detail
