# lex-zander/kirby-karbon architecture

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

- Interactive diagram: https://gitdiagram.com/lex-zander/kirby-karbon
- Repository: https://github.com/lex-zander/kirby-karbon

## Overview

Kirby Karbon lets site editors maintain organisation disclosures and upstream hosting services in the Kirby Panel, then serves those values as carbon.txt at two routes. The update hook refreshes the last-updated date only when those data fields change. The renderer filters and normalizes entries, formats TOML, and returns a plain-text response. The README also documents English and German Panel labels. Runtime wiring is visible in index.php and lib/CarbonTxt.php; the blueprint and translations are included as product resources.

Main entry points: [`lib/CarbonTxt.php`](https://github.com/lex-zander/kirby-karbon/blob/main/lib/CarbonTxt.php) (CarbonTxt renderer), [`blueprints/tabs/karbon.yml`](https://github.com/lex-zander/kirby-karbon/blob/main/blueprints/tabs/karbon.yml) (Carbon tab), [`index.php`](https://github.com/lex-zander/kirby-karbon/blob/main/index.php) (Change hook), [`translations`](https://github.com/lex-zander/kirby-karbon/tree/main/translations) (Panel labels)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_panel["Panel editing"]
  node_blueprint["Carbon tab<br/>[karbon.yml]"]
  node_panel_fields["Carbon fields<br/>[karbon.yml]"]
  node_translations["Panel labels"]
end

subgraph group_updates["Update lifecycle"]
  node_site_content["Site content"]
  node_update_hook["Change hook<br/>[index.php]"]
  node_date_field["Last updated<br/>[index.php]"]
end

subgraph group_output["Carbon output"]
  node_route["GET routes<br/>[index.php]"]
  node_response["Plain-text response<br/>[CarbonTxt.php]"]
  node_renderer["CarbonTxt renderer<br/>[CarbonTxt.php]"]
  node_disclosures["Disclosure entries<br/>[CarbonTxt.php]"]
  node_services["Service entries<br/>[CarbonTxt.php]"]
  node_toml["TOML formatting<br/>[CarbonTxt.php]"]
end

node_editor(("Site editor"))
node_requester(("HTTP requester"))
node_carbon_consumers(("Carbon.txt consumers"))

node_editor -->|"opens tab"| node_blueprint
node_blueprint -->|"defines fields"| node_panel_fields
node_panel_fields -->|"saves data"| node_site_content
node_site_content -->|"triggers update"| node_update_hook
node_update_hook -->|"sets date"| node_date_field
node_date_field -->|"updates field"| node_site_content
node_editor -->|"sees labels"| node_translations
node_requester -->|"requests GET"| node_route
node_route -->|"invokes response"| node_response
node_response -->|"renders text"| node_renderer
node_renderer -->|"reads fields"| node_site_content
node_renderer -->|"formats entries"| node_disclosures
node_renderer -->|"formats entries"| node_services
node_renderer -->|"templates output"| node_toml
node_toml -->|"returns text"| node_response
node_response -->|"serves file"| node_carbon_consumers

click node_blueprint "https://github.com/lex-zander/kirby-karbon/blob/main/blueprints/tabs/karbon.yml"
click node_panel_fields "https://github.com/lex-zander/kirby-karbon/blob/main/blueprints/tabs/karbon.yml"
click node_update_hook "https://github.com/lex-zander/kirby-karbon/blob/main/index.php"
click node_date_field "https://github.com/lex-zander/kirby-karbon/blob/main/index.php"
click node_translations "https://github.com/lex-zander/kirby-karbon/tree/main/translations"
click node_route "https://github.com/lex-zander/kirby-karbon/blob/main/index.php"
click node_response "https://github.com/lex-zander/kirby-karbon/blob/main/lib/CarbonTxt.php"
click node_renderer "https://github.com/lex-zander/kirby-karbon/blob/main/lib/CarbonTxt.php"
click node_disclosures "https://github.com/lex-zander/kirby-karbon/blob/main/lib/CarbonTxt.php"
click node_services "https://github.com/lex-zander/kirby-karbon/blob/main/lib/CarbonTxt.php"
click node_toml "https://github.com/lex-zander/kirby-karbon/blob/main/lib/CarbonTxt.php"

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_blueprint,node_panel_fields,node_translations toneBlue
class node_site_content,node_update_hook,node_date_field toneAmber
class node_route,node_response,node_renderer,node_disclosures,node_services,node_toml,node_requester toneMint
class node_editor,node_carbon_consumers toneIndigo
```

## Components

### Panel editing

- [Carbon tab](https://github.com/lex-zander/kirby-karbon/blob/main/blueprints/tabs/karbon.yml): `blueprints/tabs/karbon.yml`
- [Carbon fields](https://github.com/lex-zander/kirby-karbon/blob/main/blueprints/tabs/karbon.yml): `blueprints/tabs/karbon.yml`
- [Panel labels](https://github.com/lex-zander/kirby-karbon/tree/main/translations): `translations`

### Update lifecycle

- **Site content**
- [Change hook](https://github.com/lex-zander/kirby-karbon/blob/main/index.php): `index.php`
- [Last updated](https://github.com/lex-zander/kirby-karbon/blob/main/index.php): `index.php`

### Carbon output

- [GET routes](https://github.com/lex-zander/kirby-karbon/blob/main/index.php): `index.php`
- [Plain-text response](https://github.com/lex-zander/kirby-karbon/blob/main/lib/CarbonTxt.php): `lib/CarbonTxt.php`
- [CarbonTxt renderer](https://github.com/lex-zander/kirby-karbon/blob/main/lib/CarbonTxt.php): `lib/CarbonTxt.php`
- [Disclosure entries](https://github.com/lex-zander/kirby-karbon/blob/main/lib/CarbonTxt.php): `lib/CarbonTxt.php`
- [Service entries](https://github.com/lex-zander/kirby-karbon/blob/main/lib/CarbonTxt.php): `lib/CarbonTxt.php`
- [TOML formatting](https://github.com/lex-zander/kirby-karbon/blob/main/lib/CarbonTxt.php): `lib/CarbonTxt.php`

### Other components

- **Site editor**
- **HTTP requester**
- **Carbon.txt consumers**

## Connections

- Site editor → Carbon tab: opens tab
- Carbon tab → Carbon fields: defines fields
- Carbon fields → Site content: saves data
- Site content → Change hook: triggers update
- Change hook → Last updated: sets date
- Last updated → Site content: updates field
- Site editor → Panel labels: sees labels
- HTTP requester → GET routes: requests GET
- GET routes → Plain-text response: invokes response
- Plain-text response → CarbonTxt renderer: renders text
- CarbonTxt renderer → Site content: reads fields
- CarbonTxt renderer → Disclosure entries: formats entries
- CarbonTxt renderer → Service entries: formats entries
- CarbonTxt renderer → TOML formatting: templates output
- TOML formatting → Plain-text response: returns text
- Plain-text response → Carbon.txt consumers: serves file