# tanish-2603/locallens architecture

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

- Interactive diagram: https://gitdiagram.com/tanish-2603/locallens
- Repository: https://github.com/tanish-2603/locallens

## Overview

LocalLens is a local-discovery and trip-planning product: travelers explore ranked places, inspect them on a map, and build budget- and time-aware itineraries. The web app also exposes a grounded place guide, community submissions, host experiences, reviews, and account access. FastAPI routers own these domain operations over SQLAlchemy-backed data; ranking and itinerary services provide discovery and planning logic. The source excerpts show the main wiring and several service calls; connections for read-but-unsampled capabilities follow the source index, while frontend-to-backend routing is documented only at a high level.

Main entry points: [`backend/app/main.py`](https://github.com/tanish-2603/locallens/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/db/database.py`](https://github.com/tanish-2603/locallens/blob/main/backend/app/db/database.py) (Relational database), [`backend/app/schemas/schemas.py`](https://github.com/tanish-2603/locallens/blob/main/backend/app/schemas/schemas.py) (Request and response schemas), [`backend/app/api/places.py`](https://github.com/tanish-2603/locallens/blob/main/backend/app/api/places.py) (Place discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Traveler web app"]
  node_webpage["Discovery interface<br/>[page.tsx]"]
  node_map["Interactive map<br/>[MapView.tsx]"]
  node_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and accounts"]
  node_app["FastAPI app<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
end

subgraph group_discovery["Discovery and planning"]
  node_places["Place discovery<br/>[places.py]"]
  node_ranking["Gem ranking<br/>[ranking_service.py]"]
  node_itinerary["Itinerary API<br/>[itinerary.py]"]
  node_planner["Itinerary planner"]
  node_guide["Local guide<br/>[guide.py]"]
  node_guide_service["Grounded answers<br/>[guide_service.py]"]
end

subgraph group_community["Community offerings"]
  node_submissions["Place submissions<br/>[submissions.py]"]
  node_experiences["Host experiences<br/>[experiences.py]"]
end

subgraph group_data["Persistence and domain"]
  node_db[("Relational database<br/>[database.py]")]
  node_models["Domain records<br/>[models.py]"]
  node_schemas["Request and response schemas<br/>[schemas.py]"]
  node_seeding["Schema and seed setup<br/>[init_db.py]"]
  node_seed_data["Curated place catalog<br/>[seed_data.py]"]
end

node_traveler(("Traveler"))

node_traveler -->|"uses"| node_webpage
node_webpage -->|"requests data"| node_client
node_webpage -->|"renders"| node_map
node_map -->|"requests data"| node_client
node_client -.->|"calls API"| node_app
node_app -->|"registers routes"| node_auth
node_app -->|"registers routes"| node_places
node_app -->|"registers routes"| node_itinerary
node_app -->|"registers routes"| node_guide
node_app -->|"registers routes"| node_submissions
node_app -->|"registers routes"| node_experiences
node_app -->|"initializes"| node_seeding
node_places -->|"ranks places"| node_ranking
node_itinerary -->|"generates plans"| node_planner
node_guide -->|"requests answers"| node_guide_service
node_places -->|"queries"| node_db
node_itinerary -->|"queries"| node_db
node_guide -->|"loads place"| node_db
node_submissions -->|"persists submissions"| node_db
node_experiences -->|"queries experiences"| node_db
node_auth -->|"reads and writes"| node_db
node_auth -->|"validates payloads"| node_schemas
node_places -->|"uses schemas"| node_schemas
node_itinerary -->|"uses schemas"| node_schemas
node_guide -->|"uses schemas"| node_schemas
node_submissions -->|"uses schemas"| node_schemas
node_experiences -->|"uses schemas"| node_schemas
node_db -->|"maps records"| node_models
node_seeding -->|"initializes schema"| node_db
node_seeding -->|"loads catalog"| node_seed_data

click node_webpage "https://github.com/tanish-2603/locallens/blob/main/frontend/src/app/page.tsx"
click node_map "https://github.com/tanish-2603/locallens/blob/main/frontend/src/components/MapView.tsx"
click node_client "https://github.com/tanish-2603/locallens/blob/main/frontend/src/lib/api.ts"
click node_app "https://github.com/tanish-2603/locallens/blob/main/backend/app/main.py"
click node_auth "https://github.com/tanish-2603/locallens/blob/main/backend/app/api/auth.py"
click node_places "https://github.com/tanish-2603/locallens/blob/main/backend/app/api/places.py"
click node_ranking "https://github.com/tanish-2603/locallens/blob/main/backend/app/services/ranking_service.py"
click node_itinerary "https://github.com/tanish-2603/locallens/blob/main/backend/app/api/itinerary.py"
click node_planner "https://github.com/tanish-2603/locallens/blob/main/backend/app/services/itinerary_service.py"
click node_guide "https://github.com/tanish-2603/locallens/blob/main/backend/app/api/guide.py"
click node_guide_service "https://github.com/tanish-2603/locallens/blob/main/backend/app/services/guide_service.py"
click node_submissions "https://github.com/tanish-2603/locallens/blob/main/backend/app/api/submissions.py"
click node_experiences "https://github.com/tanish-2603/locallens/blob/main/backend/app/api/experiences.py"
click node_db "https://github.com/tanish-2603/locallens/blob/main/backend/app/db/database.py"
click node_models "https://github.com/tanish-2603/locallens/blob/main/backend/app/db/models.py"
click node_schemas "https://github.com/tanish-2603/locallens/blob/main/backend/app/schemas/schemas.py"
click node_seeding "https://github.com/tanish-2603/locallens/blob/main/backend/app/db/init_db.py"
click node_seed_data "https://github.com/tanish-2603/locallens/blob/main/backend/app/db/seed_data.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_webpage,node_map,node_client toneBlue
class node_app,node_auth toneAmber
class node_places,node_ranking,node_itinerary,node_planner,node_guide,node_guide_service toneMint
class node_submissions,node_experiences toneRose
class node_db,node_models,node_schemas,node_seeding,node_seed_data,node_traveler toneIndigo
```

## Components

### Traveler web app

- [Discovery interface](https://github.com/tanish-2603/locallens/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Interactive map](https://github.com/tanish-2603/locallens/blob/main/frontend/src/components/MapView.tsx): `frontend/src/components/MapView.tsx`
- [API client](https://github.com/tanish-2603/locallens/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and accounts

- [FastAPI app](https://github.com/tanish-2603/locallens/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/tanish-2603/locallens/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`

### Discovery and planning

- [Place discovery](https://github.com/tanish-2603/locallens/blob/main/backend/app/api/places.py): `backend/app/api/places.py`
- [Gem ranking](https://github.com/tanish-2603/locallens/blob/main/backend/app/services/ranking_service.py): `backend/app/services/ranking_service.py`
- [Itinerary API](https://github.com/tanish-2603/locallens/blob/main/backend/app/api/itinerary.py): `backend/app/api/itinerary.py`
- [Itinerary planner](https://github.com/tanish-2603/locallens/blob/main/backend/app/services/itinerary_service.py): `backend/app/services/itinerary_service.py`
- [Local guide](https://github.com/tanish-2603/locallens/blob/main/backend/app/api/guide.py): `backend/app/api/guide.py`
- [Grounded answers](https://github.com/tanish-2603/locallens/blob/main/backend/app/services/guide_service.py): `backend/app/services/guide_service.py`

### Community offerings

- [Place submissions](https://github.com/tanish-2603/locallens/blob/main/backend/app/api/submissions.py): `backend/app/api/submissions.py`
- [Host experiences](https://github.com/tanish-2603/locallens/blob/main/backend/app/api/experiences.py): `backend/app/api/experiences.py`

### Persistence and domain

- [Relational database](https://github.com/tanish-2603/locallens/blob/main/backend/app/db/database.py): `backend/app/db/database.py`
- [Domain records](https://github.com/tanish-2603/locallens/blob/main/backend/app/db/models.py): `backend/app/db/models.py`
- [Request and response schemas](https://github.com/tanish-2603/locallens/blob/main/backend/app/schemas/schemas.py): `backend/app/schemas/schemas.py`
- [Schema and seed setup](https://github.com/tanish-2603/locallens/blob/main/backend/app/db/init_db.py): `backend/app/db/init_db.py`
- [Curated place catalog](https://github.com/tanish-2603/locallens/blob/main/backend/app/db/seed_data.py): `backend/app/db/seed_data.py`

### Other components

- **Traveler**

## Connections

- Traveler → Discovery interface: uses (evidence: `README.md`)
- Discovery interface → API client: requests data (evidence: `frontend/src/app/page.tsx`)
- Discovery interface → Interactive map: renders (evidence: `frontend/src/app/page.tsx`)
- Interactive map → API client: requests data (evidence: `frontend/src/components/MapView.tsx`)
- API client → FastAPI app: calls API
- FastAPI app → Authentication: registers routes (evidence: `backend/app/main.py`)
- FastAPI app → Place discovery: registers routes (evidence: `backend/app/main.py`)
- FastAPI app → Itinerary API: registers routes (evidence: `backend/app/main.py`)
- FastAPI app → Local guide: registers routes (evidence: `backend/app/main.py`)
- FastAPI app → Place submissions: registers routes (evidence: `backend/app/main.py`)
- FastAPI app → Host experiences: registers routes (evidence: `backend/app/main.py`)
- FastAPI app → Schema and seed setup: initializes (evidence: `backend/app/main.py`)
- Place discovery → Gem ranking: ranks places (evidence: `backend/app/api/places.py`)
- Itinerary API → Itinerary planner: generates plans (evidence: `backend/app/api/itinerary.py`)
- Local guide → Grounded answers: requests answers (evidence: `backend/app/api/guide.py`)
- Place discovery → Relational database: queries (evidence: `backend/app/api/places.py`)
- Itinerary API → Relational database: queries (evidence: `backend/app/api/itinerary.py`)
- Local guide → Relational database: loads place (evidence: `backend/app/api/guide.py`)
- Place submissions → Relational database: persists submissions (evidence: `backend/app/api/submissions.py`)
- Host experiences → Relational database: queries experiences (evidence: `backend/app/api/experiences.py`)
- Authentication → Relational database: reads and writes (evidence: `backend/app/api/auth.py`)
- Authentication → Request and response schemas: validates payloads (evidence: `backend/app/api/auth.py`)
- Place discovery → Request and response schemas: uses schemas (evidence: `backend/app/api/places.py`)
- Itinerary API → Request and response schemas: uses schemas (evidence: `backend/app/api/itinerary.py`)
- Local guide → Request and response schemas: uses schemas (evidence: `backend/app/api/guide.py`)
- Place submissions → Request and response schemas: uses schemas (evidence: `backend/app/api/submissions.py`)
- Host experiences → Request and response schemas: uses schemas (evidence: `backend/app/api/experiences.py`)
- Relational database → Domain records: maps records (evidence: `backend/app/db/models.py`)
- Schema and seed setup → Relational database: initializes schema (evidence: `backend/app/db/init_db.py`)
- Schema and seed setup → Curated place catalog: loads catalog (evidence: `backend/app/db/init_db.py`)