# alandtse/alexa_media_player architecture

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

- Interactive diagram: https://gitdiagram.com/alandtse/alexa_media_player
- Repository: https://github.com/alandtse/alexa_media_player

## Overview

Alexa Media Player is a Home Assistant custom integration that connects Alexa accounts and Echo devices to Home Assistant entities. The principal workflow is account setup, device discovery/state refresh, then exposure of Alexa controls and readings in Home Assistant. The README documents media playback controls and metadata; the tree also identifies sensors, switches, lights, alarms, notifications, and diagnostics. Several runtime links are only implied by the available excerpts and are marked unverified rather than presented as inspected call paths.

Main entry points: [`custom_components/alexa_media/__init__.py`](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/__init__.py) (Integration setup), [`custom_components/alexa_media/media_player.py`](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/media_player.py) (Media player), [`custom_components/alexa_media/config_flow.py`](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/config_flow.py) (Account configuration), [`custom_components/alexa_media/alexa_media.py`](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/alexa_media.py) (Account API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Account setup"]
  node_config["Account configuration<br/>[config_flow.py]"]
  node_integration["Integration setup<br/>[__init__.py]"]
end

subgraph group_runtime["Account runtime"]
  node_account["Account API client<br/>[alexa_media.py]"]
  node_coordinator["Data coordinator<br/>[coordinator.py]"]
  node_runtime_data["Runtime state<br/>[runtime_data.py]"]
  node_helpers["Shared helpers<br/>[helpers.py]"]
  node_exceptions["Integration exceptions<br/>[exceptions.py]"]
  node_constants["Constants and mappings<br/>[const.py]"]
end

subgraph group_entities["Device entities"]
  node_shared_entity["Shared entity base<br/>[alexa_entity.py]"]
  node_media["Media player<br/>[media_player.py]"]
  node_sensors["Sensors<br/>[sensor.py]"]
  node_switches["Switches<br/>[switch.py]"]
  node_lights["Lights<br/>[light.py]"]
  node_alarms["Alarm panel"]
  node_binary["Binary sensors<br/>[binary_sensor.py]"]
end

subgraph group_features["Controls and services"]
  node_services["Integration services<br/>[services.py]"]
  node_notify["Alexa notifications<br/>[notify.py]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.py]"]
  node_metrics["Metrics<br/>[metrics.py]"]
end

node_user(("Home Assistant user"))
node_ha["Home Assistant"]
node_alexa["Alexa service"]

node_user -.->|"configures account"| node_config
node_config -.->|"starts integration"| node_integration
node_integration -.->|"sets up account"| node_account
node_account -.->|"requests device data"| node_alexa
node_integration -.->|"creates refresh coordinator"| node_coordinator
node_coordinator -.->|"tracks runtime state"| node_runtime_data
node_integration -.->|"exposes entities"| node_media
node_integration -.->|"exposes entities"| node_sensors
node_integration -.->|"exposes entities"| node_switches
node_integration -.->|"exposes entities"| node_lights
node_integration -.->|"exposes entities"| node_alarms
node_integration -.->|"exposes entities"| node_binary
node_media -->|"extends base"| node_shared_entity
node_switches -->|"extends base"| node_shared_entity
node_user -->|"controls playback"| node_ha
node_ha -->|"controls Echo devices"| node_alexa
node_alexa -->|"provides music metadata"| node_ha
node_integration -.->|"registers services"| node_services
node_integration -.->|"enables notifications"| node_notify
node_ha -.->|"requests diagnostics"| node_diagnostics
node_integration -.->|"tracks metrics"| node_metrics
node_media -.->|"uses helpers"| node_helpers
node_integration -.->|"handles failures"| node_exceptions
node_integration -.->|"uses definitions"| node_constants

click node_config "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/config_flow.py"
click node_integration "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/__init__.py"
click node_account "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/alexa_media.py"
click node_coordinator "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/coordinator.py"
click node_runtime_data "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/runtime_data.py"
click node_shared_entity "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/alexa_entity.py"
click node_media "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/media_player.py"
click node_sensors "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/sensor.py"
click node_switches "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/switch.py"
click node_lights "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/light.py"
click node_alarms "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/alarm_control_panel.py"
click node_binary "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/binary_sensor.py"
click node_services "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/services.py"
click node_notify "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/notify.py"
click node_diagnostics "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/diagnostics.py"
click node_metrics "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/metrics.py"
click node_helpers "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/helpers.py"
click node_exceptions "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/exceptions.py"
click node_constants "https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/const.py"

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_user toneBlue
class node_account,node_coordinator,node_runtime_data,node_helpers,node_exceptions,node_constants toneAmber
class node_shared_entity,node_media,node_sensors,node_switches,node_lights,node_alarms,node_binary toneMint
class node_services,node_notify,node_diagnostics,node_metrics toneRose
class node_ha,node_alexa toneIndigo
```

## Components

### Account setup

- [Account configuration](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/config_flow.py): `custom_components/alexa_media/config_flow.py`
- [Integration setup](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/__init__.py): `custom_components/alexa_media/__init__.py`

### Account runtime

- [Account API client](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/alexa_media.py): `custom_components/alexa_media/alexa_media.py`
- [Data coordinator](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/coordinator.py): `custom_components/alexa_media/coordinator.py`
- [Runtime state](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/runtime_data.py): `custom_components/alexa_media/runtime_data.py`
- [Shared helpers](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/helpers.py): `custom_components/alexa_media/helpers.py`
- [Integration exceptions](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/exceptions.py): `custom_components/alexa_media/exceptions.py`
- [Constants and mappings](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/const.py): `custom_components/alexa_media/const.py`

### Device entities

- [Shared entity base](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/alexa_entity.py): `custom_components/alexa_media/alexa_entity.py`
- [Media player](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/media_player.py): `custom_components/alexa_media/media_player.py`
- [Sensors](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/sensor.py): `custom_components/alexa_media/sensor.py`
- [Switches](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/switch.py): `custom_components/alexa_media/switch.py`
- [Lights](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/light.py): `custom_components/alexa_media/light.py`
- [Alarm panel](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/alarm_control_panel.py): `custom_components/alexa_media/alarm_control_panel.py`
- [Binary sensors](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/binary_sensor.py): `custom_components/alexa_media/binary_sensor.py`

### Controls and services

- [Integration services](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/services.py): `custom_components/alexa_media/services.py`
- [Alexa notifications](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/notify.py): `custom_components/alexa_media/notify.py`
- [Diagnostics](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/diagnostics.py): `custom_components/alexa_media/diagnostics.py`
- [Metrics](https://github.com/alandtse/alexa_media_player/blob/dev/custom_components/alexa_media/metrics.py): `custom_components/alexa_media/metrics.py`

### Other components

- **Home Assistant user**
- **Home Assistant**
- **Alexa service**

## Connections

- Home Assistant user → Account configuration: configures account
- Account configuration → Integration setup: starts integration (evidence: `custom_components/alexa_media/__init__.py`)
- Integration setup → Account API client: sets up account
- Account API client → Alexa service: requests device data
- Integration setup → Data coordinator: creates refresh coordinator (evidence: `custom_components/alexa_media/__init__.py`)
- Data coordinator → Runtime state: tracks runtime state (evidence: `custom_components/alexa_media/coordinator.py`)
- Integration setup → Media player: exposes entities (evidence: `custom_components/alexa_media/media_player.py`)
- Integration setup → Sensors: exposes entities (evidence: `custom_components/alexa_media/sensor.py`)
- Integration setup → Switches: exposes entities (evidence: `custom_components/alexa_media/switch.py`)
- Integration setup → Lights: exposes entities (evidence: `custom_components/alexa_media/light.py`)
- Integration setup → Alarm panel: exposes entities
- Integration setup → Binary sensors: exposes entities (evidence: `custom_components/alexa_media/binary_sensor.py`)
- Media player → Shared entity base: extends base (evidence: `custom_components/alexa_media/media_player.py`)
- Switches → Shared entity base: extends base (evidence: `custom_components/alexa_media/switch.py`)
- Home Assistant user → Home Assistant: controls playback (evidence: `README.md`)
- Home Assistant → Alexa service: controls Echo devices (evidence: `README.md`)
- Alexa service → Home Assistant: provides music metadata (evidence: `README.md`)
- Integration setup → Integration services: registers services (evidence: `custom_components/alexa_media/__init__.py`)
- Integration setup → Alexa notifications: enables notifications (evidence: `custom_components/alexa_media/__init__.py`)
- Home Assistant → Diagnostics: requests diagnostics
- Integration setup → Metrics: tracks metrics (evidence: `custom_components/alexa_media/__init__.py`)
- Media player → Shared helpers: uses helpers (evidence: `custom_components/alexa_media/media_player.py`)
- Integration setup → Integration exceptions: handles failures (evidence: `custom_components/alexa_media/__init__.py`)
- Integration setup → Constants and mappings: uses definitions (evidence: `custom_components/alexa_media/__init__.py`)
