# openproficiency/model architecture

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

## Overview

Open Proficiency Model is a portable data model, distributed as JSON Schemas rather than an application that performs proficiency tracking. Its central workflow defines topics and scores, records issuer-claimed transcript entries, and bundles entries into transcripts; interpretation lists add a separate way to make scores meaningful. The graph reflects the README’s conceptual relationships and the schema/spec files in the tree, not runtime processing. The repository excerpt contains no schema contents, so links are limited to relationships explicitly documented in the README diagram.

Main entry points: [`schemas/transcript-entry.schema.json`](https://github.com/openproficiency/model/blob/main/schemas/transcript-entry.schema.json) (Transcript Entry), [`schemas/topic-list.schema.json`](https://github.com/openproficiency/model/blob/main/schemas/topic-list.schema.json) (Topic List), [`specs/topic-score.md`](https://github.com/openproficiency/model/blob/main/specs/topic-score.md) (Topic Score), [`schemas/score-interpretation-list.schema.json`](https://github.com/openproficiency/model/blob/main/schemas/score-interpretation-list.schema.json) (Interpretation List)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_knowledge["Knowledge Definitions"]
  node_topic["Topic<br/>[topic.schema.json]"]
  node_topic_list["Topic List"]
  node_experience_source["Experience Source"]
  node_issuer["Issuer<br/>[issuer.md]"]
end

subgraph group_tracking["Proficiency Records"]
  node_topic_score["Topic Score<br/>[topic-score.md]"]
  node_transcript_entry["Transcript Entry"]
  node_entry_verification["Entry Verification"]
  node_transcript["Transcript"]
end

subgraph group_interpretation["Score Interpretation"]
  node_score_interpretation["Score Interpretation"]
  node_interpretation_list["Interpretation List"]
end

subgraph group_distribution["Schema Distribution"]
end

node_consumer(("Applications"))

node_topic -->|"listed in"| node_topic_list
node_experience_source -->|"informs"| node_topic_score
node_topic_list -->|"provides topic"| node_topic_score
node_topic_score -->|"recorded in"| node_transcript_entry
node_issuer -->|"signs claim"| node_transcript_entry
node_transcript_entry -->|"verified by"| node_entry_verification
node_transcript_entry -->|"collected in"| node_transcript
node_topic_list -->|"grounds requirements"| node_score_interpretation
node_score_interpretation -->|"collected in"| node_interpretation_list
node_issuer -->|"signs claim"| node_interpretation_list
node_transcript -->|"used by"| node_consumer
node_interpretation_list -->|"used by"| node_consumer

click node_topic "https://github.com/openproficiency/model/blob/main/schemas/topic.schema.json"
click node_topic_list "https://github.com/openproficiency/model/blob/main/schemas/topic-list.schema.json"
click node_experience_source "https://github.com/openproficiency/model/blob/main/specs/experience-source.md"
click node_issuer "https://github.com/openproficiency/model/blob/main/specs/issuer.md"
click node_topic_score "https://github.com/openproficiency/model/blob/main/specs/topic-score.md"
click node_transcript_entry "https://github.com/openproficiency/model/blob/main/schemas/transcript-entry.schema.json"
click node_entry_verification "https://github.com/openproficiency/model/blob/main/schemas/transcript-entry-verification.schema.json"
click node_transcript "https://github.com/openproficiency/model/blob/main/schemas/transcript.schema.json"
click node_score_interpretation "https://github.com/openproficiency/model/blob/main/schemas/score-interpretation.schema.json"
click node_interpretation_list "https://github.com/openproficiency/model/blob/main/schemas/score-interpretation-list.schema.json"

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_topic,node_topic_list,node_experience_source,node_issuer toneBlue
class node_topic_score,node_transcript_entry,node_entry_verification,node_transcript toneAmber
class node_score_interpretation,node_interpretation_list toneMint
class node_consumer toneIndigo
```

## Components

### Knowledge Definitions

- [Topic](https://github.com/openproficiency/model/blob/main/schemas/topic.schema.json): `schemas/topic.schema.json`
- [Topic List](https://github.com/openproficiency/model/blob/main/schemas/topic-list.schema.json): `schemas/topic-list.schema.json`
- [Experience Source](https://github.com/openproficiency/model/blob/main/specs/experience-source.md): `specs/experience-source.md`
- [Issuer](https://github.com/openproficiency/model/blob/main/specs/issuer.md): `specs/issuer.md`

### Proficiency Records

- [Topic Score](https://github.com/openproficiency/model/blob/main/specs/topic-score.md): `specs/topic-score.md`
- [Transcript Entry](https://github.com/openproficiency/model/blob/main/schemas/transcript-entry.schema.json): `schemas/transcript-entry.schema.json`
- [Entry Verification](https://github.com/openproficiency/model/blob/main/schemas/transcript-entry-verification.schema.json): `schemas/transcript-entry-verification.schema.json`
- [Transcript](https://github.com/openproficiency/model/blob/main/schemas/transcript.schema.json): `schemas/transcript.schema.json`

### Score Interpretation

- [Score Interpretation](https://github.com/openproficiency/model/blob/main/schemas/score-interpretation.schema.json): `schemas/score-interpretation.schema.json`
- [Interpretation List](https://github.com/openproficiency/model/blob/main/schemas/score-interpretation-list.schema.json): `schemas/score-interpretation-list.schema.json`

### Other components

- **Applications**

## Connections

- Topic → Topic List: listed in (evidence: `README.md`)
- Experience Source → Topic Score: informs (evidence: `README.md`)
- Topic List → Topic Score: provides topic (evidence: `README.md`)
- Topic Score → Transcript Entry: recorded in (evidence: `README.md`)
- Issuer → Transcript Entry: signs claim (evidence: `README.md`)
- Transcript Entry → Entry Verification: verified by (evidence: `README.md`)
- Transcript Entry → Transcript: collected in (evidence: `README.md`)
- Topic List → Score Interpretation: grounds requirements (evidence: `README.md`)
- Score Interpretation → Interpretation List: collected in (evidence: `README.md`)
- Issuer → Interpretation List: signs claim (evidence: `README.md`)
- Transcript → Applications: used by (evidence: `README.md`)
- Interpretation List → Applications: used by (evidence: `README.md`)
