# openproficiency/opm-go architecture

> Architecture diagram of the GitHub repository openproficiency/opm-go, 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/openproficiency/opm-go
- Repository: https://github.com/openproficiency/opm-go

## Overview

opm-go is a Go library for defining and exchanging Open Proficiency Model data. Its principal workflow is to represent topic lists, record scores as transcript entries, and evaluate those entries against score interpretations to produce pass/fail results. The library also supports JSON/YAML encoding, schema validation, detached OpenPGP signing and verification, and topic-list dependencies. Edges reflect the README workflow and sampled imports or calls; unsampled dependency-resolution behavior is represented as a capability, without asserting its internal call path.

Main entry points: [`topic/topic.go`](https://github.com/openproficiency/opm-go/blob/main/topic/topic.go) (Topic lists), [`scoreinterpretation/list.go`](https://github.com/openproficiency/opm-go/blob/main/scoreinterpretation/list.go) (Interpretation lists), [`transcript/entry.go`](https://github.com/openproficiency/opm-go/blob/main/transcript/entry.go) (Transcript entries), [`internal/schema/schema.go`](https://github.com/openproficiency/opm-go/blob/main/internal/schema/schema.go) (OPM schemas)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_domain["OPM Data"]
  node_topics["Topic lists<br/>[topic.go]"]
  node_entries["Transcript entries<br/>[entry.go]"]
  node_transcripts["Transcript collections<br/>[entries.go]"]
  node_scores["Score levels<br/>[score.go]"]
  node_topic_serialization["Topic encoding<br/>[topic.go]"]
  node_transcript_wire["Entry encoding<br/>[wire.go]"]
end

subgraph group_interpret["Interpretation"]
  node_interpretation_lists["Interpretation lists<br/>[list.go]"]
  node_requirements["Requirement expressions<br/>[requirement.go]"]
  node_evaluation["Score evaluation<br/>[result.go]"]
  node_interpretation_validation["Interpretation validation<br/>[validate.go]"]
  node_interpretation_wire["Interpretation encoding<br/>[wire.go]"]
end

subgraph group_trust["Validation and Trust"]
  node_signing["Signing operations<br/>[sign.go]"]
  node_entry_signing["Entry signing<br/>[sign.go]"]
  node_schema["OPM schemas<br/>[schema.go]"]
end

subgraph group_shared["Shared Primitives"]
  node_semantic["Semantic checks<br/>[semantic.go]"]
  node_canonical["Canonical data<br/>[canonical.go]"]
  node_pgp["OpenPGP operations<br/>[pgp.go]"]
end

node_user(("Library user"))

node_user -->|"defines"| node_topics
node_user -->|"defines"| node_interpretation_lists
node_user -->|"issues"| node_entries
node_user -->|"requests evaluation"| node_evaluation
node_topics -->|"encodes and decodes"| node_topic_serialization
node_topics -->|"validates against"| node_schema
node_topics -->|"captures signature state"| node_canonical
node_topics -->|"signs and verifies"| node_pgp
node_topics -->|"checks values"| node_semantic
node_entries -->|"uses levels"| node_scores
node_entries -->|"checks values"| node_semantic
node_transcripts -->|"encodes entries"| node_entries
node_transcripts -->|"validates transcripts"| node_schema
node_transcript_wire -->|"validates signed entries"| node_schema
node_transcript_wire -->|"captures protected state"| node_canonical
node_interpretation_lists -->|"validates"| node_interpretation_validation
node_interpretation_lists -->|"encodes and decodes"| node_interpretation_wire
node_interpretation_lists -->|"evaluates entries"| node_evaluation
node_interpretation_lists -->|"contains expressions"| node_requirements
node_evaluation -->|"reads scores"| node_entries
node_evaluation -->|"compares levels"| node_scores
node_interpretation_validation -->|"validates against"| node_schema
node_interpretation_wire -->|"validates encoded lists"| node_schema
node_interpretation_wire -->|"builds protected data"| node_canonical
node_interpretation_wire -->|"decodes thresholds"| node_scores
node_interpretation_wire -->|"uses dependencies"| node_topics
node_signing -->|"signs list data"| node_interpretation_lists
node_signing -->|"canonicalizes data"| node_canonical
node_signing -->|"signs and verifies"| node_pgp
node_entry_signing -->|"signs entry data"| node_entries
node_entry_signing -->|"canonicalizes data"| node_canonical
node_entry_signing -->|"signs and verifies"| node_pgp
node_schema -->|"registers format checks"| node_semantic
node_interpretation_validation -->|"checks values"| node_semantic

click node_topics "https://github.com/openproficiency/opm-go/blob/main/topic/topic.go"
click node_entries "https://github.com/openproficiency/opm-go/blob/main/transcript/entry.go"
click node_transcripts "https://github.com/openproficiency/opm-go/blob/main/transcript/entries.go"
click node_scores "https://github.com/openproficiency/opm-go/blob/main/score/score.go"
click node_interpretation_lists "https://github.com/openproficiency/opm-go/blob/main/scoreinterpretation/list.go"
click node_requirements "https://github.com/openproficiency/opm-go/blob/main/scoreinterpretation/requirement.go"
click node_evaluation "https://github.com/openproficiency/opm-go/blob/main/scoreinterpretation/result.go"
click node_interpretation_validation "https://github.com/openproficiency/opm-go/blob/main/scoreinterpretation/validate.go"
click node_interpretation_wire "https://github.com/openproficiency/opm-go/blob/main/scoreinterpretation/wire.go"
click node_topic_serialization "https://github.com/openproficiency/opm-go/blob/main/topic/topic.go"
click node_transcript_wire "https://github.com/openproficiency/opm-go/blob/main/transcript/wire.go"
click node_signing "https://github.com/openproficiency/opm-go/blob/main/scoreinterpretation/sign.go"
click node_entry_signing "https://github.com/openproficiency/opm-go/blob/main/transcript/sign.go"
click node_schema "https://github.com/openproficiency/opm-go/blob/main/internal/schema/schema.go"
click node_semantic "https://github.com/openproficiency/opm-go/blob/main/internal/semantic/semantic.go"
click node_canonical "https://github.com/openproficiency/opm-go/blob/main/internal/canonical/canonical.go"
click node_pgp "https://github.com/openproficiency/opm-go/blob/main/internal/pgp/pgp.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_topics,node_entries,node_transcripts,node_scores,node_topic_serialization,node_transcript_wire,node_user toneBlue
class node_interpretation_lists,node_requirements,node_evaluation,node_interpretation_validation,node_interpretation_wire toneAmber
class node_signing,node_entry_signing,node_schema toneMint
class node_semantic,node_canonical,node_pgp toneRose
```

## Components

### OPM Data

- [Topic lists](https://github.com/openproficiency/opm-go/blob/main/topic/topic.go): `topic/topic.go`
- [Transcript entries](https://github.com/openproficiency/opm-go/blob/main/transcript/entry.go): `transcript/entry.go`
- [Transcript collections](https://github.com/openproficiency/opm-go/blob/main/transcript/entries.go): `transcript/entries.go`
- [Score levels](https://github.com/openproficiency/opm-go/blob/main/score/score.go): `score/score.go`
- [Topic encoding](https://github.com/openproficiency/opm-go/blob/main/topic/topic.go): `topic/topic.go`
- [Entry encoding](https://github.com/openproficiency/opm-go/blob/main/transcript/wire.go): `transcript/wire.go`

### Interpretation

- [Interpretation lists](https://github.com/openproficiency/opm-go/blob/main/scoreinterpretation/list.go): `scoreinterpretation/list.go`
- [Requirement expressions](https://github.com/openproficiency/opm-go/blob/main/scoreinterpretation/requirement.go): `scoreinterpretation/requirement.go`
- [Score evaluation](https://github.com/openproficiency/opm-go/blob/main/scoreinterpretation/result.go): `scoreinterpretation/result.go`
- [Interpretation validation](https://github.com/openproficiency/opm-go/blob/main/scoreinterpretation/validate.go): `scoreinterpretation/validate.go`
- [Interpretation encoding](https://github.com/openproficiency/opm-go/blob/main/scoreinterpretation/wire.go): `scoreinterpretation/wire.go`

### Validation and Trust

- [Signing operations](https://github.com/openproficiency/opm-go/blob/main/scoreinterpretation/sign.go): `scoreinterpretation/sign.go`
- [Entry signing](https://github.com/openproficiency/opm-go/blob/main/transcript/sign.go): `transcript/sign.go`
- [OPM schemas](https://github.com/openproficiency/opm-go/blob/main/internal/schema/schema.go): `internal/schema/schema.go`

### Shared Primitives

- [Semantic checks](https://github.com/openproficiency/opm-go/blob/main/internal/semantic/semantic.go): `internal/semantic/semantic.go`
- [Canonical data](https://github.com/openproficiency/opm-go/blob/main/internal/canonical/canonical.go): `internal/canonical/canonical.go`
- [OpenPGP operations](https://github.com/openproficiency/opm-go/blob/main/internal/pgp/pgp.go): `internal/pgp/pgp.go`

### Other components

- **Library user**

## Connections

- Library user → Topic lists: defines (evidence: `README.md`)
- Library user → Interpretation lists: defines (evidence: `README.md`)
- Library user → Transcript entries: issues (evidence: `README.md`)
- Library user → Score evaluation: requests evaluation (evidence: `README.md`)
- Topic lists → Topic encoding: encodes and decodes (evidence: `topic/topic.go`)
- Topic lists → OPM schemas: validates against (evidence: `topic/topic.go`)
- Topic lists → Canonical data: captures signature state (evidence: `topic/topic.go`)
- Topic lists → OpenPGP operations: signs and verifies (evidence: `topic/topic.go`)
- Topic lists → Semantic checks: checks values (evidence: `topic/topic.go`)
- Transcript entries → Score levels: uses levels (evidence: `transcript/entry.go`)
- Transcript entries → Semantic checks: checks values (evidence: `transcript/entry.go`)
- Transcript collections → Transcript entries: encodes entries (evidence: `transcript/entries.go`)
- Transcript collections → OPM schemas: validates transcripts (evidence: `transcript/entries.go`)
- Entry encoding → OPM schemas: validates signed entries (evidence: `transcript/wire.go`)
- Entry encoding → Canonical data: captures protected state (evidence: `transcript/wire.go`)
- Interpretation lists → Interpretation validation: validates (evidence: `scoreinterpretation/validate.go`)
- Interpretation lists → Interpretation encoding: encodes and decodes (evidence: `scoreinterpretation/wire.go`)
- Interpretation lists → Score evaluation: evaluates entries (evidence: `scoreinterpretation/result.go`)
- Interpretation lists → Requirement expressions: contains expressions (evidence: `README.md`)
- Score evaluation → Transcript entries: reads scores (evidence: `scoreinterpretation/result.go`)
- Score evaluation → Score levels: compares levels (evidence: `scoreinterpretation/result.go`)
- Interpretation validation → OPM schemas: validates against (evidence: `scoreinterpretation/validate.go`)
- Interpretation encoding → OPM schemas: validates encoded lists (evidence: `scoreinterpretation/wire.go`)
- Interpretation encoding → Canonical data: builds protected data (evidence: `scoreinterpretation/wire.go`)
- Interpretation encoding → Score levels: decodes thresholds (evidence: `scoreinterpretation/wire.go`)
- Interpretation encoding → Topic lists: uses dependencies (evidence: `scoreinterpretation/wire.go`)
- Signing operations → Interpretation lists: signs list data (evidence: `scoreinterpretation/sign.go`)
- Signing operations → Canonical data: canonicalizes data (evidence: `scoreinterpretation/sign.go`)
- Signing operations → OpenPGP operations: signs and verifies (evidence: `scoreinterpretation/sign.go`)
- Entry signing → Transcript entries: signs entry data (evidence: `transcript/sign.go`)
- Entry signing → Canonical data: canonicalizes data (evidence: `transcript/sign.go`)
- Entry signing → OpenPGP operations: signs and verifies (evidence: `transcript/sign.go`)
- OPM schemas → Semantic checks: registers format checks (evidence: `internal/schema/schema.go`)
- Interpretation validation → Semantic checks: checks values (evidence: `scoreinterpretation/validate.go`)
