# rayhannr/places-to-go architecture

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

- Interactive diagram: https://gitdiagram.com/rayhannr/places-to-go
- Repository: https://github.com/rayhannr/places-to-go

## Overview

Places To Go is a personal food-place tracker with browser, Telegram, CLI, and MCP entry points. The main workflow is to ask for recommendations or manage a place; AI tools perform the relevant discovery or tracker operation, using mapping services and place storage where needed, and the result returns through the initiating interface. The README documents recommendations, visit and priority tracking, geolocation, a decision wheel, and closure cleanup. Some subsystem wiring is based on documented capabilities because its source was not sampled.

Main entry points: [`lib/ai/tools.ts`](https://github.com/rayhannr/places-to-go/blob/master/lib/ai/tools.ts) (AI tool registry), [`lib/googleSheets.ts`](https://github.com/rayhannr/places-to-go/blob/master/lib/googleSheets.ts) (Google Sheets adapter), [`app/api/cron/check-closures/route.ts`](https://github.com/rayhannr/places-to-go/blob/master/app/api/cron/check-closures/route.ts) (Closure checker), [`app/api/chat/route.ts`](https://github.com/rayhannr/places-to-go/blob/master/app/api/chat/route.ts) (Chat endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_web_app["Tracker UI<br/>[page.tsx]"]
  node_chat_ui["Chat interface"]
  node_wheel["Places wheel"]
  node_cli["CLI entry<br/>[index.ts]"]
  node_chat_api["Chat endpoint<br/>[route.ts]"]
  node_places_api["Places endpoint<br/>[route.ts]"]
  node_telegram_api["Telegram webhook<br/>[route.ts]"]
  node_mcp_api["MCP endpoint<br/>[route.ts]"]
  node_auth["Request authentication<br/>[auth.ts]"]
  node_bot["Telegram bot<br/>[bot.ts]"]
  node_cli_commands["CLI commands<br/>[commands.ts]"]
end

subgraph group_workflow["AI and Place Workflows"]
  node_ai_tools["AI tool registry<br/>[tools.ts]"]
  node_recommendations["Recommendations<br/>[logic.ts]"]
  node_place_operations["Place operations<br/>[places.ts]"]
  node_location["Location and routes<br/>[location.ts]"]
  node_closure_job["Closure checker<br/>[route.ts]"]
end

subgraph group_data["Place Data"]
  node_sheets["Google Sheets adapter<br/>[googleSheets.ts]"]
  node_demo_store[("Demo place store<br/>[demo-store.ts]")]
end

subgraph group_integrations["External Services"]
  node_google_sheets[("Google Sheets")]
  node_blob[("Vercel Blob")]
  node_mistral["Mistral AI"]
  node_google_maps["Google Maps APIs"]
  node_redis[("Upstash Redis")]
  node_telegram["Telegram"]
end

node_browser(("Browser user"))
node_telegram_user(("Telegram user"))
node_cli_user(("CLI user"))
node_mcp_client(("MCP client"))

node_browser -->|"uses"| node_web_app
node_web_app -->|"presents"| node_chat_ui
node_chat_ui -->|"sends chat"| node_chat_api
node_chat_ui -->|"loads places"| node_places_api
node_web_app -->|"offers spins"| node_wheel
node_chat_api -->|"checks access"| node_auth
node_places_api -->|"checks access"| node_auth
node_chat_api -->|"dispatches tools"| node_ai_tools
node_chat_api -->|"streams chat"| node_mistral
node_ai_tools -->|"uses"| node_recommendations
node_ai_tools -->|"uses"| node_place_operations
node_ai_tools -->|"uses"| node_location
node_recommendations -->|"reads places"| node_sheets
node_place_operations -->|"manages places"| node_sheets
node_location -->|"gets routes"| node_google_maps
node_places_api -->|"reads places"| node_sheets
node_sheets -->|"reads and writes"| node_google_sheets
node_sheets -.->|"uses in demo"| node_demo_store
node_demo_store -.->|"stores data"| node_blob
node_telegram_user -->|"messages"| node_telegram
node_telegram -->|"sends webhook"| node_telegram_api
node_telegram_api -->|"dispatches updates"| node_bot
node_bot -->|"uses tools"| node_ai_tools
node_bot -->|"sends replies"| node_telegram
node_cli_user -->|"runs"| node_cli
node_cli -->|"dispatches commands"| node_cli_commands
node_cli_commands -->|"runs tools"| node_ai_tools
node_mcp_client -->|"calls tools"| node_mcp_api
node_mcp_api -->|"checks access"| node_auth
node_mcp_api -->|"registers and invokes"| node_ai_tools
node_closure_job -->|"reads and updates"| node_sheets
node_closure_job -->|"checks status"| node_google_maps
node_closure_job -->|"tracks checks"| node_redis
node_closure_job -->|"sends alerts"| node_telegram

click node_web_app "https://github.com/rayhannr/places-to-go/blob/master/app/page.tsx"
click node_chat_ui "https://github.com/rayhannr/places-to-go/tree/master/components/chat"
click node_wheel "https://github.com/rayhannr/places-to-go/blob/master/components/wheel-of-places.tsx"
click node_cli "https://github.com/rayhannr/places-to-go/blob/master/cli/index.ts"
click node_chat_api "https://github.com/rayhannr/places-to-go/blob/master/app/api/chat/route.ts"
click node_places_api "https://github.com/rayhannr/places-to-go/blob/master/app/api/places/route.ts"
click node_telegram_api "https://github.com/rayhannr/places-to-go/blob/master/app/api/telegram/route.ts"
click node_mcp_api "https://github.com/rayhannr/places-to-go/blob/master/app/api/mcp/route.ts"
click node_auth "https://github.com/rayhannr/places-to-go/blob/master/lib/auth.ts"
click node_bot "https://github.com/rayhannr/places-to-go/blob/master/lib/bot.ts"
click node_cli_commands "https://github.com/rayhannr/places-to-go/blob/master/cli/commands.ts"
click node_ai_tools "https://github.com/rayhannr/places-to-go/blob/master/lib/ai/tools.ts"
click node_recommendations "https://github.com/rayhannr/places-to-go/blob/master/lib/ai/tools/logic.ts"
click node_place_operations "https://github.com/rayhannr/places-to-go/blob/master/lib/ai/tools/places.ts"
click node_location "https://github.com/rayhannr/places-to-go/blob/master/lib/ai/tools/location.ts"
click node_closure_job "https://github.com/rayhannr/places-to-go/blob/master/app/api/cron/check-closures/route.ts"
click node_sheets "https://github.com/rayhannr/places-to-go/blob/master/lib/googleSheets.ts"
click node_demo_store "https://github.com/rayhannr/places-to-go/blob/master/lib/demo-store.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_web_app,node_chat_ui,node_wheel,node_cli,node_chat_api,node_places_api,node_telegram_api,node_mcp_api,node_auth,node_bot,node_cli_commands,node_browser,node_telegram_user,node_cli_user,node_mcp_client toneBlue
class node_ai_tools,node_recommendations,node_place_operations,node_location,node_closure_job toneAmber
class node_sheets,node_demo_store toneMint
class node_google_sheets,node_blob,node_mistral,node_google_maps,node_redis,node_telegram toneRose
```

## Components

### User Interfaces

- [Tracker UI](https://github.com/rayhannr/places-to-go/blob/master/app/page.tsx): `app/page.tsx`
- [Chat interface](https://github.com/rayhannr/places-to-go/tree/master/components/chat): `components/chat`
- [Places wheel](https://github.com/rayhannr/places-to-go/blob/master/components/wheel-of-places.tsx): `components/wheel-of-places.tsx`
- [CLI entry](https://github.com/rayhannr/places-to-go/blob/master/cli/index.ts): `cli/index.ts`
- [Chat endpoint](https://github.com/rayhannr/places-to-go/blob/master/app/api/chat/route.ts): `app/api/chat/route.ts`
- [Places endpoint](https://github.com/rayhannr/places-to-go/blob/master/app/api/places/route.ts): `app/api/places/route.ts`
- [Telegram webhook](https://github.com/rayhannr/places-to-go/blob/master/app/api/telegram/route.ts): `app/api/telegram/route.ts`
- [MCP endpoint](https://github.com/rayhannr/places-to-go/blob/master/app/api/mcp/route.ts): `app/api/mcp/route.ts`
- [Request authentication](https://github.com/rayhannr/places-to-go/blob/master/lib/auth.ts): `lib/auth.ts`
- [Telegram bot](https://github.com/rayhannr/places-to-go/blob/master/lib/bot.ts): `lib/bot.ts`
- [CLI commands](https://github.com/rayhannr/places-to-go/blob/master/cli/commands.ts): `cli/commands.ts`

### AI and Place Workflows

- [AI tool registry](https://github.com/rayhannr/places-to-go/blob/master/lib/ai/tools.ts): `lib/ai/tools.ts`
- [Recommendations](https://github.com/rayhannr/places-to-go/blob/master/lib/ai/tools/logic.ts): `lib/ai/tools/logic.ts`
- [Place operations](https://github.com/rayhannr/places-to-go/blob/master/lib/ai/tools/places.ts): `lib/ai/tools/places.ts`
- [Location and routes](https://github.com/rayhannr/places-to-go/blob/master/lib/ai/tools/location.ts): `lib/ai/tools/location.ts`
- [Closure checker](https://github.com/rayhannr/places-to-go/blob/master/app/api/cron/check-closures/route.ts): `app/api/cron/check-closures/route.ts`

### Place Data

- [Google Sheets adapter](https://github.com/rayhannr/places-to-go/blob/master/lib/googleSheets.ts): `lib/googleSheets.ts`
- [Demo place store](https://github.com/rayhannr/places-to-go/blob/master/lib/demo-store.ts): `lib/demo-store.ts`

### External Services

- **Google Sheets**
- **Vercel Blob**
- **Mistral AI**
- **Google Maps APIs**
- **Upstash Redis**
- **Telegram**

### Other components

- **Browser user**
- **Telegram user**
- **CLI user**
- **MCP client**

## Connections

- Browser user → Tracker UI: uses
- Tracker UI → Chat interface: presents
- Chat interface → Chat endpoint: sends chat
- Chat interface → Places endpoint: loads places
- Tracker UI → Places wheel: offers spins
- Chat endpoint → Request authentication: checks access
- Places endpoint → Request authentication: checks access
- Chat endpoint → AI tool registry: dispatches tools
- Chat endpoint → Mistral AI: streams chat
- AI tool registry → Recommendations: uses
- AI tool registry → Place operations: uses
- AI tool registry → Location and routes: uses
- Recommendations → Google Sheets adapter: reads places
- Place operations → Google Sheets adapter: manages places
- Location and routes → Google Maps APIs: gets routes
- Places endpoint → Google Sheets adapter: reads places
- Google Sheets adapter → Google Sheets: reads and writes
- Google Sheets adapter → Demo place store: uses in demo
- Demo place store → Vercel Blob: stores data
- Telegram user → Telegram: messages
- Telegram → Telegram webhook: sends webhook
- Telegram webhook → Telegram bot: dispatches updates
- Telegram bot → AI tool registry: uses tools
- Telegram bot → Telegram: sends replies
- CLI user → CLI entry: runs
- CLI entry → CLI commands: dispatches commands
- CLI commands → AI tool registry: runs tools
- MCP client → MCP endpoint: calls tools
- MCP endpoint → Request authentication: checks access
- MCP endpoint → AI tool registry: registers and invokes
- Closure checker → Google Sheets adapter: reads and updates
- Closure checker → Google Maps APIs: checks status
- Closure checker → Upstash Redis: tracks checks
- Closure checker → Telegram: sends alerts