# loamysand/betterbearings architecture

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

- Interactive diagram: https://gitdiagram.com/loamysand/betterbearings
- Repository: https://github.com/loamysand/betterbearings

## Overview

BetterBearings is a browser-based street-learning game with optional accounts and saved neighborhood street sets. A player opens the game, receives a street prompt, and selects its geometry on a map; guests can play random areas, while signed-in users can create and manage saved sets. The map and quiz hooks divide game state, area selection, and street rendering. The server separately handles authentication, street-set persistence, and a public street-selection API. The README documents browser-fetched Overpass data and map tiles; unsampled client request details are not inferred here.

Main entry points: [`client/src/components/Game.jsx`](https://github.com/loamysand/betterbearings/blob/main/client/src/components/Game.jsx) (Street quiz), [`client/src/App.jsx`](https://github.com/loamysand/betterbearings/blob/main/client/src/App.jsx) (React routes), [`server/app.js`](https://github.com/loamysand/betterbearings/blob/main/server/app.js) (Express app), [`client/src/contexts/AuthContext.jsx`](https://github.com/loamysand/betterbearings/blob/main/client/src/contexts/AuthContext.jsx) (Auth state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client_game["Game and maps"]
  node_app["React routes<br/>[App.jsx]"]
  node_home["Game page<br/>[Home.jsx]"]
  node_game["Street quiz<br/>[Game.jsx]"]
  node_game_state["Quiz state<br/>[useGameState.js]"]
  node_area["Quiz area<br/>[useQuizArea.js]"]
  node_map_hooks["Map rendering<br/>[useLeafletMap.js]"]
  node_polylines["Street geometry"]
  node_quiz_area_ui["Area selector<br/>[QuizAreaModule.jsx]"]
  node_streets_client["Street loading<br/>[useStreets.js]"]
  node_tile_layer["Tile layer<br/>[tileLayer.js]"]
end

subgraph group_client_account["Accounts"]
  node_auth_ui["Sign-in dialog<br/>[AuthModal.jsx]"]
  node_auth_context["Auth state<br/>[AuthContext.jsx]"]
  node_sets_list["Street-set list<br/>[StreetSets.jsx]"]
  node_sets_detail["Street-set detail"]
  node_sets_create["Create street set"]
end

subgraph group_server_api["API services"]
  node_auth_routes["Auth endpoints<br/>[authRoutes.js]"]
  node_set_routes["Street-set endpoints<br/>[streetSetRoutes.js]"]
  node_street_routes["Street query endpoint<br/>[streetRoutes.js]"]
  node_server_app["Express app<br/>[app.js]"]
end

subgraph group_server_data["Street data"]
  node_street_set_store["Street-set queries<br/>[streetSets.js]"]
  node_street_store["Street queries<br/>[streets.js]"]
  node_postgres[("PostGIS database<br/>[pool.js]")]
end

node_player(("Player"))
node_overpass["Overpass API"]
node_tiles["Map tiles"]

node_player -->|"opens"| node_app
node_app -->|"routes to"| node_home
node_home -->|"renders"| node_game
node_game -->|"uses"| node_game_state
node_game -->|"uses"| node_area
node_game -->|"uses"| node_map_hooks
node_game -->|"uses"| node_polylines
node_game -->|"renders"| node_quiz_area_ui
node_game -->|"loads streets"| node_streets_client
node_streets_client -->|"fetches data"| node_overpass
node_map_hooks -->|"adds base layer"| node_tile_layer
node_tile_layer -->|"loads tiles"| node_tiles
node_app -->|"provides auth"| node_auth_context
node_auth_ui -->|"calls login/signup"| node_auth_context
node_auth_context -->|"requests auth"| node_auth_routes
node_app -->|"routes to"| node_sets_list
node_app -->|"routes to"| node_sets_detail
node_sets_list -->|"opens create flow"| node_sets_create
node_player -->|"signs in"| node_auth_ui
node_server_app -->|"mounts"| node_auth_routes
node_server_app -->|"mounts"| node_set_routes
node_server_app -->|"mounts"| node_street_routes
node_auth_routes -->|"queries"| node_postgres
node_set_routes -->|"calls"| node_street_set_store
node_street_routes -->|"calls"| node_street_store
node_street_set_store -->|"queries"| node_postgres
node_street_store -->|"queries"| node_postgres

click node_app "https://github.com/loamysand/betterbearings/blob/main/client/src/App.jsx"
click node_home "https://github.com/loamysand/betterbearings/blob/main/client/src/pages/Home.jsx"
click node_game "https://github.com/loamysand/betterbearings/blob/main/client/src/components/Game.jsx"
click node_game_state "https://github.com/loamysand/betterbearings/blob/main/client/src/hooks/useGameState.js"
click node_area "https://github.com/loamysand/betterbearings/blob/main/client/src/hooks/useQuizArea.js"
click node_map_hooks "https://github.com/loamysand/betterbearings/blob/main/client/src/hooks/useLeafletMap.js"
click node_polylines "https://github.com/loamysand/betterbearings/blob/main/client/src/hooks/useStreetPolylines.js"
click node_quiz_area_ui "https://github.com/loamysand/betterbearings/blob/main/client/src/components/QuizAreaModule.jsx"
click node_streets_client "https://github.com/loamysand/betterbearings/blob/main/client/src/hooks/useStreets.js"
click node_tile_layer "https://github.com/loamysand/betterbearings/blob/main/client/src/utils/tileLayer.js"
click node_auth_ui "https://github.com/loamysand/betterbearings/blob/main/client/src/components/AuthModal.jsx"
click node_auth_context "https://github.com/loamysand/betterbearings/blob/main/client/src/contexts/AuthContext.jsx"
click node_sets_list "https://github.com/loamysand/betterbearings/blob/main/client/src/pages/StreetSets.jsx"
click node_sets_detail "https://github.com/loamysand/betterbearings/blob/main/client/src/pages/StreetSetDetail.jsx"
click node_sets_create "https://github.com/loamysand/betterbearings/blob/main/client/src/components/CreateStreetSetModal.jsx"
click node_auth_routes "https://github.com/loamysand/betterbearings/blob/main/server/routes/authRoutes.js"
click node_set_routes "https://github.com/loamysand/betterbearings/blob/main/server/routes/streetSetRoutes.js"
click node_street_routes "https://github.com/loamysand/betterbearings/blob/main/server/routes/streetRoutes.js"
click node_server_app "https://github.com/loamysand/betterbearings/blob/main/server/app.js"
click node_street_set_store "https://github.com/loamysand/betterbearings/blob/main/server/db/streetSets.js"
click node_street_store "https://github.com/loamysand/betterbearings/blob/main/server/db/streets.js"
click node_postgres "https://github.com/loamysand/betterbearings/blob/main/server/db/pool.js"

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_home,node_game,node_game_state,node_area,node_map_hooks,node_polylines,node_quiz_area_ui,node_streets_client,node_tile_layer toneBlue
class node_auth_ui,node_auth_context,node_sets_list,node_sets_detail,node_sets_create toneAmber
class node_auth_routes,node_set_routes,node_street_routes,node_server_app,node_overpass toneMint
class node_street_set_store,node_street_store,node_postgres toneRose
class node_player,node_tiles toneIndigo
```

## Components

### Game and maps

- [React routes](https://github.com/loamysand/betterbearings/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Game page](https://github.com/loamysand/betterbearings/blob/main/client/src/pages/Home.jsx): `client/src/pages/Home.jsx`
- [Street quiz](https://github.com/loamysand/betterbearings/blob/main/client/src/components/Game.jsx): `client/src/components/Game.jsx`
- [Quiz state](https://github.com/loamysand/betterbearings/blob/main/client/src/hooks/useGameState.js): `client/src/hooks/useGameState.js`
- [Quiz area](https://github.com/loamysand/betterbearings/blob/main/client/src/hooks/useQuizArea.js): `client/src/hooks/useQuizArea.js`
- [Map rendering](https://github.com/loamysand/betterbearings/blob/main/client/src/hooks/useLeafletMap.js): `client/src/hooks/useLeafletMap.js`
- [Street geometry](https://github.com/loamysand/betterbearings/blob/main/client/src/hooks/useStreetPolylines.js): `client/src/hooks/useStreetPolylines.js`
- [Area selector](https://github.com/loamysand/betterbearings/blob/main/client/src/components/QuizAreaModule.jsx): `client/src/components/QuizAreaModule.jsx`
- [Street loading](https://github.com/loamysand/betterbearings/blob/main/client/src/hooks/useStreets.js): `client/src/hooks/useStreets.js`
- [Tile layer](https://github.com/loamysand/betterbearings/blob/main/client/src/utils/tileLayer.js): `client/src/utils/tileLayer.js`

### Accounts

- [Sign-in dialog](https://github.com/loamysand/betterbearings/blob/main/client/src/components/AuthModal.jsx): `client/src/components/AuthModal.jsx`
- [Auth state](https://github.com/loamysand/betterbearings/blob/main/client/src/contexts/AuthContext.jsx): `client/src/contexts/AuthContext.jsx`
- [Street-set list](https://github.com/loamysand/betterbearings/blob/main/client/src/pages/StreetSets.jsx): `client/src/pages/StreetSets.jsx`
- [Street-set detail](https://github.com/loamysand/betterbearings/blob/main/client/src/pages/StreetSetDetail.jsx): `client/src/pages/StreetSetDetail.jsx`
- [Create street set](https://github.com/loamysand/betterbearings/blob/main/client/src/components/CreateStreetSetModal.jsx): `client/src/components/CreateStreetSetModal.jsx`

### API services

- [Auth endpoints](https://github.com/loamysand/betterbearings/blob/main/server/routes/authRoutes.js): `server/routes/authRoutes.js`
- [Street-set endpoints](https://github.com/loamysand/betterbearings/blob/main/server/routes/streetSetRoutes.js): `server/routes/streetSetRoutes.js`
- [Street query endpoint](https://github.com/loamysand/betterbearings/blob/main/server/routes/streetRoutes.js): `server/routes/streetRoutes.js`
- [Express app](https://github.com/loamysand/betterbearings/blob/main/server/app.js): `server/app.js`

### Street data

- [Street-set queries](https://github.com/loamysand/betterbearings/blob/main/server/db/streetSets.js): `server/db/streetSets.js`
- [Street queries](https://github.com/loamysand/betterbearings/blob/main/server/db/streets.js): `server/db/streets.js`
- [PostGIS database](https://github.com/loamysand/betterbearings/blob/main/server/db/pool.js): `server/db/pool.js`

### Other components

- **Player**
- **Overpass API**
- **Map tiles**

## Connections

- Player → React routes: opens (evidence: `client/src/App.jsx`)
- React routes → Game page: routes to (evidence: `client/src/App.jsx`)
- Game page → Street quiz: renders (evidence: `client/src/pages/Home.jsx`)
- Street quiz → Quiz state: uses (evidence: `client/src/components/Game.jsx`)
- Street quiz → Quiz area: uses (evidence: `client/src/components/Game.jsx`)
- Street quiz → Map rendering: uses (evidence: `client/src/components/Game.jsx`)
- Street quiz → Street geometry: uses (evidence: `client/src/components/Game.jsx`)
- Street quiz → Area selector: renders (evidence: `client/src/components/Game.jsx`)
- Street quiz → Street loading: loads streets (evidence: `client/src/components/Game.jsx`)
- Street loading → Overpass API: fetches data (evidence: `README.md`)
- Map rendering → Tile layer: adds base layer (evidence: `client/src/hooks/useLeafletMap.js`)
- Tile layer → Map tiles: loads tiles (evidence: `README.md`)
- React routes → Auth state: provides auth (evidence: `client/src/App.jsx`)
- Sign-in dialog → Auth state: calls login/signup (evidence: `client/src/components/AuthModal.jsx`)
- Auth state → Auth endpoints: requests auth (evidence: `client/src/contexts/AuthContext.jsx`)
- React routes → Street-set list: routes to (evidence: `client/src/App.jsx`)
- React routes → Street-set detail: routes to (evidence: `client/src/App.jsx`)
- Street-set list → Create street set: opens create flow (evidence: `client/src/pages/StreetSets.jsx`)
- Player → Sign-in dialog: signs in (evidence: `client/src/components/AuthModal.jsx`)
- Express app → Auth endpoints: mounts (evidence: `server/app.js`)
- Express app → Street-set endpoints: mounts (evidence: `server/app.js`)
- Express app → Street query endpoint: mounts (evidence: `server/app.js`)
- Auth endpoints → PostGIS database: queries (evidence: `server/routes/authRoutes.js`)
- Street-set endpoints → Street-set queries: calls (evidence: `server/routes/streetSetRoutes.js`)
- Street query endpoint → Street queries: calls (evidence: `server/routes/streetRoutes.js`)
- Street-set queries → PostGIS database: queries (evidence: `server/db/streetSets.js`)
- Street queries → PostGIS database: queries (evidence: `server/db/streets.js`)