# julicraft44/ha-cloudflare-tunnel architecture

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

- Interactive diagram: https://gitdiagram.com/julicraft44/ha-cloudflare-tunnel
- Repository: https://github.com/julicraft44/ha-cloudflare-tunnel

## Overview

This repository packages a Home Assistant add-on that exposes a Home Assistant instance through a token-authenticated Cloudflare Tunnel. The main workflow is configuring and starting the add-on, running cloudflared, and monitoring its readiness and metrics to update Home Assistant sensor entities; the README also documents automatic tunnel restart when it drops. The monitor’s polling and entity updates are visible in source. Service startup wiring and restart behavior are not shown in the excerpts, so those links rely only on README documentation or are left unverified.

Main entry points: [`cloudflare_tunnel/monitor.py`](https://github.com/julicraft44/ha-cloudflare-tunnel/blob/main/cloudflare_tunnel/monitor.py) (Metrics Monitor), [`cloudflare_tunnel/rootfs/etc/services.d/cloudflare_tunnel/run`](https://github.com/julicraft44/ha-cloudflare-tunnel/blob/main/cloudflare_tunnel/rootfs/etc/services.d/cloudflare_tunnel/run) (cloudflared Service), [`cloudflare_tunnel/config.yaml`](https://github.com/julicraft44/ha-cloudflare-tunnel/blob/main/cloudflare_tunnel/config.yaml) (Add-on Configuration), [`cloudflare_tunnel/rootfs/etc/services.d/cloudflare_tunnel_monitor/run`](https://github.com/julicraft44/ha-cloudflare-tunnel/blob/main/cloudflare_tunnel/rootfs/etc/services.d/cloudflare_tunnel_monitor/run) (Monitor Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Configuration"]
  node_addon_config["Add-on Configuration<br/>[config.yaml]"]
end

subgraph group_tunnel["Tunnel Runtime"]
  node_tunnel_service["cloudflared Service<br/>[run]"]
  node_restart["Tunnel Restart<br/>[run]"]
end

subgraph group_monitoring["Health Monitoring"]
  node_monitor_service["Monitor Service<br/>[run]"]
  node_monitor["Metrics Monitor<br/>[monitor.py]"]
end

subgraph group_ha["Home Assistant"]
  node_ha_entities["Tunnel Sensor Entities<br/>[monitor.py]"]
  node_ha_api["Home Assistant API"]
end

node_user(("Home Assistant User"))
node_cloudflare{{"Cloudflare Tunnel"}}
node_ha_instance["Home Assistant Instance"]

node_user -->|"configures"| node_addon_config
node_addon_config -.->|"starts with"| node_tunnel_service
node_tunnel_service -->|"connects to"| node_cloudflare
node_cloudflare -->|"routes requests"| node_ha_instance
node_monitor_service -.->|"runs"| node_monitor
node_monitor -->|"polls readiness and metrics"| node_cloudflare
node_monitor -->|"posts state updates"| node_ha_api
node_ha_api -->|"updates"| node_ha_entities
node_monitor -->|"defines entity states"| node_ha_entities
node_tunnel_service -.->|"restarts on drop"| node_restart

click node_addon_config "https://github.com/julicraft44/ha-cloudflare-tunnel/blob/main/cloudflare_tunnel/config.yaml"
click node_tunnel_service "https://github.com/julicraft44/ha-cloudflare-tunnel/blob/main/cloudflare_tunnel/rootfs/etc/services.d/cloudflare_tunnel/run"
click node_monitor_service "https://github.com/julicraft44/ha-cloudflare-tunnel/blob/main/cloudflare_tunnel/rootfs/etc/services.d/cloudflare_tunnel_monitor/run"
click node_monitor "https://github.com/julicraft44/ha-cloudflare-tunnel/blob/main/cloudflare_tunnel/monitor.py"
click node_ha_entities "https://github.com/julicraft44/ha-cloudflare-tunnel/blob/main/cloudflare_tunnel/monitor.py"
click node_restart "https://github.com/julicraft44/ha-cloudflare-tunnel/blob/main/cloudflare_tunnel/rootfs/etc/services.d/cloudflare_tunnel/run"

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_addon_config,node_user toneBlue
class node_tunnel_service,node_restart toneAmber
class node_monitor_service,node_monitor toneMint
class node_ha_entities,node_ha_api toneRose
class node_cloudflare,node_ha_instance toneIndigo
```

## Components

### Configuration

- [Add-on Configuration](https://github.com/julicraft44/ha-cloudflare-tunnel/blob/main/cloudflare_tunnel/config.yaml): `cloudflare_tunnel/config.yaml`

### Tunnel Runtime

- [cloudflared Service](https://github.com/julicraft44/ha-cloudflare-tunnel/blob/main/cloudflare_tunnel/rootfs/etc/services.d/cloudflare_tunnel/run): `cloudflare_tunnel/rootfs/etc/services.d/cloudflare_tunnel/run`
- [Tunnel Restart](https://github.com/julicraft44/ha-cloudflare-tunnel/blob/main/cloudflare_tunnel/rootfs/etc/services.d/cloudflare_tunnel/run): `cloudflare_tunnel/rootfs/etc/services.d/cloudflare_tunnel/run`

### Health Monitoring

- [Monitor Service](https://github.com/julicraft44/ha-cloudflare-tunnel/blob/main/cloudflare_tunnel/rootfs/etc/services.d/cloudflare_tunnel_monitor/run): `cloudflare_tunnel/rootfs/etc/services.d/cloudflare_tunnel_monitor/run`
- [Metrics Monitor](https://github.com/julicraft44/ha-cloudflare-tunnel/blob/main/cloudflare_tunnel/monitor.py): `cloudflare_tunnel/monitor.py`

### Home Assistant

- [Tunnel Sensor Entities](https://github.com/julicraft44/ha-cloudflare-tunnel/blob/main/cloudflare_tunnel/monitor.py): `cloudflare_tunnel/monitor.py`
- **Home Assistant API**

### Other components

- **Home Assistant User**
- **Cloudflare Tunnel**
- **Home Assistant Instance**

## Connections

- Home Assistant User → Add-on Configuration: configures (evidence: `README.md`)
- Add-on Configuration → cloudflared Service: starts with
- cloudflared Service → Cloudflare Tunnel: connects to (evidence: `README.md`)
- Cloudflare Tunnel → Home Assistant Instance: routes requests (evidence: `README.md`)
- Monitor Service → Metrics Monitor: runs
- Metrics Monitor → Cloudflare Tunnel: polls readiness and metrics (evidence: `cloudflare_tunnel/monitor.py`)
- Metrics Monitor → Home Assistant API: posts state updates (evidence: `cloudflare_tunnel/monitor.py`)
- Home Assistant API → Tunnel Sensor Entities: updates (evidence: `cloudflare_tunnel/monitor.py`)
- Metrics Monitor → Tunnel Sensor Entities: defines entity states (evidence: `cloudflare_tunnel/monitor.py`)
- cloudflared Service → Tunnel Restart: restarts on drop (evidence: `README.md`)
