# djtimca/hasatellitetracker architecture

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

- Interactive diagram: https://gitdiagram.com/djtimca/hasatellitetracker
- Repository: https://github.com/djtimca/hasatellitetracker

## Overview

##### Project type and purpose
- This is a Home Assistant custom integration (plugin) named “SatelliteTracker” that uses the N2YO API to provide two kinds of entities:
- A “location” sensor showing satellites overhead,
- A “satellite” integration with multiple sensors for visible passes and a device tracker for plotting satellite position on your Home Assistant map.

##### File structure
- Top-level:
- `.gitignore`, `LICENSE`, `README.md`, `hacs.json`, `info.md` (project metadata)
- `custom_components/satellitetracker/` (actual integration code)
- Inside `satellitetracker/`:
- `manifest.json` (HASS metadata, requirements, version, dependencies)
- `config_flow.py` (defines the UI flow for adding/configuring the integration)
- `const.py` (static strings, API base URLs, default settings)
- `binary_sensor.py`, `sensor.py`, `device_tracker.py` (three platform modules registering different entity types)
- `__init__.py` (entry point for setup, loading platforms)
- Localization: `strings.json`, `translations/sk.json`

##### README for additional insights
- It describes two setup modes (“Location” vs. “Satellite”), each creating different entity sets.
- Mentions N2YO API key, rate-limit considerations, configurable polling intervals and radii/minimum pass durations.

##### Main components
a. Home Assistant Core (blue rectangle)
- Component registry & entity/state machine (could be a sub-component)
- Frontend (UI) for configuration and dashboards
b. SatelliteTracker Integration (orange rectangle inside Core)
- `config_flow.py` (Config Entry handler)
- `__init__.py` (setup, coordinator initialization)
- Update Coordinator (internal helper to schedule API calls)
- Platforms:
- Binary Sensor Platform (`binary_sensor.py`)
- Sensor Platform (`sensor.py`)
- Device Tracker Platform (`device_tracker.py`)
- Constants & localization (`const.py`, `strings.json`, translations)
- Endpoints for current satellites overhead and next visible passes
d. Home Assistant UI / User (optional to show user interaction)

##### Relationships and interactions
- The user (via Home Assistant UI) initiates the Config Flow → calls `config_flow.py` → creates a Config Entry.
- On integration setup (`__init__.py`), an Update Coordinator is instantiated using API key and user-provided parameters (lat, long, elevation, category or NORAD ID, etc.).
- The Coordinator regularly calls the N2YO API (external service) based on the polling interval.
- API responses are parsed and pushed to the registered entity platforms.
- Each platform module registers its entities with the Core’s entity registry, which updates the state machine.
- The UI/dashboard fetches entity states from the state machine and displays sensor/device tracker data.

##### Architectural patterns and design principles
- **Home Assistant Integration Pattern**: use of Config Flow, Config Entries, platforms per entity type.
- **Update Coordinator**: centralizes polling and throttling, respects API rate limits.
- **Entity Model**: separate modules for each entity type for maintainability.
- **Decoupling**: business logic (API calls, data parsing) separated from Home Assistant plumbing.
- **Localization**: strings and translations externalized.

##### Key details to capture
- Config Entry lifecycle
- Update polling logic and intervals
- Distinct entity types (binary_sensor, sensor, device_tracker)
- Localization and manifest metadata

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and UI
    User(("User")):::user
    HA_UI["Home Assistant UI"]:::frontend

    %% Home Assistant Core
    subgraph "Home Assistant Core" 
        direction TB
        HomeCore["Core Engine"]:::core
        State["Entity Registry & State Machine"]:::core
        Storage["Persistent Storage (SQLite)"]:::core
    end

    %% SatelliteTracker Integration
    subgraph "SatelliteTracker Integration" 
        direction TB
        Manifest["manifest.json"]:::integration
        ConfigFlow["config_flow.py"]:::integration
        Init["__init__.py"]:::integration
        Coordinator["Update Coordinator"]:::integration

        subgraph "Platforms"
            direction TB
            BinarySensor["binary_sensor.py"]:::platform
            Sensor["sensor.py"]:::platform
            DeviceTracker["device_tracker.py"]:::platform
        end

        Const["const.py"]:::integration
        Localization["strings.json & translations"]:::integration
    end

    %% External API
    N2YO_API[(N2YO REST API)]:::external

    %% Interactions
    User -->|"configures Integration"| HA_UI
    HA_UI -->|"initiates Config Flow"| ConfigFlow
    ConfigFlow -->|"creates Config Entry"| HomeCore
    HomeCore -->|"calls setup"| Init
    Init -->|"instantiates"| Coordinator
    Coordinator -->|"API request: get satellites"| N2YO_API
    N2YO_API -->|"API response"| Coordinator
    Coordinator -->|"pushes data"| BinarySensor
    Coordinator -->|"pushes data"| Sensor
    Coordinator -->|"pushes data"| DeviceTracker
    BinarySensor --> State
    Sensor --> State
    DeviceTracker --> State
    State -->|"updates UI"| HA_UI

    %% Click Events
    click Manifest "https://github.com/djtimca/hasatellitetracker/blob/main/custom_components/satellitetracker/manifest.json"
    click ConfigFlow "https://github.com/djtimca/hasatellitetracker/blob/main/custom_components/satellitetracker/config_flow.py"
    click Init "https://github.com/djtimca/hasatellitetracker/blob/main/custom_components/satellitetracker/__init__.py"
    click BinarySensor "https://github.com/djtimca/hasatellitetracker/blob/main/custom_components/satellitetracker/binary_sensor.py"
    click Sensor "https://github.com/djtimca/hasatellitetracker/blob/main/custom_components/satellitetracker/sensor.py"
    click DeviceTracker "https://github.com/djtimca/hasatellitetracker/blob/main/custom_components/satellitetracker/device_tracker.py"
    click Const "https://github.com/djtimca/hasatellitetracker/blob/main/custom_components/satellitetracker/const.py"
    click Localization "https://github.com/djtimca/hasatellitetracker/blob/main/custom_components/satellitetracker/strings.json"

    %% Styles
    classDef user fill:#E0E0E0,stroke:#666,stroke-width:2px
    classDef frontend fill:#D0E8FF,stroke:#0366D6,stroke-width:2px
    classDef core fill:#B3D4FC,stroke:#0366D6,stroke-width:2px
    classDef integration fill:#FFD8B1,stroke:#D2691E,stroke-width:2px
    classDef platform fill:#FFE4B5,stroke:#D2691E,stroke-width:2px
    classDef external fill:#DFF2BF,stroke:#4F8A10,stroke-width:2px
```
