# taibeled/jetlaghideandseek architecture

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

- Interactive diagram: https://gitdiagram.com/taibeled/jetlaghideandseek
- Repository: https://github.com/taibeled/jetlaghideandseek

## Overview

#### Purpose and Entry Points
This is a client-side interactive map generator for evaluating Hide and Seek locations in *Jet Lag: The Game*. Astro hosts the application shell; React/TSX components provide the interactive UI. The primary entry route is `src/pages/index.astro`, wrapped by `src/layouts/Layout.astro`; PWA setup is in `src/pwa.ts`.

#### Application Composition
`src/components/Map.tsx` is the central map-facing UI, coordinating rendered map state, overlays, and user interactions. Supporting controls collect locations and geometry (`src/components/PlacePicker.tsx`, `src/components/PolygonDraw.tsx`, `src/components/DraggableMarkers.tsx`) and expose map-specific operations such as printing and fullscreen (`src/components/MapPrint.tsx`, `src/components/LeafletFullScreenButton.tsx`).

#### State, Setup, and Question Selection
Shared application context is defined in `src/lib/context.ts`. Question configuration is presented through the sidebar/card layer: `src/components/QuestionSidebar.tsx`, `src/components/QuestionCards.tsx`, and `src/components/cards/base.tsx`. Initialization, built-in presets, and user-defined presets form a separate configuration boundary in `src/components/CustomInitDialog.tsx`, `src/components/PresetsDialog.tsx`, and `src/components/CustomPresets.tsx`.

#### Question Evaluation Domain
The question engine is organized by gameplay category under `src/maps/questions/`: matching, measuring, radius, thermometer, and tentacles (`src/maps/questions/matching.ts`, `src/maps/questions/measuring.ts`, `src/maps/questions/tentacles.ts`). These modules turn selected question parameters and geographic datasets into map-visible eligibility/measurement results. Shared domain schemas and exports reside in `src/maps/schema.ts` and `src/maps/index.ts`, providing a boundary between React presentation and geospatial computation.

#### Geospatial Processing Pipeline
Reusable spatial algorithms are isolated from UI and external requests in `src/maps/geo-utils/`. Operators and special-case logic (`src/maps/geo-utils/operators.ts`, `src/maps/geo-utils/special.ts`) support transformations and filtering; station-specific processing is in `src/maps/geo-utils/stationManipulations.ts`; Voronoi calculations are in `src/maps/geo-utils/voronoi.ts`. User-drawn or picked points, lines, and polygons flow into this layer, then into question evaluators and map overlays.

#### Data Access and External Boundaries
`src/maps/api/index.ts` is the map-data access facade. It separates geocoding, Overpass queries, imports, and caching (`src/maps/api/geocode.ts`, `src/maps/api/overpass.ts`, `src/maps/api/cache.ts`) from calculation code. Geographic input/output types and constants are centralized in `src/maps/api/types.ts` and `src/maps/api/constants.ts`. The checked-in coastline dataset, `public/coastline50.geojson`, is a local geospatial dependency for coastline-distance questions. External map/geographic services are consumed through the API layer rather than UI components.

#### Runtime and Delivery
The project runs on Node.js with pnpm and is built as an Astro application configured by `astro.config.mjs`; TypeScript React components constitute the interactive runtime. Styling is global/Tailwind-based (`src/styles/globals.css`, `tailwind.config.mjs`). Deployment automation is defined in `.github/workflows/deploy.yml`. The PWA module indicates installable/offline-oriented browser delivery, while runtime geographic lookup remains an external-service boundary.

