# aj-omnimatrix/gazetteer-demo architecture

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

- Interactive diagram: https://gitdiagram.com/aj-omnimatrix/gazetteer-demo
- Repository: https://github.com/aj-omnimatrix/gazetteer-demo

## Overview

Gazetteer is a personal travel catalogue: visitors discover curated places, search or filter them, and—after signing in—save visits and review travel statistics. The main runtime path runs from catalogue views through client data/mutations and server actions to the database abstraction, with seeded in-memory data as a documented fallback. The graph also preserves authentication, location-of-the-day, nearby lookup, directions, and the place-authoring capability. Some links are documented but their implementation was not sampled, so those links are dashed and marked unverified.

Main entry points: [`components/ExploreView.tsx`](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/components/ExploreView.tsx) (Explore view), [`components/ListView.tsx`](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/components/ListView.tsx) (Travel list), [`lib/auth.ts`](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/lib/auth.ts) (Identity and sessions), [`app/actions.ts`](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/app/actions.ts) (Server actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Place discovery"]
  node_explore_page["Explore page<br/>[page.tsx]"]
  node_explore_view["Explore view<br/>[ExploreView.tsx]"]
  node_lotd_page["Featured page<br/>[page.tsx]"]
  node_lotd_view["Featured view<br/>[LotdView.tsx]"]
end

subgraph group_visits["Travel records"]
  node_visit_button["Visit control"]
  node_list_page["Travel list page<br/>[page.tsx]"]
  node_list_view["Travel list<br/>[ListView.tsx]"]
  node_stats_index["Travel statistics<br/>[segment-tree.ts]"]
end

subgraph group_services["Application services"]
  node_catalog_hook["Catalog client<br/>[use-catalog.ts]"]
  node_search_index["Prefix search<br/>[trie.ts]"]
  node_nearby_index["Nearby lookup<br/>[kd-tree.ts]"]
  node_auth_dialog["Sign-in dialog<br/>[AuthDialog.tsx]"]
  node_auth_service["Identity and sessions<br/>[auth.ts]"]
  node_server_actions["Server actions<br/>[actions.ts]"]
  node_catalog_api["Catalog endpoint<br/>[route.ts]"]
end

subgraph group_catalogue["Catalogue data"]
  node_query_service["Catalog queries<br/>[queries.ts]"]
  node_database_pool["SQL connection<br/>[index.ts]"]
  node_memory_store[("Memory fallback<br/>[memory.ts]")]
  node_seed_catalog["Curated places<br/>[seed-data.ts]"]
  node_place_authoring["Place authoring<br/>[add-location.ts]"]
  node_image_processing["Photo processing<br/>[image-search.ts]"]
end

node_traveler(("Traveler"))
node_maps["Google Maps"]

node_traveler -->|"opens"| node_explore_page
node_explore_page -->|"renders"| node_explore_view
node_traveler -.->|"opens"| node_lotd_page
node_lotd_page -->|"renders"| node_lotd_view
node_explore_view -->|"loads catalog"| node_catalog_hook
node_lotd_view -->|"loads catalog"| node_catalog_hook
node_explore_view -->|"searches"| node_search_index
node_traveler -.->|"requests nearby"| node_nearby_index
node_explore_view -->|"renders"| node_visit_button
node_lotd_view -->|"renders"| node_visit_button
node_traveler -.->|"opens"| node_list_page
node_list_page -->|"renders"| node_list_view
node_list_view -->|"loads catalog"| node_catalog_hook
node_list_view -->|"searches"| node_search_index
node_list_view -.->|"calculates stats"| node_stats_index
node_traveler -->|"signs in"| node_auth_dialog
node_auth_dialog -->|"submits identity"| node_server_actions
node_catalog_hook -->|"records visits"| node_server_actions
node_server_actions -->|"checks session"| node_auth_service
node_auth_service -->|"uses SQL"| node_database_pool
node_auth_service -->|"uses fallback"| node_memory_store
node_server_actions -->|"updates visits"| node_query_service
node_catalog_api -->|"gets session"| node_auth_service
node_catalog_api -->|"loads catalog"| node_query_service
node_query_service -->|"queries SQL"| node_database_pool
node_query_service -->|"uses fallback"| node_memory_store
node_memory_store -->|"initializes from"| node_seed_catalog
node_traveler -.->|"opens directions"| node_maps
node_place_authoring -->|"processes photos"| node_image_processing
node_place_authoring -->|"updates entries"| node_seed_catalog

click node_explore_page "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/app/explore/page.tsx"
click node_explore_view "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/components/ExploreView.tsx"
click node_lotd_page "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/app/page.tsx"
click node_lotd_view "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/components/LotdView.tsx"
click node_catalog_hook "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/hooks/use-catalog.ts"
click node_search_index "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/lib/ads/trie.ts"
click node_nearby_index "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/lib/ads/kd-tree.ts"
click node_visit_button "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/components/VisitStatusButton.tsx"
click node_list_page "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/app/list/page.tsx"
click node_list_view "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/components/ListView.tsx"
click node_stats_index "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/lib/ads/segment-tree.ts"
click node_auth_dialog "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/components/AuthDialog.tsx"
click node_auth_service "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/lib/auth.ts"
click node_server_actions "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/app/actions.ts"
click node_catalog_api "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/app/api/catalog/route.ts"
click node_query_service "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/db/queries.ts"
click node_database_pool "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/db/index.ts"
click node_memory_store "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/db/memory.ts"
click node_seed_catalog "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/db/seed-data.ts"
click node_place_authoring "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/db/add-location.ts"
click node_image_processing "https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/lib/image-search.ts"

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_explore_page,node_explore_view,node_lotd_page,node_lotd_view toneBlue
class node_visit_button,node_list_page,node_list_view,node_stats_index toneAmber
class node_catalog_hook,node_search_index,node_nearby_index,node_auth_dialog,node_auth_service,node_server_actions,node_catalog_api toneMint
class node_query_service,node_database_pool,node_memory_store,node_seed_catalog,node_place_authoring,node_image_processing toneRose
class node_traveler,node_maps toneIndigo
```

## Components

### Place discovery

- [Explore page](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/app/explore/page.tsx): `app/explore/page.tsx`
- [Explore view](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/components/ExploreView.tsx): `components/ExploreView.tsx`
- [Featured page](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/app/page.tsx): `app/page.tsx`
- [Featured view](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/components/LotdView.tsx): `components/LotdView.tsx`

### Travel records

- [Visit control](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/components/VisitStatusButton.tsx): `components/VisitStatusButton.tsx`
- [Travel list page](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/app/list/page.tsx): `app/list/page.tsx`
- [Travel list](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/components/ListView.tsx): `components/ListView.tsx`
- [Travel statistics](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/lib/ads/segment-tree.ts): `lib/ads/segment-tree.ts`

### Application services

- [Catalog client](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/hooks/use-catalog.ts): `hooks/use-catalog.ts`
- [Prefix search](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/lib/ads/trie.ts): `lib/ads/trie.ts`
- [Nearby lookup](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/lib/ads/kd-tree.ts): `lib/ads/kd-tree.ts`
- [Sign-in dialog](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/components/AuthDialog.tsx): `components/AuthDialog.tsx`
- [Identity and sessions](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/lib/auth.ts): `lib/auth.ts`
- [Server actions](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/app/actions.ts): `app/actions.ts`
- [Catalog endpoint](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/app/api/catalog/route.ts): `app/api/catalog/route.ts`

### Catalogue data

- [Catalog queries](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/db/queries.ts): `db/queries.ts`
- [SQL connection](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/db/index.ts): `db/index.ts`
- [Memory fallback](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/db/memory.ts): `db/memory.ts`
- [Curated places](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/db/seed-data.ts): `db/seed-data.ts`
- [Place authoring](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/db/add-location.ts): `db/add-location.ts`
- [Photo processing](https://github.com/aj-omnimatrix/gazetteer-demo/blob/main/lib/image-search.ts): `lib/image-search.ts`

### Other components

- **Traveler**
- **Google Maps**

## Connections

- Traveler → Explore page: opens
- Explore page → Explore view: renders (evidence: `app/explore/page.tsx`)
- Traveler → Featured page: opens
- Featured page → Featured view: renders (evidence: `app/page.tsx`)
- Explore view → Catalog client: loads catalog (evidence: `components/ExploreView.tsx`)
- Featured view → Catalog client: loads catalog (evidence: `components/LotdView.tsx`)
- Explore view → Prefix search: searches (evidence: `components/ExploreView.tsx`)
- Traveler → Nearby lookup: requests nearby
- Explore view → Visit control: renders (evidence: `components/ExploreView.tsx`)
- Featured view → Visit control: renders (evidence: `components/LotdView.tsx`)
- Traveler → Travel list page: opens
- Travel list page → Travel list: renders (evidence: `app/list/page.tsx`)
- Travel list → Catalog client: loads catalog (evidence: `components/ListView.tsx`)
- Travel list → Prefix search: searches (evidence: `components/ListView.tsx`)
- Travel list → Travel statistics: calculates stats (evidence: `components/ListView.tsx`)
- Traveler → Sign-in dialog: signs in (evidence: `components/AuthDialog.tsx`)
- Sign-in dialog → Server actions: submits identity (evidence: `components/AuthDialog.tsx`)
- Catalog client → Server actions: records visits (evidence: `hooks/use-catalog.ts`)
- Server actions → Identity and sessions: checks session (evidence: `app/actions.ts`)
- Identity and sessions → SQL connection: uses SQL (evidence: `lib/auth.ts`)
- Identity and sessions → Memory fallback: uses fallback (evidence: `lib/auth.ts`)
- Server actions → Catalog queries: updates visits (evidence: `app/actions.ts`)
- Catalog endpoint → Identity and sessions: gets session (evidence: `app/api/catalog/route.ts`)
- Catalog endpoint → Catalog queries: loads catalog (evidence: `app/api/catalog/route.ts`)
- Catalog queries → SQL connection: queries SQL (evidence: `db/queries.ts`)
- Catalog queries → Memory fallback: uses fallback (evidence: `db/queries.ts`)
- Memory fallback → Curated places: initializes from (evidence: `db/memory.ts`)
- Traveler → Google Maps: opens directions
- Place authoring → Photo processing: processes photos (evidence: `db/add-location.ts`)
- Place authoring → Curated places: updates entries (evidence: `db/add-location.ts`)
