# pompomiiiii/cafe-scout architecture

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

- Interactive diagram: https://gitdiagram.com/pompomiiiii/cafe-scout
- Repository: https://github.com/pompomiiiii/cafe-scout

## Overview

Café Scout is a location-based café discovery web app. Its main workflow is to obtain the user's location, retrieve and rank nearby cafés, then present them in a filterable list and interactive Google Map with synchronized selection. A separate chat workflow sends café context and a request to Gemini, then displays suggested cafés that can be selected in the app. The README documents the product capabilities; edges are limited to relationships visible in excerpts or explicitly documented.

Main entry points: [`cafe-scout/src/App.jsx`](https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/App.jsx) (App coordinator), [`cafe-scout/src/hooks/useCafes.js`](https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/hooks/useCafes.js) (Cafe data hook), [`cafe-scout/src/components/ChatPanel.jsx`](https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/components/ChatPanel.jsx) (Chat panel), [`cafe-scout/src/services/geminiApi.js`](https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/services/geminiApi.js) (Gemini service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Café discovery"]
  node_location["Location hook<br/>[useLocation.js]"]
  node_places["Places search<br/>[placesApi.js]"]
  node_cafe_hook["Cafe data hook<br/>[useCafes.js]"]
  node_filters["Search filters<br/>[FilterBar.jsx]"]
end

subgraph group_presentation["Browse and map"]
  node_list["Café list<br/>[CafeList.jsx]"]
  node_card["Café card<br/>[CafeCard.jsx]"]
  node_map["Interactive map<br/>[MapView.jsx]"]
end

subgraph group_assistant["AI assistant"]
  node_chat["Chat panel<br/>[ChatPanel.jsx]"]
  node_gemini["Gemini service<br/>[geminiApi.js]"]
  node_prompt["Café prompt<br/>[cafePrompt.js]"]
end

subgraph group_experience["App experience"]
  node_app["App coordinator<br/>[App.jsx]"]
  node_bean["Bean character<br/>[BeanCharacter.jsx]"]
end

node_visitor(("User"))
node_google_places{{"Google Places"}}
node_google_maps{{"Google Maps"}}
node_gemini_api{{"Gemini API"}}

node_visitor -->|"uses"| node_app
node_app -->|"reads location"| node_location
node_location -->|"requests GPS"| node_visitor
node_app -->|"loads cafés"| node_cafe_hook
node_cafe_hook -->|"fetches nearby"| node_places
node_places -->|"searches cafés"| node_google_places
node_cafe_hook -->|"applies preferences"| node_filters
node_app -->|"renders"| node_filters
node_app -->|"renders"| node_list
node_list -->|"renders cards"| node_card
node_app -->|"renders"| node_map
node_map -->|"loads map"| node_google_maps
node_app -->|"renders"| node_chat
node_app -->|"renders"| node_bean
node_bean -->|"toggles chat"| node_app
node_chat -->|"asks"| node_gemini
node_gemini -->|"builds prompt"| node_prompt
node_gemini -->|"generates response"| node_gemini_api
node_chat -->|"selects suggestion"| node_app
node_app -->|"passes selection"| node_map
node_app -.->|"passes selection"| node_list

click node_app "https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/App.jsx"
click node_location "https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/hooks/useLocation.js"
click node_places "https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/services/placesApi.js"
click node_cafe_hook "https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/hooks/useCafes.js"
click node_filters "https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/components/FilterBar.jsx"
click node_list "https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/components/CafeList.jsx"
click node_card "https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/components/CafeCard.jsx"
click node_map "https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/components/MapView.jsx"
click node_chat "https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/components/ChatPanel.jsx"
click node_gemini "https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/services/geminiApi.js"
click node_prompt "https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/services/prompts/cafePrompt.js"
click node_bean "https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/components/BeanCharacter.jsx"

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_location,node_places,node_cafe_hook,node_filters,node_visitor toneBlue
class node_list,node_card,node_map toneAmber
class node_chat,node_gemini,node_prompt,node_gemini_api toneMint
class node_app,node_bean toneRose
class node_google_places,node_google_maps toneIndigo
```

## Components

### Café discovery

- [Location hook](https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/hooks/useLocation.js): `cafe-scout/src/hooks/useLocation.js`
- [Places search](https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/services/placesApi.js): `cafe-scout/src/services/placesApi.js`
- [Cafe data hook](https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/hooks/useCafes.js): `cafe-scout/src/hooks/useCafes.js`
- [Search filters](https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/components/FilterBar.jsx): `cafe-scout/src/components/FilterBar.jsx`

### Browse and map

- [Café list](https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/components/CafeList.jsx): `cafe-scout/src/components/CafeList.jsx`
- [Café card](https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/components/CafeCard.jsx): `cafe-scout/src/components/CafeCard.jsx`
- [Interactive map](https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/components/MapView.jsx): `cafe-scout/src/components/MapView.jsx`

### AI assistant

- [Chat panel](https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/components/ChatPanel.jsx): `cafe-scout/src/components/ChatPanel.jsx`
- [Gemini service](https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/services/geminiApi.js): `cafe-scout/src/services/geminiApi.js`
- [Café prompt](https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/services/prompts/cafePrompt.js): `cafe-scout/src/services/prompts/cafePrompt.js`

### App experience

- [App coordinator](https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/App.jsx): `cafe-scout/src/App.jsx`
- [Bean character](https://github.com/pompomiiiii/cafe-scout/blob/main/cafe-scout/src/components/BeanCharacter.jsx): `cafe-scout/src/components/BeanCharacter.jsx`

### Other components

- **User**
- **Google Places**
- **Google Maps**
- **Gemini API**

## Connections

- User → App coordinator: uses
- App coordinator → Location hook: reads location (evidence: `cafe-scout/src/App.jsx`)
- Location hook → User: requests GPS (evidence: `cafe-scout/src/hooks/useLocation.js`)
- App coordinator → Cafe data hook: loads cafés (evidence: `cafe-scout/src/App.jsx`)
- Cafe data hook → Places search: fetches nearby (evidence: `cafe-scout/src/hooks/useCafes.js`)
- Places search → Google Places: searches cafés (evidence: `cafe-scout/src/services/placesApi.js`)
- Cafe data hook → Search filters: applies preferences
- App coordinator → Search filters: renders (evidence: `cafe-scout/src/App.jsx`)
- App coordinator → Café list: renders (evidence: `cafe-scout/src/App.jsx`)
- Café list → Café card: renders cards (evidence: `cafe-scout/src/components/CafeList.jsx`)
- App coordinator → Interactive map: renders (evidence: `cafe-scout/src/App.jsx`)
- Interactive map → Google Maps: loads map (evidence: `cafe-scout/src/components/MapView.jsx`)
- App coordinator → Chat panel: renders (evidence: `cafe-scout/src/App.jsx`)
- App coordinator → Bean character: renders (evidence: `cafe-scout/src/App.jsx`)
- Bean character → App coordinator: toggles chat (evidence: `cafe-scout/src/App.jsx`)
- Chat panel → Gemini service: asks (evidence: `cafe-scout/src/components/ChatPanel.jsx`)
- Gemini service → Café prompt: builds prompt (evidence: `cafe-scout/src/services/geminiApi.js`)
- Gemini service → Gemini API: generates response (evidence: `cafe-scout/src/services/geminiApi.js`)
- Chat panel → App coordinator: selects suggestion (evidence: `cafe-scout/src/App.jsx`)
- App coordinator → Interactive map: passes selection (evidence: `cafe-scout/src/App.jsx`)
- App coordinator → Café list: passes selection (evidence: `cafe-scout/src/App.jsx`)
