iaunn/thailand-electric-rate

<explanation>

1. Identify the project type and purpose

- This is an open‐source Home Assistant integration/utility for fetching Thailand Electricity Authority (PEA) tariff data, storing it as JSON, and computing user electricity costs via Home Assistant sensors.

- Key indicators: a JSON rate file (thailand_electric_rate.json), a sensor configuration (sensors.yaml), a GitHub Actions workflow to update the JSON, and a small shell script (update_ft.sh).

2. Analyze the file structure

- .github/workflows/update_json.yml: CI job that runs daily (or on schedule) to update the JSON with current tariffs.

- update_ft.sh: script invoked by the workflow to scrape or fetch new FT (fuel adjustment) rates and commit them.

- thailand_electric_rate.json: the single source of truth for all tariff values (grid_150, grid_250, grid_400, ft, service).

- sensors.yaml: Home Assistant REST & template sensors that consume the JSON from GitHub’s raw URL and compute the final electricity cost.

- readme.md: documentation for setting up in Home Assistant.

3. Examine the README for additional insights

- The README shows YAML snippets for REST platform sensors (p150, p250, p400, ft, service), a template sensor (electricity_cost), and a utility meter (monthly_energy).

- It references PEA tariff documents and explains how the cost calculation tiers work.

4. Creating the system design diagram

a. Main components

- External Tariff Source (PEA website / PDF)

- CI/CD pipeline (GitHub Actions) + update_ft.sh

- GitHub Repository (holding JSON & YAML)

- Home Assistant Instance

• REST Sensor subsystem

• Utility Meter

• Template Sensor (electricity_cost)

- End‑user Dashboard or Automation

b. Relationships & interactions

1. CI job triggers update_ft.sh → fetches latest FT & tariff values from PEA → updates thailand_electric_rate.json → commits & pushes to GitHub.

2. Home Assistant’s REST sensors poll the raw GitHub URL for thailand_electric_rate.json (e.g., every hour).

3. Utility Meter collects monthly energy usage from an existing sensor (sensor.overall_used).

4. Template Sensor reads the five rate sensors + monthly usage to calculate total cost (including ft adjustment and 7% VAT + service charge).

5. The computed value is exposed to dashboards or automations in Home Assistant.

c. Architectural patterns & design principles

- Configuration‑as‑Code: All logic lives in versioned YAML and JSON.

- CI‑Driven Data Refresh: Use GitHub Actions to keep data fresh.

- Separation of Concerns:

• Data acquisition & storage (CI + JSON)

• Data retrieval (REST sensors)

• Data transformation (template sensor)

• Usage metering (utility_meter)

d. Key technologies & libraries

- GitHub Actions (update_json.yml)

- Shell script (update_ft.sh)

- REST sensor platform in Home Assistant

- Template sensor & Utility Meter integration

5. Tailoring the diagram for this open‐source Home Assistant tool

- Emphasize:

• The external PEA tariff source as a cloud/Internet icon.

• The CI/CD block (GitHub Actions + script) updating the JSON.

• GitHub raw content endpoint serving the JSON.

• Home Assistant’s sensor subsystems (REST, Template, Utility Meter).

- Show how each subsystem fits into the end‑to‑end flow: data origin → storage → retrieval → computation → presentation.

6. Diagramming guidelines

- Components: Draw each as a labeled rectangle or icon:

• Cloud icon: PEA Tariff Source

• Gear icon: GitHub Actions + update_ft.sh

• Cylinder icon: thailand_electric_rate.json (data store)

• GitHub icon: Repository

• Box: Home Assistant (with sub‑boxes for REST Sensor, Utility Meter, Template Sensor)

• Monitor icon: Dashboard/Automation

- Arrows & Data Flow:

• Arrow from PEA Source → CI/CD

• Arrow from CI/CD → GitHub JSON

• Arrow from GitHub JSON → Home Assistant REST Sensor

• Arrow from Utility Meter (energy) + REST sensors → Template Sensor

• Arrow from Template Sensor → Dashboard

- Color Coding / Shapes:

• External services (cloud) in light blue

• CI/CD pipeline in yellow

• Data store (JSON) in gray

• Home Assistant internal components in green

• End‑user view in purple

7. Capturing essential elements

- Label each component clearly.

- Use directional arrows to show “fetch,” “update,” and “compute.”

- Nest Home Assistant subsystems to indicate they all reside in one host.

- Annotate polling intervals (e.g., “REST sensors: every 3600 s,” “CI job: daily”).

By following these steps and guidelines, you’ll produce a concise yet detailed architecture diagram that reflects exactly how this Home Assistant electricity‐cost integration sources, stores, and processes tariff data.