Main entry points: [`src/components/Map.tsx`](https://github.com/taibeled/jetlaghideandseek/blob/master/src/components/Map.tsx) (Interactive map), [`src/lib/context.ts`](https://github.com/taibeled/jetlaghideandseek/blob/master/src/lib/context.ts) (Shared app context), [`src/maps/api/index.ts`](https://github.com/taibeled/jetlaghideandseek/blob/master/src/maps/api/index.ts) (Map data facade), [`src/pages/index.astro`](https://github.com/taibeled/jetlaghideandseek/blob/master/src/pages/index.astro) (Home route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Astro & UI"]
  node_entry["Home route<br/>Astro route<br/>[index.astro]"]
  node_layout["Application layout<br/>Astro layout<br/>[Layout.astro]"]
  node_map["Interactive map<br/>React map UI<br/>[Map.tsx]"]
  node_location_input["Location &amp; geometry input<br/>React controls"]
  node_map_operations["Map operations<br/>React controls"]
end

subgraph group_state["Configuration"]
  node_context["Shared app context<br/>React context<br/>[context.ts]"]
  node_questions_ui["Question selection<br/>React sidebar/cards"]
  node_presets["Initialization &amp; presets<br/>React dialogs"]
end

subgraph group_domain["Map Domain"]
  node_domain_boundary{{"Map domain boundary<br/>Schemas &amp; exports"}}
  node_question_engine["Question evaluators<br/>Gameplay rules"]
  node_geo_utils["Spatial algorithms<br/>Geospatial processing"]
  node_station_processing["Station processing<br/>Geospatial operator"]
  node_voronoi["Voronoi calculation<br/>Geospatial operator<br/>[voronoi.ts]"]
end

subgraph group_data["Geographic Data"]
  node_api{{"Map data facade<br/>Data access API<br/>[index.ts]"}}
  node_api_sources["Geocoding, Overpass &amp; cache<br/>API adapters"]
  node_api_contract["Geographic contracts<br/>Types &amp; constants"]
  node_coastline[("Coastline dataset<br/>GeoJSON asset")]
end

subgraph group_delivery["Delivery"]
  node_pwa["PWA setup<br/>Browser delivery<br/>[pwa.ts]"]
  node_build["Astro build &amp; styling<br/>Build configuration"]
  node_deploy["Deployment workflow<br/>CI deployment<br/>[deploy.yml]"]
end

node_entry -->|"renders within"| node_layout
node_layout -->|"hosts"| node_map
node_map -->|"reads and updates"| node_context
node_questions_ui -->|"configures"| node_context
node_presets -->|"initializes"| node_context
node_context -->|"drives UI state"| node_map
node_location_input -->|"supplies geometry"| node_map
node_map_operations -->|"acts on"| node_map
node_map -->|"requests evaluation"| node_domain_boundary
node_context -->|"supplies parameters"| node_domain_boundary
node_domain_boundary -->|"routes questions"| node_question_engine
node_question_engine -->|"uses spatial operations"| node_geo_utils
node_geo_utils -.->|"includes"| node_station_processing
node_geo_utils -.->|"includes"| node_voronoi
node_question_engine -->|"loads geographic data"| node_api
node_api -->|"delegates requests"| node_api_sources
node_api -->|"uses contracts"| node_api_contract
node_question_engine -->|"uses for distance rules"| node_coastline
node_question_engine -->|"returns overlays"| node_map
node_build -->|"builds"| node_entry
node_pwa -.->|"enables browser delivery"| node_entry
node_deploy -->|"deploys build"| node_build

click node_entry "https://github.com/taibeled/jetlaghideandseek/blob/master/src/pages/index.astro"
click node_layout "https://github.com/taibeled/jetlaghideandseek/blob/master/src/layouts/Layout.astro"
click node_map "https://github.com/taibeled/jetlaghideandseek/blob/master/src/components/Map.tsx"
click node_context "https://github.com/taibeled/jetlaghideandseek/blob/master/src/lib/context.ts"
click node_station_processing "https://github.com/taibeled/jetlaghideandseek/blob/master/src/maps/geo-utils/stationManipulations.ts"
click node_voronoi "https://github.com/taibeled/jetlaghideandseek/blob/master/src/maps/geo-utils/voronoi.ts"
click node_api "https://github.com/taibeled/jetlaghideandseek/blob/master/src/maps/api/index.ts"
click node_coastline "https://github.com/taibeled/jetlaghideandseek/blob/master/public/coastline50.geojson"
click node_pwa "https://github.com/taibeled/jetlaghideandseek/blob/master/src/pwa.ts"
click node_deploy "https://github.com/taibeled/jetlaghideandseek/blob/master/.github/workflows/deploy.yml"

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_entry,node_layout,node_map,node_location_input,node_map_operations toneBlue
class node_context,node_questions_ui,node_presets toneAmber
class node_domain_boundary,node_question_engine,node_geo_utils,node_station_processing,node_voronoi toneMint
class node_api,node_api_sources,node_api_contract,node_coastline toneRose
class node_pwa,node_build,node_deploy toneIndigo
```

## Components

### Astro & UI

Browser application shell and interactive controls.

- [Home route](https://github.com/taibeled/jetlaghideandseek/blob/master/src/pages/index.astro): Astro route · Primary application entry point. · `src/pages/index.astro`
- [Application layout](https://github.com/taibeled/jetlaghideandseek/blob/master/src/layouts/Layout.astro): Astro layout · `src/layouts/Layout.astro`
- [Interactive map](https://github.com/taibeled/jetlaghideandseek/blob/master/src/components/Map.tsx): React map UI · Coordinates map state, overlays, and interactions. · `src/components/Map.tsx`
- **Location & geometry input**: React controls · Place picking, polygon drawing, and draggable markers.
- **Map operations**: React controls · Print and fullscreen map actions.

### Configuration

Shared state, question selection, and presets.

- [Shared app context](https://github.com/taibeled/jetlaghideandseek/blob/master/src/lib/context.ts): React context · Holds shared application state. · `src/lib/context.ts`
- **Question selection**: React sidebar/cards · Presents question configuration.
- **Initialization & presets**: React dialogs · Provides built-in and user-defined setups.

### Map Domain

Question evaluation and spatial computation.

- **Map domain boundary**: Schemas & exports · Separates presentation from geospatial computation.
- **Question evaluators**: Gameplay rules · Computes eligibility and measurements by question category.
- **Spatial algorithms**: Geospatial processing · Transforms and filters user geography for evaluation.
- [Station processing](https://github.com/taibeled/jetlaghideandseek/blob/master/src/maps/geo-utils/stationManipulations.ts): Geospatial operator · `src/maps/geo-utils/stationManipulations.ts`
- [Voronoi calculation](https://github.com/taibeled/jetlaghideandseek/blob/master/src/maps/geo-utils/voronoi.ts): Geospatial operator · `src/maps/geo-utils/voronoi.ts`

### Geographic Data

External lookup facade and local geographic assets.

- [Map data facade](https://github.com/taibeled/jetlaghideandseek/blob/master/src/maps/api/index.ts): Data access API · Isolates external geographic requests, imports, and caching. · `src/maps/api/index.ts`
- **Geocoding, Overpass & cache**: API adapters
- **Geographic contracts**: Types & constants
- [Coastline dataset](https://github.com/taibeled/jetlaghideandseek/blob/master/public/coastline50.geojson): GeoJSON asset · Local dependency for coastline-distance questions. · `public/coastline50.geojson`

### Delivery

Build, styling, PWA, and deployment.

- [PWA setup](https://github.com/taibeled/jetlaghideandseek/blob/master/src/pwa.ts): Browser delivery · Supports installable and offline-oriented delivery. · `src/pwa.ts`
- **Astro build & styling**: Build configuration · Astro application and global Tailwind styling.
- [Deployment workflow](https://github.com/taibeled/jetlaghideandseek/blob/master/.github/workflows/deploy.yml): CI deployment · `.github/workflows/deploy.yml`

## Connections

- Home route → Application layout: renders within
- Application layout → Interactive map: hosts
- Interactive map → Shared app context: reads and updates
- Question selection → Shared app context: configures
- Initialization & presets → Shared app context: initializes
- Shared app context → Interactive map: drives UI state
- Location & geometry input → Interactive map: supplies geometry
- Map operations → Interactive map: acts on
- Interactive map → Map domain boundary: requests evaluation
- Shared app context → Map domain boundary: supplies parameters
- Map domain boundary → Question evaluators: routes questions
- Question evaluators → Spatial algorithms: uses spatial operations
- Spatial algorithms → Station processing: includes
- Spatial algorithms → Voronoi calculation: includes
- Question evaluators → Map data facade: loads geographic data
- Map data facade → Geocoding, Overpass & cache: delegates requests
- Map data facade → Geographic contracts: uses contracts
- Question evaluators → Coastline dataset: uses for distance rules
- Question evaluators → Interactive map: returns overlays
- Astro build & styling → Home route: builds
- PWA setup → Home route: enables browser delivery
- Deployment workflow → Astro build & styling: deploys build