# amenmnx/bean-beacon architecture

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

- Interactive diagram: https://gitdiagram.com/amenmnx/bean-beacon
- Repository: https://github.com/amenmnx/bean-beacon

## Overview

Bean Beacon is a café-discovery application: users explore nearby places, search and filter results, inspect café profiles, and save favorites or contribute reviews. The frontend also supports café submissions and administration; the backend serves these workflows with MongoDB-backed records and OpenStreetMap integrations. The graph reflects the sampled routes and controller calls plus README-documented capabilities. Several frontend component-to-page/API links and backend startup wiring were not excerpted, so those relationships are omitted rather than inferred.

Main entry points: [`bean-beacon-frontend/src/lib/api.ts`](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/lib/api.ts) (API client), [`bean-beacon-frontend/src/App.tsx`](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/App.tsx) (Web app routes), [`bean-beacon-frontend/src/pages/Index.tsx`](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/pages/Index.tsx) (Cafe discovery), [`bean-beacon-backend/src/routes/cafeRoutes.ts`](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/routes/cafeRoutes.ts) (Cafe endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Discovery frontend"]
  node_app["Web app routes<br/>[App.tsx]"]
  node_explore["Cafe discovery<br/>[Index.tsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_manage["Cafe management<br/>[Manage.tsx]"]
  node_profile["Cafe profile<br/>[CafeProfile.tsx]"]
  node_map["Interactive map<br/>[CafeMap.tsx]"]
  node_search["Search and filters<br/>[SearchBar.tsx]"]
  node_recommendui["Preference recommender"]
  node_reviewsui["Reviews interface<br/>[CafeReviews.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API workflows"]
  node_cafe_routes["Cafe endpoints<br/>[cafeRoutes.ts]"]
  node_recommend_controller["Recommendation handler"]
  node_auth_routes["Auth endpoints<br/>[authRoutes.ts]"]
  node_admin_routes["Admin endpoints<br/>[adminRoutes.ts]"]
  node_favorite_routes["Favorite endpoints<br/>[favoriteRoutes.ts]"]
  node_rating_routes["Rating endpoints<br/>[ratingRoutes.ts]"]
end

subgraph group_places["Place data"]
  node_cafe_controller["Cafe operations<br/>[cafeController.ts]"]
  node_recommend_service["Preference matching"]
  node_overpass["Place data lookup<br/>[overpassService.ts]"]
  node_geocoding["Address geocoding"]
end

subgraph group_accounts["Accounts and community"]
  node_auth_controller["Authentication<br/>[authController.ts]"]
  node_favorites_controller["Favorites operations"]
  node_ratings_controller["Ratings and reviews"]
  node_admin_controller["Admin operations<br/>[adminController.ts]"]
  node_auth_middleware["Token authorization<br/>[auth.ts]"]
end

subgraph group_persistence["Persistence"]
  node_cafe_store[("Cafe records<br/>[Cafe.ts]")]
  node_user_store[("User records<br/>[User.ts]")]
  node_favorite_store[("Favorite records<br/>[Favorite.ts]")]
  node_rating_store[("Rating records<br/>[Rating.ts]")]
end

node_user(("Visitor"))
node_osm{{"OpenStreetMap services"}}
node_mongo[("MongoDB")]
node_nominatim{{"Nominatim"}}

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_explore
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_manage
node_app -->|"routes to"| node_profile
node_explore -.->|"displays on"| node_map
node_explore -.->|"filters with"| node_search
node_explore -.->|"offers"| node_recommendui
node_profile -.->|"shows"| node_reviewsui
node_explore -.->|"requests data"| node_api_client
node_profile -.->|"requests details"| node_api_client
node_manage -.->|"submits changes"| node_api_client
node_api_client -->|"calls API"| node_cafe_routes
node_api_client -->|"calls API"| node_auth_routes
node_api_client -->|"calls API"| node_favorite_routes
node_api_client -->|"calls API"| node_rating_routes
node_cafe_routes -->|"dispatches"| node_cafe_controller
node_cafe_routes -->|"dispatches"| node_recommend_controller
node_recommend_controller -->|"ranks cafes"| node_recommend_service
node_cafe_controller -->|"reads and writes"| node_cafe_store
node_cafe_controller -->|"fetches places"| node_overpass
node_cafe_controller -->|"geocodes addresses"| node_geocoding
node_overpass -->|"queries places"| node_osm
node_geocoding -->|"resolves addresses"| node_nominatim
node_auth_routes -->|"dispatches"| node_auth_controller
node_auth_controller -->|"reads and writes"| node_user_store
node_favorite_routes -->|"dispatches"| node_favorites_controller
node_favorites_controller -->|"reads and writes"| node_favorite_store
node_favorites_controller -->|"looks up cafes"| node_cafe_store
node_rating_routes -->|"dispatches"| node_ratings_controller
node_ratings_controller -->|"reads and writes"| node_rating_store
node_ratings_controller -->|"updates averages"| node_cafe_store
node_admin_routes -->|"dispatches"| node_admin_controller
node_admin_routes -->|"dispatches"| node_ratings_controller
node_admin_routes -->|"guards endpoints"| node_auth_middleware
node_cafe_routes -->|"guards writes"| node_auth_middleware
node_favorite_routes -->|"guards endpoints"| node_auth_middleware
node_rating_routes -->|"guards endpoints"| node_auth_middleware
node_cafe_store -->|"persists"| node_mongo
node_user_store -->|"persists"| node_mongo
node_favorite_store -->|"persists"| node_mongo
node_rating_store -->|"persists"| node_mongo

click node_app "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/App.tsx"
click node_explore "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/pages/Index.tsx"
click node_dashboard "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/pages/Dashboard.tsx"
click node_manage "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/pages/Manage.tsx"
click node_profile "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/pages/CafeProfile.tsx"
click node_map "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/components/CafeMap.tsx"
click node_search "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/components/SearchBar.tsx"
click node_recommendui "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/components/CafeRecommender.tsx"
click node_reviewsui "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/components/CafeReviews.tsx"
click node_api_client "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/lib/api.ts"
click node_cafe_routes "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/routes/cafeRoutes.ts"
click node_cafe_controller "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/controllers/cafeController.ts"
click node_recommend_controller "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/controllers/recommendationController.ts"
click node_recommend_service "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/services/recommendationService.ts"
click node_overpass "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/services/overpassService.ts"
click node_geocoding "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/services/geocodingService.ts"
click node_auth_controller "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/controllers/authController.ts"
click node_auth_routes "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/routes/authRoutes.ts"
click node_favorites_controller "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/controllers/favoriteController.ts"
click node_ratings_controller "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/controllers/ratingController.ts"
click node_admin_controller "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/controllers/adminController.ts"
click node_admin_routes "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/routes/adminRoutes.ts"
click node_favorite_routes "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/routes/favoriteRoutes.ts"
click node_rating_routes "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/routes/ratingRoutes.ts"
click node_auth_middleware "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/middleware/auth.ts"
click node_cafe_store "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/models/Cafe.ts"
click node_user_store "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/models/User.ts"
click node_favorite_store "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/models/Favorite.ts"
click node_rating_store "https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/models/Rating.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_app,node_explore,node_dashboard,node_manage,node_profile,node_map,node_search,node_recommendui,node_reviewsui,node_api_client toneBlue
class node_cafe_routes,node_recommend_controller,node_auth_routes,node_admin_routes,node_favorite_routes,node_rating_routes,node_mongo toneAmber
class node_cafe_controller,node_recommend_service,node_overpass,node_geocoding toneMint
class node_auth_controller,node_favorites_controller,node_ratings_controller,node_admin_controller,node_auth_middleware toneRose
class node_cafe_store,node_user_store,node_favorite_store,node_rating_store,node_user,node_osm,node_nominatim toneIndigo
```

## Components

### Discovery frontend

- [Web app routes](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/App.tsx): `bean-beacon-frontend/src/App.tsx`
- [Cafe discovery](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/pages/Index.tsx): `bean-beacon-frontend/src/pages/Index.tsx`
- [Dashboard](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/pages/Dashboard.tsx): `bean-beacon-frontend/src/pages/Dashboard.tsx`
- [Cafe management](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/pages/Manage.tsx): `bean-beacon-frontend/src/pages/Manage.tsx`
- [Cafe profile](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/pages/CafeProfile.tsx): `bean-beacon-frontend/src/pages/CafeProfile.tsx`
- [Interactive map](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/components/CafeMap.tsx): `bean-beacon-frontend/src/components/CafeMap.tsx`
- [Search and filters](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/components/SearchBar.tsx): `bean-beacon-frontend/src/components/SearchBar.tsx`
- [Preference recommender](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/components/CafeRecommender.tsx): `bean-beacon-frontend/src/components/CafeRecommender.tsx`
- [Reviews interface](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/components/CafeReviews.tsx): `bean-beacon-frontend/src/components/CafeReviews.tsx`
- [API client](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-frontend/src/lib/api.ts): `bean-beacon-frontend/src/lib/api.ts`

### API workflows

- [Cafe endpoints](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/routes/cafeRoutes.ts): `bean-beacon-backend/src/routes/cafeRoutes.ts`
- [Recommendation handler](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/controllers/recommendationController.ts): `bean-beacon-backend/src/controllers/recommendationController.ts`
- [Auth endpoints](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/routes/authRoutes.ts): `bean-beacon-backend/src/routes/authRoutes.ts`
- [Admin endpoints](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/routes/adminRoutes.ts): `bean-beacon-backend/src/routes/adminRoutes.ts`
- [Favorite endpoints](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/routes/favoriteRoutes.ts): `bean-beacon-backend/src/routes/favoriteRoutes.ts`
- [Rating endpoints](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/routes/ratingRoutes.ts): `bean-beacon-backend/src/routes/ratingRoutes.ts`

### Place data

- [Cafe operations](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/controllers/cafeController.ts): `bean-beacon-backend/src/controllers/cafeController.ts`
- [Preference matching](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/services/recommendationService.ts): `bean-beacon-backend/src/services/recommendationService.ts`
- [Place data lookup](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/services/overpassService.ts): `bean-beacon-backend/src/services/overpassService.ts`
- [Address geocoding](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/services/geocodingService.ts): `bean-beacon-backend/src/services/geocodingService.ts`

### Accounts and community

- [Authentication](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/controllers/authController.ts): `bean-beacon-backend/src/controllers/authController.ts`
- [Favorites operations](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/controllers/favoriteController.ts): `bean-beacon-backend/src/controllers/favoriteController.ts`
- [Ratings and reviews](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/controllers/ratingController.ts): `bean-beacon-backend/src/controllers/ratingController.ts`
- [Admin operations](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/controllers/adminController.ts): `bean-beacon-backend/src/controllers/adminController.ts`
- [Token authorization](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/middleware/auth.ts): `bean-beacon-backend/src/middleware/auth.ts`

### Persistence

- [Cafe records](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/models/Cafe.ts): `bean-beacon-backend/src/models/Cafe.ts`
- [User records](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/models/User.ts): `bean-beacon-backend/src/models/User.ts`
- [Favorite records](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/models/Favorite.ts): `bean-beacon-backend/src/models/Favorite.ts`
- [Rating records](https://github.com/amenmnx/bean-beacon/blob/main/bean-beacon-backend/src/models/Rating.ts): `bean-beacon-backend/src/models/Rating.ts`

### Other components

- **Visitor**
- **OpenStreetMap services**
- **MongoDB**
- **Nominatim**

## Connections

- Visitor → Web app routes: uses
- Web app routes → Cafe discovery: routes to (evidence: `bean-beacon-frontend/src/App.tsx`)
- Web app routes → Dashboard: routes to (evidence: `bean-beacon-frontend/src/App.tsx`)
- Web app routes → Cafe management: routes to (evidence: `bean-beacon-frontend/src/App.tsx`)
- Web app routes → Cafe profile: routes to (evidence: `bean-beacon-frontend/src/App.tsx`)
- Cafe discovery → Interactive map: displays on
- Cafe discovery → Search and filters: filters with
- Cafe discovery → Preference recommender: offers
- Cafe profile → Reviews interface: shows
- Cafe discovery → API client: requests data
- Cafe profile → API client: requests details
- Cafe management → API client: submits changes
- API client → Cafe endpoints: calls API
- API client → Auth endpoints: calls API
- API client → Favorite endpoints: calls API
- API client → Rating endpoints: calls API
- Cafe endpoints → Cafe operations: dispatches (evidence: `bean-beacon-backend/src/routes/cafeRoutes.ts`)
- Cafe endpoints → Recommendation handler: dispatches (evidence: `bean-beacon-backend/src/routes/cafeRoutes.ts`)
- Recommendation handler → Preference matching: ranks cafes (evidence: `bean-beacon-backend/src/controllers/recommendationController.ts`)
- Cafe operations → Cafe records: reads and writes (evidence: `bean-beacon-backend/src/controllers/cafeController.ts`)
- Cafe operations → Place data lookup: fetches places (evidence: `bean-beacon-backend/src/controllers/cafeController.ts`)
- Cafe operations → Address geocoding: geocodes addresses (evidence: `bean-beacon-backend/src/controllers/cafeController.ts`)
- Place data lookup → OpenStreetMap services: queries places (evidence: `bean-beacon-backend/src/services/overpassService.ts`)
- Address geocoding → Nominatim: resolves addresses
- Auth endpoints → Authentication: dispatches (evidence: `bean-beacon-backend/src/routes/authRoutes.ts`)
- Authentication → User records: reads and writes (evidence: `bean-beacon-backend/src/controllers/authController.ts`)
- Favorite endpoints → Favorites operations: dispatches (evidence: `bean-beacon-backend/src/routes/favoriteRoutes.ts`)
- Favorites operations → Favorite records: reads and writes (evidence: `bean-beacon-backend/src/controllers/favoriteController.ts`)
- Favorites operations → Cafe records: looks up cafes (evidence: `bean-beacon-backend/src/controllers/favoriteController.ts`)
- Rating endpoints → Ratings and reviews: dispatches (evidence: `bean-beacon-backend/src/routes/ratingRoutes.ts`)
- Ratings and reviews → Rating records: reads and writes (evidence: `bean-beacon-backend/src/controllers/ratingController.ts`)
- Ratings and reviews → Cafe records: updates averages (evidence: `bean-beacon-backend/src/controllers/ratingController.ts`)
- Admin endpoints → Admin operations: dispatches (evidence: `bean-beacon-backend/src/routes/adminRoutes.ts`)
- Admin endpoints → Ratings and reviews: dispatches (evidence: `bean-beacon-backend/src/routes/adminRoutes.ts`)
- Admin endpoints → Token authorization: guards endpoints (evidence: `bean-beacon-backend/src/routes/adminRoutes.ts`)
- Cafe endpoints → Token authorization: guards writes (evidence: `bean-beacon-backend/src/routes/cafeRoutes.ts`)
- Favorite endpoints → Token authorization: guards endpoints (evidence: `bean-beacon-backend/src/routes/favoriteRoutes.ts`)
- Rating endpoints → Token authorization: guards endpoints (evidence: `bean-beacon-backend/src/routes/ratingRoutes.ts`)
- Cafe records → MongoDB: persists
- User records → MongoDB: persists
- Favorite records → MongoDB: persists
- Rating records → MongoDB: persists
