# pqpxo/ha-notify-studio architecture

> Architecture diagram of the GitHub repository pqpxo/ha-notify-studio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pqpxo/ha-notify-studio
- Repository: https://github.com/pqpxo/ha-notify-studio

## Overview

Notify Studio is an admin-only Home Assistant integration for composing, auditing, organizing, and operating Companion notifications. The main workflow runs from the sidebar panel through authenticated WebSocket requests to backend validation, preview, test-send, YAML generation, and UI-managed automation saving. Separate branches cover Device Watch, templates, notification-source audits, custom groups, runnable controls, and operational logs. Backend details are only partially sampled; documented capabilities are retained, while uncertain internal call links are omitted.

Main entry points: [`custom_components/notify_studio/websocket_api.py`](https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/websocket_api.py) (WebSocket handlers), [`panel-src/src/App.tsx`](https://github.com/pqpxo/ha-notify-studio/blob/main/panel-src/src/App.tsx) (Studio interface), [`custom_components/notify_studio/notify_scanner.py`](https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/notify_scanner.py) (Merged YAML audit), [`panel-src/src/main.tsx`](https://github.com/pqpxo/ha-notify-studio/blob/main/panel-src/src/main.tsx) (Panel element)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_panel["Admin panel"]
  node_panel_element["Panel element<br/>[main.tsx]"]
  node_panel_app["Studio interface<br/>[App.tsx]"]
  node_ws_client["WebSocket client<br/>[api.ts]"]
  node_panel_styles["Panel styling<br/>[styles.ts]"]
end

subgraph group_api["Integration API"]
  node_ws_api["WebSocket handlers<br/>[websocket_api.py]"]
  node_integration_setup["Integration setup<br/>[__init__.py]"]
  node_config_flow["Integration config<br/>[config_flow.py]"]
  node_constants["Integration constants<br/>[const.py]"]
end

subgraph group_notification["Notification workflows"]
  node_notifiers["Notifier discovery"]
  node_payload_schema["Payload validation"]
  node_automation_writer["Automation writer"]
  node_templates[("Template drafts<br/>[template_store.py]")]
end

subgraph group_operations["Organization and operations"]
  node_usage_scanner["Merged YAML audit<br/>[notify_scanner.py]"]
  node_runnables["Runnable registry"]
  node_custom_groups[("Custom categories and areas")]
  node_logs[("Activity logs<br/>[log_store.py]")]
end

node_admin(("Administrator"))
node_ha["Home Assistant"]
node_companion["Companion notify services"]
node_yaml_config["Merged HA YAML"]
node_ha_automation["HA automation editor"]

node_admin -->|"opens panel"| node_panel_element
node_panel_element -->|"renders"| node_panel_app
node_panel_app -->|"uses styles"| node_panel_styles
node_panel_app -->|"sends requests"| node_ws_client
node_ws_client -->|"uses authenticated WebSocket"| node_ha
node_ha -.->|"routes requests"| node_ws_api
node_integration_setup -->|"registers handlers"| node_ws_api
node_admin -->|"adds integration"| node_config_flow
node_ws_api -->|"discovers targets"| node_notifiers
node_ws_api -->|"validates payload"| node_payload_schema
node_ws_api -->|"sends test notification"| node_companion
node_ws_api -->|"generates notification YAML"| node_automation_writer
node_ws_api -->|"saves UI automations"| node_ha_automation
node_ha_automation -->|"opens editor"| node_admin
node_ws_api -->|"manages drafts"| node_templates
node_ws_api -->|"scans notification usage"| node_usage_scanner
node_usage_scanner -->|"audits merged YAML"| node_yaml_config
node_usage_scanner -->|"resolves device names"| node_notifiers
node_ws_api -->|"lists runnable entities"| node_runnables
node_ws_api -->|"manages memberships"| node_custom_groups
node_ws_api -->|"records activity"| node_logs
node_admin -->|"composes and audits"| node_panel_app
node_panel_app -->|"requests previews and saves"| node_ws_api
node_ws_api -->|"renders templates"| node_ha
node_ws_api -->|"controls automations"| node_ha

click node_panel_element "https://github.com/pqpxo/ha-notify-studio/blob/main/panel-src/src/main.tsx"
click node_panel_app "https://github.com/pqpxo/ha-notify-studio/blob/main/panel-src/src/App.tsx"
click node_ws_client "https://github.com/pqpxo/ha-notify-studio/blob/main/panel-src/src/api.ts"
click node_panel_styles "https://github.com/pqpxo/ha-notify-studio/blob/main/panel-src/src/styles.ts"
click node_ws_api "https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/websocket_api.py"
click node_integration_setup "https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/__init__.py"
click node_config_flow "https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/config_flow.py"
click node_constants "https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/const.py"
click node_notifiers "https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/notifier_registry.py"
click node_payload_schema "https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/notification_schema.py"
click node_automation_writer "https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/automation_writer.py"
click node_templates "https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/template_store.py"
click node_usage_scanner "https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/notify_scanner.py"
click node_runnables "https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/runnable_registry.py"
click node_custom_groups "https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/custom_group_store.py"
click node_logs "https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/log_store.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_panel_element,node_panel_app,node_ws_client,node_panel_styles toneBlue
class node_ws_api,node_integration_setup,node_config_flow,node_constants toneAmber
class node_notifiers,node_payload_schema,node_automation_writer,node_templates toneMint
class node_usage_scanner,node_runnables,node_custom_groups,node_logs toneRose
class node_admin,node_ha,node_companion,node_yaml_config,node_ha_automation toneIndigo
```

## Components

### Admin panel

- [Panel element](https://github.com/pqpxo/ha-notify-studio/blob/main/panel-src/src/main.tsx): `panel-src/src/main.tsx`
- [Studio interface](https://github.com/pqpxo/ha-notify-studio/blob/main/panel-src/src/App.tsx): `panel-src/src/App.tsx`
- [WebSocket client](https://github.com/pqpxo/ha-notify-studio/blob/main/panel-src/src/api.ts): `panel-src/src/api.ts`
- [Panel styling](https://github.com/pqpxo/ha-notify-studio/blob/main/panel-src/src/styles.ts): `panel-src/src/styles.ts`

### Integration API

- [WebSocket handlers](https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/websocket_api.py): `custom_components/notify_studio/websocket_api.py`
- [Integration setup](https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/__init__.py): `custom_components/notify_studio/__init__.py`
- [Integration config](https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/config_flow.py): `custom_components/notify_studio/config_flow.py`
- [Integration constants](https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/const.py): `custom_components/notify_studio/const.py`

### Notification workflows

- [Notifier discovery](https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/notifier_registry.py): `custom_components/notify_studio/notifier_registry.py`
- [Payload validation](https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/notification_schema.py): `custom_components/notify_studio/notification_schema.py`
- [Automation writer](https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/automation_writer.py): `custom_components/notify_studio/automation_writer.py`
- [Template drafts](https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/template_store.py): `custom_components/notify_studio/template_store.py`

### Organization and operations

- [Merged YAML audit](https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/notify_scanner.py): `custom_components/notify_studio/notify_scanner.py`
- [Runnable registry](https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/runnable_registry.py): `custom_components/notify_studio/runnable_registry.py`
- [Custom categories and areas](https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/custom_group_store.py): `custom_components/notify_studio/custom_group_store.py`
- [Activity logs](https://github.com/pqpxo/ha-notify-studio/blob/main/custom_components/notify_studio/log_store.py): `custom_components/notify_studio/log_store.py`

### Other components

- **Administrator**
- **Home Assistant**
- **Companion notify services**
- **Merged HA YAML**
- **HA automation editor**

## Connections

- Administrator → Panel element: opens panel (evidence: `README.md`)
- Panel element → Studio interface: renders (evidence: `panel-src/src/main.tsx`)
- Studio interface → Panel styling: uses styles (evidence: `panel-src/src/App.tsx`)
- Studio interface → WebSocket client: sends requests (evidence: `panel-src/src/App.tsx`)
- WebSocket client → Home Assistant: uses authenticated WebSocket (evidence: `README.md`)
- Home Assistant → WebSocket handlers: routes requests
- Integration setup → WebSocket handlers: registers handlers (evidence: `custom_components/notify_studio/__init__.py`)
- Administrator → Integration config: adds integration (evidence: `README.md`)
- WebSocket handlers → Notifier discovery: discovers targets (evidence: `custom_components/notify_studio/websocket_api.py`)
- WebSocket handlers → Payload validation: validates payload (evidence: `custom_components/notify_studio/websocket_api.py`)
- WebSocket handlers → Companion notify services: sends test notification (evidence: `README.md`)
- WebSocket handlers → Automation writer: generates notification YAML (evidence: `custom_components/notify_studio/websocket_api.py`)
- WebSocket handlers → HA automation editor: saves UI automations (evidence: `custom_components/notify_studio/websocket_api.py`)
- HA automation editor → Administrator: opens editor (evidence: `README.md`)
- WebSocket handlers → Template drafts: manages drafts (evidence: `README.md`)
- WebSocket handlers → Merged YAML audit: scans notification usage (evidence: `custom_components/notify_studio/websocket_api.py`)
- Merged YAML audit → Merged HA YAML: audits merged YAML (evidence: `custom_components/notify_studio/notify_scanner.py`)
- Merged YAML audit → Notifier discovery: resolves device names (evidence: `custom_components/notify_studio/notify_scanner.py`)
- WebSocket handlers → Runnable registry: lists runnable entities (evidence: `custom_components/notify_studio/websocket_api.py`)
- WebSocket handlers → Custom categories and areas: manages memberships (evidence: `custom_components/notify_studio/websocket_api.py`)
- WebSocket handlers → Activity logs: records activity (evidence: `custom_components/notify_studio/websocket_api.py`)
- Administrator → Studio interface: composes and audits (evidence: `README.md`)
- Studio interface → WebSocket handlers: requests previews and saves (evidence: `README.md`)
- WebSocket handlers → Home Assistant: renders templates (evidence: `custom_components/notify_studio/websocket_api.py`)
- WebSocket handlers → Home Assistant: controls automations (evidence: `custom_components/notify_studio/websocket_api.py`)