# zubir2k/homeassistant-jejakmasjid architecture

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

- Interactive diagram: https://gitdiagram.com/zubir2k/homeassistant-jejakmasjid
- Repository: https://github.com/zubir2k/homeassistant-jejakmasjid

## Overview

Jejak Masjid is a Home Assistant integration for discovering nearby mosques and surau. Users configure a search radius and refresh interval; the integration tracks GPS for people and Home, fetches and caches nearby places, then exposes per-location sensors and a find_nearby action. Home Assistant dashboards can use the bundled interactive map card. The coordinator, service handler, and card registration are distinct runtime paths. The README documents card capabilities beyond the sampled frontend excerpts; unsampled implementation details and their internal links are not inferred.

Main entry points: [`custom_components/jejakmasjid/coordinator.py`](https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/coordinator.py) (Refresh coordinator), [`custom_components/jejakmasjid/__init__.py`](https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/__init__.py) (Integration lifecycle), [`custom_components/jejakmasjid/services.py`](https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/services.py) (find_nearby service), [`custom_components/jejakmasjid/config_flow.py`](https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/config_flow.py) (Configuration flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup &amp; lifecycle"]
  node_config["Configuration flow<br/>[config_flow.py]"]
  node_integration["Integration lifecycle<br/>[__init__.py]"]
  node_constants["Settings &amp; constants<br/>[const.py]"]
end

subgraph group_discovery["Place discovery"]
  node_locations["Person &amp; Home GPS<br/>[coordinator.py]"]
  node_coordinator["Refresh coordinator<br/>[coordinator.py]"]
  node_cache[("Search cache<br/>[coordinator.py]")]
  node_api_client["Jejak Masjid client"]
  node_ranked_places["Nearby place results<br/>[coordinator.py]"]
end

subgraph group_ha["Home Assistant outputs"]
  node_find_service["find_nearby service<br/>[services.py]"]
  node_entity_base["Entity base<br/>[entity.py]"]
  node_sensors["Location sensors<br/>[sensor.py]"]
  node_diagnostics["Redacted diagnostics<br/>[diagnostics.py]"]
end

subgraph group_dashboard["Dashboard map"]
  node_card_registration["Card registration"]
  node_card["Interactive map card"]
  node_leaflet["Leaflet map library<br/>[leaflet.js]"]
end

node_user(("Integrator"))
node_ha_core["Home Assistant"]
node_upstream["Jejak Masjid API"]
node_dashboard_ui["Lovelace dashboard"]
node_service_user(("Automation or Assist"))

node_user -->|"configures"| node_config
node_config -->|"checks connection"| node_upstream
node_config -->|"creates entry"| node_ha_core
node_ha_core -->|"sets up entry"| node_integration
node_integration -->|"starts refresh"| node_coordinator
node_integration -->|"registers service"| node_find_service
node_integration -->|"registers card"| node_card_registration
node_integration -->|"forwards platform"| node_sensors
node_coordinator -->|"reads coordinates"| node_locations
node_coordinator -->|"loads and saves"| node_cache
node_coordinator -->|"fetches places"| node_api_client
node_api_client -.->|"queries"| node_upstream
node_coordinator -->|"ranks results"| node_ranked_places
node_find_service -->|"fetches places"| node_api_client
node_find_service -->|"filters and limits"| node_ranked_places
node_service_user -->|"requests search"| node_find_service
node_sensors -->|"reads updates"| node_coordinator
node_sensors -->|"uses base"| node_entity_base
node_diagnostics -->|"reads status"| node_coordinator
node_card_registration -->|"serves and registers"| node_dashboard_ui
node_dashboard_ui -->|"loads resource"| node_card
node_card -->|"reads sensor states"| node_ha_core
node_card -->|"renders map with"| node_leaflet

click node_config "https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/config_flow.py"
click node_integration "https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/__init__.py"
click node_constants "https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/const.py"
click node_locations "https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/coordinator.py"
click node_coordinator "https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/coordinator.py"
click node_cache "https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/coordinator.py"
click node_ranked_places "https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/coordinator.py"
click node_find_service "https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/services.py"
click node_entity_base "https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/entity.py"
click node_sensors "https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/sensor.py"
click node_diagnostics "https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/diagnostics.py"
click node_card_registration "https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/card_registration.py"
click node_card "https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/frontend/jejakmasjid-card.js"
click node_leaflet "https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/frontend/leaflet.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_config,node_integration,node_constants toneBlue
class node_locations,node_coordinator,node_cache,node_api_client,node_ranked_places toneAmber
class node_find_service,node_entity_base,node_sensors,node_diagnostics,node_upstream toneMint
class node_card_registration,node_card,node_leaflet toneRose
class node_user,node_ha_core,node_dashboard_ui,node_service_user toneIndigo
```

## Components

### Setup & lifecycle

- [Configuration flow](https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/config_flow.py): `custom_components/jejakmasjid/config_flow.py`
- [Integration lifecycle](https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/__init__.py): `custom_components/jejakmasjid/__init__.py`
- [Settings & constants](https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/const.py): `custom_components/jejakmasjid/const.py`

### Place discovery

- [Person & Home GPS](https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/coordinator.py): `custom_components/jejakmasjid/coordinator.py`
- [Refresh coordinator](https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/coordinator.py): `custom_components/jejakmasjid/coordinator.py`
- [Search cache](https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/coordinator.py): `custom_components/jejakmasjid/coordinator.py`
- **Jejak Masjid client**
- [Nearby place results](https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/coordinator.py): `custom_components/jejakmasjid/coordinator.py`

### Home Assistant outputs

- [find_nearby service](https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/services.py): `custom_components/jejakmasjid/services.py`
- [Entity base](https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/entity.py): `custom_components/jejakmasjid/entity.py`
- [Location sensors](https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/sensor.py): `custom_components/jejakmasjid/sensor.py`
- [Redacted diagnostics](https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/diagnostics.py): `custom_components/jejakmasjid/diagnostics.py`

### Dashboard map

- [Card registration](https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/card_registration.py): `custom_components/jejakmasjid/card_registration.py`
- [Interactive map card](https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/frontend/jejakmasjid-card.js): `custom_components/jejakmasjid/frontend/jejakmasjid-card.js`
- [Leaflet map library](https://github.com/zubir2k/homeassistant-jejakmasjid/blob/main/custom_components/jejakmasjid/frontend/leaflet.js): `custom_components/jejakmasjid/frontend/leaflet.js`

### Other components

- **Integrator**
- **Home Assistant**
- **Jejak Masjid API**
- **Lovelace dashboard**
- **Automation or Assist**

## Connections

- Integrator → Configuration flow: configures (evidence: `README.md`)
- Configuration flow → Jejak Masjid API: checks connection (evidence: `custom_components/jejakmasjid/config_flow.py`)
- Configuration flow → Home Assistant: creates entry (evidence: `custom_components/jejakmasjid/config_flow.py`)
- Home Assistant → Integration lifecycle: sets up entry (evidence: `custom_components/jejakmasjid/__init__.py`)
- Integration lifecycle → Refresh coordinator: starts refresh (evidence: `custom_components/jejakmasjid/__init__.py`)
- Integration lifecycle → find_nearby service: registers service (evidence: `custom_components/jejakmasjid/__init__.py`)
- Integration lifecycle → Card registration: registers card (evidence: `custom_components/jejakmasjid/__init__.py`)
- Integration lifecycle → Location sensors: forwards platform (evidence: `custom_components/jejakmasjid/__init__.py`)
- Refresh coordinator → Person & Home GPS: reads coordinates (evidence: `custom_components/jejakmasjid/coordinator.py`)
- Refresh coordinator → Search cache: loads and saves (evidence: `custom_components/jejakmasjid/coordinator.py`)
- Refresh coordinator → Jejak Masjid client: fetches places (evidence: `custom_components/jejakmasjid/coordinator.py`)
- Jejak Masjid client → Jejak Masjid API: queries
- Refresh coordinator → Nearby place results: ranks results (evidence: `custom_components/jejakmasjid/coordinator.py`)
- find_nearby service → Jejak Masjid client: fetches places (evidence: `custom_components/jejakmasjid/services.py`)
- find_nearby service → Nearby place results: filters and limits (evidence: `custom_components/jejakmasjid/services.py`)
- Automation or Assist → find_nearby service: requests search (evidence: `README.md`)
- Location sensors → Refresh coordinator: reads updates (evidence: `custom_components/jejakmasjid/sensor.py`)
- Location sensors → Entity base: uses base (evidence: `custom_components/jejakmasjid/sensor.py`)
- Redacted diagnostics → Refresh coordinator: reads status (evidence: `custom_components/jejakmasjid/diagnostics.py`)
- Card registration → Lovelace dashboard: serves and registers (evidence: `custom_components/jejakmasjid/card_registration.py`)
- Lovelace dashboard → Interactive map card: loads resource
- Interactive map card → Home Assistant: reads sensor states (evidence: `custom_components/jejakmasjid/frontend/jejakmasjid-card.js`)
- Interactive map card → Leaflet map library: renders map with (evidence: `README.md`)
