# safarly-sa/safarly architecture

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

- Interactive diagram: https://gitdiagram.com/safarly-sa/safarly
- Repository: https://github.com/safarly-sa/safarly

## Overview

Safarly is a Saudi-focused travel companion website. Its principal workflow is for a traveler to specify a trip, generate and view a day-by-day itinerary, and use destination and travel tools along the way. The README says the site currently runs on local data and does not use the API server; that server is explicitly described as a skeleton. The graph therefore focuses on the frontend and itinerary engine. Route wiring is visible in App.tsx, but unsampled page and API-client implementations limit further call-level detail.

Main entry points: [`artifacts/safarly/src/App.tsx`](https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/App.tsx) (Safarly app), [`artifacts/safarly/src/lib/engine.ts`](https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/lib/engine.ts) (Itinerary engine), [`artifacts/safarly/src/pages/generating.tsx`](https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/generating.tsx) (Generation view), [`artifacts/safarly/src/pages/trip.tsx`](https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/trip.tsx) (Trip setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Website shell"]
  node_site["Safarly app<br/>[App.tsx]"]
  node_home["Home page<br/>[home.tsx]"]
  node_localization["Language provider<br/>[I18nProvider.tsx]"]
end

subgraph group_planning["Trip planning"]
  node_trip["Trip setup<br/>[trip.tsx]"]
  node_generating["Generation view<br/>[generating.tsx]"]
  node_engine["Itinerary engine<br/>[engine.ts]"]
  node_itinerary["Itinerary view<br/>[itinerary.tsx]"]
end

subgraph group_discovery["Travel discovery"]
  node_stories["Travel stories<br/>[stories.tsx]"]
  node_story["Story detail<br/>[story-detail.tsx]"]
  node_create["Create story<br/>[create-story.tsx]"]
end

subgraph group_tools["Traveler tools"]
  node_lens["Live Lens<br/>[lens.tsx]"]
  node_dialect["Dialect guide<br/>[dialect.tsx]"]
  node_companion["Travel companion<br/>[companion.tsx]"]
end

subgraph group_data["Local planning data"]
  node_poi["Points of interest<br/>[index.ts]"]
end

node_traveler(("Traveler"))

node_traveler -->|"opens"| node_site
node_site -->|"routes to"| node_home
node_site -->|"routes to"| node_trip
node_site -->|"routes to"| node_generating
node_site -->|"routes to"| node_itinerary
node_site -->|"routes to"| node_stories
node_site -->|"routes to"| node_story
node_site -->|"routes to"| node_create
node_site -->|"routes to"| node_lens
node_site -->|"routes to"| node_dialect
node_site -->|"routes to"| node_companion
node_trip -->|"submits trip"| node_generating
node_generating -->|"generates with"| node_engine
node_engine -->|"reads"| node_poi
node_engine -->|"produces itinerary"| node_itinerary
node_traveler -->|"chooses language"| node_localization

click node_site "https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/App.tsx"
click node_home "https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/home.tsx"
click node_trip "https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/trip.tsx"
click node_generating "https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/generating.tsx"
click node_engine "https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/lib/engine.ts"
click node_itinerary "https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/itinerary.tsx"
click node_poi "https://github.com/safarly-sa/safarly/blob/main/lib/poi-data/src/index.ts"
click node_stories "https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/stories.tsx"
click node_story "https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/story-detail.tsx"
click node_create "https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/create-story.tsx"
click node_lens "https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/lens.tsx"
click node_dialect "https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/dialect.tsx"
click node_companion "https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/companion.tsx"
click node_localization "https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/providers/I18nProvider.tsx"

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_site,node_home,node_localization toneBlue
class node_trip,node_generating,node_engine,node_itinerary toneAmber
class node_stories,node_story,node_create toneMint
class node_lens,node_dialect,node_companion toneRose
class node_poi,node_traveler toneIndigo
```

## Components

### Website shell

- [Safarly app](https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/App.tsx): `artifacts/safarly/src/App.tsx`
- [Home page](https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/home.tsx): `artifacts/safarly/src/pages/home.tsx`
- [Language provider](https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/providers/I18nProvider.tsx): `artifacts/safarly/src/providers/I18nProvider.tsx`

### Trip planning

- [Trip setup](https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/trip.tsx): `artifacts/safarly/src/pages/trip.tsx`
- [Generation view](https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/generating.tsx): `artifacts/safarly/src/pages/generating.tsx`
- [Itinerary engine](https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/lib/engine.ts): `artifacts/safarly/src/lib/engine.ts`
- [Itinerary view](https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/itinerary.tsx): `artifacts/safarly/src/pages/itinerary.tsx`

### Travel discovery

- [Travel stories](https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/stories.tsx): `artifacts/safarly/src/pages/stories.tsx`
- [Story detail](https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/story-detail.tsx): `artifacts/safarly/src/pages/story-detail.tsx`
- [Create story](https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/create-story.tsx): `artifacts/safarly/src/pages/create-story.tsx`

### Traveler tools

- [Live Lens](https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/lens.tsx): `artifacts/safarly/src/pages/lens.tsx`
- [Dialect guide](https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/dialect.tsx): `artifacts/safarly/src/pages/dialect.tsx`
- [Travel companion](https://github.com/safarly-sa/safarly/blob/main/artifacts/safarly/src/pages/companion.tsx): `artifacts/safarly/src/pages/companion.tsx`

### Local planning data

- [Points of interest](https://github.com/safarly-sa/safarly/blob/main/lib/poi-data/src/index.ts): `lib/poi-data/src/index.ts`

### Other components

- **Traveler**

## Connections

- Traveler → Safarly app: opens
- Safarly app → Home page: routes to
- Safarly app → Trip setup: routes to
- Safarly app → Generation view: routes to
- Safarly app → Itinerary view: routes to
- Safarly app → Travel stories: routes to
- Safarly app → Story detail: routes to
- Safarly app → Create story: routes to
- Safarly app → Live Lens: routes to
- Safarly app → Dialect guide: routes to
- Safarly app → Travel companion: routes to
- Trip setup → Generation view: submits trip
- Generation view → Itinerary engine: generates with
- Itinerary engine → Points of interest: reads
- Itinerary engine → Itinerary view: produces itinerary
- Traveler → Language provider: chooses language