# Components

Version 0.1, 2026-10-12. Source: https://developer.nrgon.net/components

How software is shaped on every layer. An application is assembled from components. A component does one job, reads from the
data layer and writes its result back there.

```schematic
col Inputs | bucket/bucket/Bucket | redis/redis/Redis | open/edge/data.nrgon.net | config/config/YAML config
col Component | comp/components/One job
col Outputs | out/bucket/Result objects | latest/redis/Latest values | report/report/Reports
edges: bucket>comp redis>comp open>comp config>comp comp>out comp>latest comp>report
```

## What a component has

```cards
doc | One job | Stated in one sentence at the top of its README.
table | Inputs and outputs | Named objects or keys, each with its format.
container | An interface | A function, a command-line entry point or an HTTPS endpoint. Often all three.
check | A check | A script that runs it on known input and compares the output.
```

## Components today

```cards
tariff | Tariff library | The tariff and time-of-use bands for a site on a date. From data.nrgon.net.
table | Load study | Daily energy, peaks and a battery size per value case, from interval load and tariff.
check | Measurement and verification | What a battery saved against a baseline, with the method.
adapter | Protocol adapters | Read and write a vendor's equipment through its cloud API or register map.
plan | Day plan | Charge and discharge windows for tomorrow, in the vendor's format, written and read back.
report | Reports | Proposal, weekly report, final report. PDF and Markdown.
phone | Configurator | A sizing conversation on tablet, phone and browser from one definition file.
```

## Conventions

- **JSON for messages, JSONL for logs, CSV for tables, YAML for configuration, Markdown
  for text.** Anything else is named in the README with the reason.
- **UTC inside, local time at the edge.** Stored timestamps are UTC. Conversion happens
  where a person reads it.
- **Units in field names**: `power_kw`, `energy_kwh`, `soc_pct`.
- **One definition, many renderers.** Content that appears on several platforms lives in
  one file. A harness checks the renderers agree.
- **A check before a feature.**
- **No secrets in code.** Credentials come from the environment. The README names which.

## Adding a component

1. Write the README: job, inputs, outputs, interface.
2. Own folder, own check script.
3. Read inputs from the bucket, Redis, data.nrgon.net or YAML. Never from another
   component's internals.
4. Write outputs with the naming on the [Infrastructure](infrastructure) page.
5. Run the check. Add the component to the list above.