# aaravkalia-88/wanderers architecture

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

- Interactive diagram: https://gitdiagram.com/aaravkalia-88/wanderers
- Repository: https://github.com/aaravkalia-88/wanderers

## Overview

Wanderer is a travel-discovery and personal travel-journal product centered on finding Indian destinations, planning trips, recording visits, and building a passport. The React app presents discovery, maps, weather, trip planning, community stories, and passport features; its API client connects to FastAPI, which serves authentication, destination, travel, export, community, and chat routes. The backend persists user, destination, travel, and community records. The README documents external weather, map, and routing integrations. Some route-to-handler and UI-to-feature wiring is inferred only where explicitly documented; unsampled source limits further call-level detail.

Main entry points: [`frontend/src/App.tsx`](https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/App.tsx) (App shell), [`backend/app/main.py`](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/main.py) (API application), [`backend/app/api/v1/api.py`](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/api/v1/api.py) (API route registry), [`backend/app/db/session.py`](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/db/session.py) (Database sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Travel experience"]
  node_app["App shell<br/>[App.tsx]"]
  node_discovery["Destination discovery"]
  node_passport["Passport journal<br/>[PassportPage.tsx]"]
  node_trip_planner["Trip planning<br/>[TripPlanner.tsx]"]
  node_community["Community stories<br/>[Community.tsx]"]
  node_atlas["Atlas maps<br/>[Atlas.tsx]"]
  node_weather["Destination weather<br/>[Weather.tsx]"]
  node_auth_form["Sign-in form<br/>[AuthForm.tsx]"]
end

subgraph group_client_support["Client services"]
  node_preferences["User preferences<br/>[preferences.tsx]"]
  node_travel_api["Travel API client<br/>[travel.ts]"]
  node_destination_api["Destination catalog client<br/>[destinations.ts]"]
  node_route_client["Route and city lookup<br/>[routes.ts]"]
end

subgraph group_api["API and identity"]
  node_fastapi["API application<br/>[main.py]"]
  node_api_router["API route registry<br/>[api.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_destination_routes["Destination routes<br/>[destinations.py]"]
  node_travel_routes["Travel routes<br/>[travel.py]"]
  node_community_routes["Community routes<br/>[community.py]"]
  node_export_routes["Journal export<br/>[export.py]"]
  node_chat_routes["AI chat routes<br/>[ai_chat.py]"]
end

subgraph group_domain["Travel domain"]
  node_travel_rules["Travel progression rules<br/>[travel.py]"]
  node_destination_model[("Destination records<br/>[destination.py]")]
  node_travel_model[("Travel records<br/>[travel.py]")]
  node_user_model[("User records<br/>[user.py]")]
  node_community_model[("Community records<br/>[community.py]")]
end

subgraph group_platform["Runtime and persistence"]
  node_db_session["Database sessions<br/>[session.py]"]
  node_cache[("Cache and rate limits<br/>[cache.py]")]
  node_config["Runtime configuration<br/>[config.py]"]
end

node_traveler(("Traveler"))
node_open_meteo["Open-Meteo services"]
node_osrm["OSRM routing"]
node_maps["Google Maps directions"]

node_traveler -->|"uses"| node_app
node_app -->|"renders"| node_discovery
node_app -->|"renders"| node_passport
node_app -->|"renders"| node_trip_planner
node_app -->|"renders"| node_community
node_app -->|"renders"| node_atlas
node_app -->|"renders"| node_weather
node_app -->|"renders"| node_auth_form
node_app -->|"uses"| node_preferences
node_app -->|"loads passport"| node_travel_api
node_auth_form -->|"signs in"| node_travel_api
node_app -->|"uses catalog"| node_destination_api
node_atlas -->|"loads destinations"| node_destination_api
node_passport -->|"loads journal"| node_travel_api
node_community -->|"requests stories"| node_travel_api
node_trip_planner -.->|"uses routing"| node_route_client
node_route_client -->|"geocodes city"| node_open_meteo
node_route_client -->|"requests road route"| node_osrm
node_route_client -->|"builds directions link"| node_maps
node_weather -.->|"gets forecasts"| node_open_meteo
node_travel_api -->|"calls API"| node_fastapi
node_fastapi -->|"mounts routes"| node_api_router
node_api_router -->|"registers"| node_auth_routes
node_api_router -->|"registers"| node_destination_routes
node_api_router -->|"registers"| node_travel_routes
node_api_router -->|"registers"| node_community_routes
node_api_router -->|"registers"| node_export_routes
node_api_router -->|"registers"| node_chat_routes
node_fastapi -->|"opens sessions"| node_db_session
node_fastapi -->|"initializes cache"| node_cache
node_fastapi -->|"reads settings"| node_config
node_auth_routes -->|"uses sessions"| node_db_session
node_auth_routes -->|"rate limits"| node_cache
node_auth_routes -->|"uses security settings"| node_config
node_db_session -->|"stores"| node_destination_model
node_db_session -->|"stores"| node_travel_model
node_db_session -->|"stores"| node_user_model
node_db_session -->|"stores"| node_community_model
node_fastapi -->|"loads progression rules"| node_travel_rules
node_fastapi -->|"seeds catalog"| node_destination_model

click node_app "https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/App.tsx"
click node_discovery "https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/components/DestinationCard.tsx"
click node_passport "https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/components/PassportPage.tsx"
click node_trip_planner "https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/components/TripPlanner.tsx"
click node_community "https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/components/Community.tsx"
click node_atlas "https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/components/atlas/Atlas.tsx"
click node_weather "https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/components/Weather.tsx"
click node_auth_form "https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/components/AuthForm.tsx"
click node_preferences "https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/preferences.tsx"
click node_travel_api "https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/api/travel.ts"
click node_destination_api "https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/api/destinations.ts"
click node_route_client "https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/api/routes.ts"
click node_fastapi "https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/main.py"
click node_api_router "https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/api/v1/api.py"
click node_auth_routes "https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/api/v1/auth.py"
click node_destination_routes "https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/api/v1/destinations.py"
click node_travel_routes "https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/api/v1/travel.py"
click node_community_routes "https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/api/v1/community.py"
click node_export_routes "https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/api/v1/export.py"
click node_chat_routes "https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/api/v1/ai_chat.py"
click node_travel_rules "https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/services/travel.py"
click node_destination_model "https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/models/destination.py"
click node_travel_model "https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/models/travel.py"
click node_user_model "https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/models/user.py"
click node_community_model "https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/models/community.py"
click node_db_session "https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/db/session.py"
click node_cache "https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/core/cache.py"
click node_config "https://github.com/aaravkalia-88/wanderers/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_discovery,node_passport,node_trip_planner,node_community,node_atlas,node_weather,node_auth_form toneBlue
class node_preferences,node_travel_api,node_destination_api,node_route_client toneAmber
class node_fastapi,node_api_router,node_auth_routes,node_destination_routes,node_travel_routes,node_community_routes,node_export_routes,node_chat_routes toneMint
class node_travel_rules,node_destination_model,node_travel_model,node_user_model,node_community_model toneRose
class node_db_session,node_cache,node_config,node_traveler,node_open_meteo,node_osrm,node_maps toneIndigo
```

## Components

### Travel experience

- [App shell](https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Destination discovery](https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/components/DestinationCard.tsx): `frontend/src/components/DestinationCard.tsx`
- [Passport journal](https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/components/PassportPage.tsx): `frontend/src/components/PassportPage.tsx`
- [Trip planning](https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/components/TripPlanner.tsx): `frontend/src/components/TripPlanner.tsx`
- [Community stories](https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/components/Community.tsx): `frontend/src/components/Community.tsx`
- [Atlas maps](https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/components/atlas/Atlas.tsx): `frontend/src/components/atlas/Atlas.tsx`
- [Destination weather](https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/components/Weather.tsx): `frontend/src/components/Weather.tsx`
- [Sign-in form](https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/components/AuthForm.tsx): `frontend/src/components/AuthForm.tsx`

### Client services

- [User preferences](https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/preferences.tsx): `frontend/src/preferences.tsx`
- [Travel API client](https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/api/travel.ts): `frontend/src/api/travel.ts`
- [Destination catalog client](https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/api/destinations.ts): `frontend/src/api/destinations.ts`
- [Route and city lookup](https://github.com/aaravkalia-88/wanderers/blob/main/frontend/src/api/routes.ts): `frontend/src/api/routes.ts`

### API and identity

- [API application](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/main.py): `backend/app/main.py`
- [API route registry](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/api/v1/api.py): `backend/app/api/v1/api.py`
- [Authentication routes](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`
- [Destination routes](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/api/v1/destinations.py): `backend/app/api/v1/destinations.py`
- [Travel routes](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/api/v1/travel.py): `backend/app/api/v1/travel.py`
- [Community routes](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/api/v1/community.py): `backend/app/api/v1/community.py`
- [Journal export](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/api/v1/export.py): `backend/app/api/v1/export.py`
- [AI chat routes](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/api/v1/ai_chat.py): `backend/app/api/v1/ai_chat.py`

### Travel domain

- [Travel progression rules](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/services/travel.py): `backend/app/services/travel.py`
- [Destination records](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/models/destination.py): `backend/app/models/destination.py`
- [Travel records](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/models/travel.py): `backend/app/models/travel.py`
- [User records](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [Community records](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/models/community.py): `backend/app/models/community.py`

### Runtime and persistence

- [Database sessions](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Cache and rate limits](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/core/cache.py): `backend/app/core/cache.py`
- [Runtime configuration](https://github.com/aaravkalia-88/wanderers/blob/main/backend/app/core/config.py): `backend/app/core/config.py`

### Other components

- **Traveler**
- **Open-Meteo services**
- **OSRM routing**
- **Google Maps directions**

## Connections

- Traveler → App shell: uses (evidence: `frontend/src/App.tsx`)
- App shell → Destination discovery: renders (evidence: `frontend/src/App.tsx`)
- App shell → Passport journal: renders (evidence: `frontend/src/App.tsx`)
- App shell → Trip planning: renders (evidence: `frontend/src/App.tsx`)
- App shell → Community stories: renders (evidence: `frontend/src/App.tsx`)
- App shell → Atlas maps: renders (evidence: `frontend/src/App.tsx`)
- App shell → Destination weather: renders (evidence: `frontend/src/App.tsx`)
- App shell → Sign-in form: renders (evidence: `frontend/src/App.tsx`)
- App shell → User preferences: uses (evidence: `frontend/src/App.tsx`)
- App shell → Travel API client: loads passport (evidence: `frontend/src/App.tsx`)
- Sign-in form → Travel API client: signs in (evidence: `frontend/src/components/AuthForm.tsx`)
- App shell → Destination catalog client: uses catalog (evidence: `frontend/src/App.tsx`)
- Atlas maps → Destination catalog client: loads destinations (evidence: `frontend/src/components/atlas/Atlas.tsx`)
- Passport journal → Travel API client: loads journal (evidence: `frontend/src/components/PassportPage.tsx`)
- Community stories → Travel API client: requests stories (evidence: `frontend/src/components/Community.tsx`)
- Trip planning → Route and city lookup: uses routing
- Route and city lookup → Open-Meteo services: geocodes city (evidence: `frontend/src/api/routes.ts`)
- Route and city lookup → OSRM routing: requests road route (evidence: `frontend/src/api/routes.ts`)
- Route and city lookup → Google Maps directions: builds directions link (evidence: `frontend/src/api/routes.ts`)
- Destination weather → Open-Meteo services: gets forecasts
- Travel API client → API application: calls API
- API application → API route registry: mounts routes (evidence: `backend/app/main.py`)
- API route registry → Authentication routes: registers (evidence: `backend/app/api/v1/api.py`)
- API route registry → Destination routes: registers (evidence: `backend/app/api/v1/api.py`)
- API route registry → Travel routes: registers (evidence: `backend/app/api/v1/api.py`)
- API route registry → Community routes: registers (evidence: `backend/app/api/v1/api.py`)
- API route registry → Journal export: registers (evidence: `backend/app/api/v1/api.py`)
- API route registry → AI chat routes: registers (evidence: `backend/app/api/v1/api.py`)
- API application → Database sessions: opens sessions (evidence: `backend/app/main.py`)
- API application → Cache and rate limits: initializes cache (evidence: `backend/app/main.py`)
- API application → Runtime configuration: reads settings (evidence: `backend/app/main.py`)
- Authentication routes → Database sessions: uses sessions (evidence: `backend/app/api/v1/auth.py`)
- Authentication routes → Cache and rate limits: rate limits (evidence: `backend/app/api/v1/auth.py`)
- Authentication routes → Runtime configuration: uses security settings (evidence: `backend/app/api/v1/auth.py`)
- Database sessions → Destination records: stores (evidence: `backend/app/models/destination.py`)
- Database sessions → Travel records: stores (evidence: `backend/app/models/travel.py`)
- Database sessions → User records: stores (evidence: `backend/app/models/user.py`)
- Database sessions → Community records: stores (evidence: `backend/app/models/community.py`)
- API application → Travel progression rules: loads progression rules (evidence: `backend/app/main.py`)
- API application → Destination records: seeds catalog (evidence: `backend/app/main.py`)
