# armada-dn/proton-qa architecture

> Architecture diagram of the GitHub repository armada-dn/proton-qa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/armada-dn/proton-qa
- Repository: https://github.com/armada-dn/proton-qa

## Overview

PROTON-QA is a knowledge-grounded benchmark dataset for question answering over nuclear technical reports. A benchmark user consults annotated questions and answers, follows their provenance to supporting report evidence, and can evaluate a QA system with the supplied evaluation script. Its knowledge graph also represents answer units and types, and links question entities to controlled concepts. The repository documents a RAG prompt and Croissant metadata as additional resources. No source excerpts were provided, so runtime behavior and unevidenced connections are not inferred.

Main entry points: [`questions.ttl`](https://github.com/armada-dn/proton-qa/blob/main/questions.ttl) (QA annotations), [`corpus`](https://github.com/armada-dn/proton-qa/tree/main/corpus) (Action reports), [`vocab/schemaorg-current-https.ttl`](https://github.com/armada-dn/proton-qa/blob/main/vocab/schemaorg-current-https.ttl) (Question-answer model), [`vocab/oa.ttl`](https://github.com/armada-dn/proton-qa/blob/main/vocab/oa.ttl) (Evidence annotations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_knowledge["Benchmark knowledge"]
  node_questions[("QA annotations<br/>[questions.ttl]")]
  node_reports[("Action reports")]
  node_metadata["Dataset metadata<br/>[croissant.jsonld]"]
end

subgraph group_semantics["Semantic vocabularies"]
  node_schema["Question-answer model"]
  node_oa["Evidence annotations<br/>[oa.ttl]"]
  node_prov["Provenance model<br/>[prov-o.ttl]"]
  node_qudt["Units and quantities<br/>[qudt.ttl]"]
  node_qudtunit["Unit vocabulary<br/>[qudt-unit.ttl]"]
  node_eurovoc["EuroVoc concepts"]
  node_extensions["Domain concepts"]
  node_qanary["QA concepts<br/>[qanary.ttl]"]
end

subgraph group_use["Benchmark use"]
  node_prompt["RAG prompt<br/>[rag_prompt.txt]"]
  node_evaluation["Benchmark evaluator<br/>[evaluate.py]"]
end

node_user(("Benchmark user"))

node_questions -->|"links evidence"| node_reports
node_questions -->|"uses question model"| node_schema
node_questions -->|"uses annotations"| node_oa
node_questions -->|"records provenance"| node_prov
node_questions -->|"represents units"| node_qudt
node_questions -->|"links concepts"| node_eurovoc
node_questions -->|"links concepts"| node_extensions
node_questions -->|"uses QA concepts"| node_qanary
node_user -.->|"evaluates QA"| node_evaluation

click node_questions "https://github.com/armada-dn/proton-qa/blob/main/questions.ttl"
click node_reports "https://github.com/armada-dn/proton-qa/tree/main/corpus"
click node_metadata "https://github.com/armada-dn/proton-qa/blob/main/croissant.jsonld"
click node_schema "https://github.com/armada-dn/proton-qa/blob/main/vocab/schemaorg-current-https.ttl"
click node_oa "https://github.com/armada-dn/proton-qa/blob/main/vocab/oa.ttl"
click node_prov "https://github.com/armada-dn/proton-qa/blob/main/vocab/prov-o.ttl"
click node_qudt "https://github.com/armada-dn/proton-qa/blob/main/vocab/qudt.ttl"
click node_qudtunit "https://github.com/armada-dn/proton-qa/blob/main/vocab/qudt-unit.ttl"
click node_eurovoc "https://github.com/armada-dn/proton-qa/blob/main/vocab/eurovoc_in_skos_core_concepts.ttl"
click node_extensions "https://github.com/armada-dn/proton-qa/blob/main/vocab/concept_extensions.ttl"
click node_qanary "https://github.com/armada-dn/proton-qa/blob/main/vocab/qanary.ttl"
click node_prompt "https://github.com/armada-dn/proton-qa/blob/main/benchmark/rag_prompt.txt"
click node_evaluation "https://github.com/armada-dn/proton-qa/blob/main/benchmark/evaluate.py"

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_questions,node_reports,node_metadata,node_user toneBlue
class node_schema,node_oa,node_prov,node_qudt,node_qudtunit,node_eurovoc,node_extensions,node_qanary toneAmber
class node_prompt,node_evaluation toneMint
```

## Components

### Benchmark knowledge

- [QA annotations](https://github.com/armada-dn/proton-qa/blob/main/questions.ttl): `questions.ttl`
- [Action reports](https://github.com/armada-dn/proton-qa/tree/main/corpus): `corpus`
- [Dataset metadata](https://github.com/armada-dn/proton-qa/blob/main/croissant.jsonld): `croissant.jsonld`

### Semantic vocabularies

- [Question-answer model](https://github.com/armada-dn/proton-qa/blob/main/vocab/schemaorg-current-https.ttl): `vocab/schemaorg-current-https.ttl`
- [Evidence annotations](https://github.com/armada-dn/proton-qa/blob/main/vocab/oa.ttl): `vocab/oa.ttl`
- [Provenance model](https://github.com/armada-dn/proton-qa/blob/main/vocab/prov-o.ttl): `vocab/prov-o.ttl`
- [Units and quantities](https://github.com/armada-dn/proton-qa/blob/main/vocab/qudt.ttl): `vocab/qudt.ttl`
- [Unit vocabulary](https://github.com/armada-dn/proton-qa/blob/main/vocab/qudt-unit.ttl): `vocab/qudt-unit.ttl`
- [EuroVoc concepts](https://github.com/armada-dn/proton-qa/blob/main/vocab/eurovoc_in_skos_core_concepts.ttl): `vocab/eurovoc_in_skos_core_concepts.ttl`
- [Domain concepts](https://github.com/armada-dn/proton-qa/blob/main/vocab/concept_extensions.ttl): `vocab/concept_extensions.ttl`
- [QA concepts](https://github.com/armada-dn/proton-qa/blob/main/vocab/qanary.ttl): `vocab/qanary.ttl`

### Benchmark use

- [RAG prompt](https://github.com/armada-dn/proton-qa/blob/main/benchmark/rag_prompt.txt): `benchmark/rag_prompt.txt`
- [Benchmark evaluator](https://github.com/armada-dn/proton-qa/blob/main/benchmark/evaluate.py): `benchmark/evaluate.py`

### Other components

- **Benchmark user**

## Connections

- QA annotations → Action reports: links evidence (evidence: `README.md`)
- QA annotations → Question-answer model: uses question model (evidence: `README.md`)
- QA annotations → Evidence annotations: uses annotations (evidence: `README.md`)
- QA annotations → Provenance model: records provenance (evidence: `README.md`)
- QA annotations → Units and quantities: represents units (evidence: `README.md`)
- QA annotations → EuroVoc concepts: links concepts (evidence: `README.md`)
- QA annotations → Domain concepts: links concepts (evidence: `README.md`)
- QA annotations → QA concepts: uses QA concepts (evidence: `README.md`)
- Benchmark user → Benchmark evaluator: evaluates QA
