# govuk-pay/paas-grafana-annotation-resource architecture

> Architecture diagram of the GitHub repository govuk-pay/paas-grafana-annotation-resource, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/govuk-pay/paas-grafana-annotation-resource
- Repository: https://github.com/govuk-pay/paas-grafana-annotation-resource

## Overview

This repository implements a Concourse resource for creating and updating Grafana dashboard annotations. The main workflow is a Concourse `put` request routed through the `out` command: it validates configuration, combines tags and template values, then creates a point annotation or updates it into a timed region. The resource also exposes `check` and `in` protocol commands; `in` persists the supplied version ID locally. Edges reflect the command calls and HTTP/file operations shown in excerpts, with the README documenting the Concourse workflow and region behavior.

Main entry points: [`pkg/out/out.go`](https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/out/out.go) (Out dispatcher), [`cmd/check/main.go`](https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/cmd/check/main.go) (Check command), [`cmd/in/main.go`](https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/cmd/in/main.go) (In command), [`cmd/out/main.go`](https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/cmd/out/main.go) (Out command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["Concourse Protocol"]
  node_checkcmd["Check command<br/>[main.go]"]
  node_check["Version check<br/>[check.go]"]
  node_incmd["In command<br/>[main.go]"]
  node_in["Version input<br/>[in.go]"]
  node_outcmd["Out command<br/>[main.go]"]
end

subgraph group_annotation["Annotation Lifecycle"]
  node_out["Out dispatcher<br/>[out.go]"]
  node_create["Create annotation<br/>[out.go]"]
  node_update["Update annotation<br/>[out.go]"]
  node_tags["Tag handling<br/>[tags.go]"]
  node_idfile["Version ID file<br/>[out.go]"]
end

subgraph group_shared["Shared Resource Data"]
  node_types["Protocol and API types<br/>[types.go]"]
  node_sourcevalidation["Source validation<br/>[resource_source.go]"]
end

node_concourse(("Concourse pipeline"))
node_grafana["Grafana API"]

node_concourse -->|"sends check"| node_checkcmd
node_concourse -->|"sends in"| node_incmd
node_concourse -->|"sends put"| node_outcmd
node_checkcmd -->|"calls"| node_check
node_incmd -->|"calls"| node_in
node_outcmd -->|"calls"| node_out
node_checkcmd -->|"decodes request"| node_types
node_incmd -->|"decodes request"| node_types
node_outcmd -->|"decodes request"| node_types
node_in -->|"writes ID"| node_idfile
node_out -->|"validates source"| node_sourcevalidation
node_out -->|"dispatches create"| node_create
node_out -->|"dispatches update"| node_update
node_create -->|"combines tags"| node_tags
node_update -->|"combines tags"| node_tags
node_create -->|"POST annotation"| node_grafana
node_update -->|"PATCH annotation"| node_grafana
node_create -->|"writes ID"| node_idfile
node_update -->|"reads ID"| node_idfile

click node_checkcmd "https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/cmd/check/main.go"
click node_check "https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/check/check.go"
click node_incmd "https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/cmd/in/main.go"
click node_in "https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/in/in.go"
click node_outcmd "https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/cmd/out/main.go"
click node_out "https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/out/out.go"
click node_create "https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/out/out.go"
click node_update "https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/out/out.go"
click node_tags "https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/tags/tags.go"
click node_idfile "https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/out/out.go"
click node_types "https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/types/types.go"
click node_sourcevalidation "https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/types/resource_source.go"

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_checkcmd,node_check,node_incmd,node_in,node_outcmd toneBlue
class node_out,node_create,node_update,node_tags,node_idfile toneAmber
class node_types,node_sourcevalidation,node_grafana toneMint
class node_concourse toneIndigo
```

## Components

### Concourse Protocol

- [Check command](https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/cmd/check/main.go): `cmd/check/main.go`
- [Version check](https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/check/check.go): `pkg/check/check.go`
- [In command](https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/cmd/in/main.go): `cmd/in/main.go`
- [Version input](https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/in/in.go): `pkg/in/in.go`
- [Out command](https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/cmd/out/main.go): `cmd/out/main.go`

### Annotation Lifecycle

- [Out dispatcher](https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/out/out.go): `pkg/out/out.go`
- [Create annotation](https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/out/out.go): `pkg/out/out.go`
- [Update annotation](https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/out/out.go): `pkg/out/out.go`
- [Tag handling](https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/tags/tags.go): `pkg/tags/tags.go`
- [Version ID file](https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/out/out.go): `pkg/out/out.go`

### Shared Resource Data

- [Protocol and API types](https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/types/types.go): `pkg/types/types.go`
- [Source validation](https://github.com/govuk-pay/paas-grafana-annotation-resource/blob/main/pkg/types/resource_source.go): `pkg/types/resource_source.go`

### Other components

- **Concourse pipeline**
- **Grafana API**

## Connections

- Concourse pipeline → Check command: sends check (evidence: `README.md`)
- Concourse pipeline → In command: sends in (evidence: `README.md`)
- Concourse pipeline → Out command: sends put (evidence: `README.md`)
- Check command → Version check: calls (evidence: `cmd/check/main.go`)
- In command → Version input: calls (evidence: `cmd/in/main.go`)
- Out command → Out dispatcher: calls (evidence: `cmd/out/main.go`)
- Check command → Protocol and API types: decodes request (evidence: `cmd/check/main.go`)
- In command → Protocol and API types: decodes request (evidence: `cmd/in/main.go`)
- Out command → Protocol and API types: decodes request (evidence: `cmd/out/main.go`)
- Version input → Version ID file: writes ID (evidence: `pkg/in/in.go`)
- Out dispatcher → Source validation: validates source (evidence: `pkg/out/out.go`)
- Out dispatcher → Create annotation: dispatches create (evidence: `pkg/out/out.go`)
- Out dispatcher → Update annotation: dispatches update (evidence: `pkg/out/out.go`)
- Create annotation → Tag handling: combines tags (evidence: `pkg/out/out.go`)
- Update annotation → Tag handling: combines tags (evidence: `pkg/out/out.go`)
- Create annotation → Grafana API: POST annotation (evidence: `pkg/out/out.go`)
- Update annotation → Grafana API: PATCH annotation (evidence: `pkg/out/out.go`)
- Create annotation → Version ID file: writes ID (evidence: `pkg/out/out.go`)
- Update annotation → Version ID file: reads ID (evidence: `pkg/out/out.go`)
