# fairmat-nfdi/pynxtools architecture

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

## Overview

pynxtools combines instrument data and ELN metadata into NeXus-compliant HDF5, with validation and schema-aware inspection; it also integrates NeXus data with NOMAD for search and publication. The main conversion flow is documented in the README, and indexed source references support several internal links. Some converter and NOMAD relationships are inferred from those references rather than complete excerpts, so the graph omits uncertain wiring.

Main entry points: [`src/pynxtools/dataconverter/convert.py`](https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/dataconverter/convert.py) (Converter), [`src/pynxtools/nomad/parsers/parser_v2.py`](https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/nomad/parsers/parser_v2.py) (NOMAD parser), [`src/pynxtools/dataconverter/validation.py`](https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/dataconverter/validation.py) (Validation), [`src/pynxtools/nexus/schema_resolver.py`](https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/nexus/schema_resolver.py) (Schema resolver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversion["Data conversion"]
  node_converter["Converter<br/>[convert.py]"]
  node_multi_reader["Multi reader<br/>[reader.py]"]
  node_json_reader["JSON map reader<br/>[reader.py]"]
  node_template["Template mapping<br/>[template.py]"]
  node_validation["Validation<br/>[validation.py]"]
  node_writer["HDF5 writer<br/>[writer.py]"]
end

subgraph group_nexus["NeXus schema and tools"]
  node_schema_tree["Schema tree<br/>[nexus_tree.py]"]
  node_schema_resolver["Schema resolver<br/>[schema_resolver.py]"]
  node_nexus_handler["NeXus visitor<br/>[handler.py]"]
  node_annotator["File annotator<br/>[annotator.py]"]
end

subgraph group_eln["ELN mapping"]
  node_eln_mapper["ELN mapper<br/>[eln.py]"]
end

subgraph group_nomad["NOMAD integration"]
  node_nomad_parser["NOMAD parser<br/>[parser_v2.py]"]
  node_nomad_schema["NOMAD schema<br/>[schema.py]"]
  node_nexus_annotations["NeXus annotations<br/>[annotations.py]"]
end

node_user(("Data user"))
node_hdf5[("NeXus HDF5")]
node_nomad_archive[("NOMAD archive")]

node_user -->|"runs conversion"| node_converter
node_converter -->|"loads reader"| node_multi_reader
node_multi_reader -->|"dispatches to"| node_json_reader
node_converter -->|"uses mapping"| node_template
node_converter -->|"validates data"| node_validation
node_converter -->|"writes output"| node_writer
node_writer -->|"writes HDF5"| node_hdf5
node_validation -->|"checks structure"| node_schema_tree
node_validation -->|"resolves schema"| node_schema_resolver
node_annotator -.->|"visits file"| node_nexus_handler
node_annotator -->|"resolves concepts"| node_schema_resolver
node_eln_mapper -->|"supplies metadata"| node_converter
node_nomad_parser -->|"traverses HDF5"| node_nexus_handler
node_nomad_parser -->|"resolves fields"| node_schema_resolver
node_nomad_parser -.->|"reads annotations"| node_nexus_annotations
node_nomad_schema -.->|"defines schema"| node_nexus_annotations
node_nomad_parser -->|"populates archive"| node_nomad_archive
node_nomad_schema -->|"enables integration"| node_nomad_archive

click node_converter "https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/dataconverter/convert.py"
click node_multi_reader "https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/dataconverter/readers/multi/reader.py"
click node_json_reader "https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/dataconverter/readers/json_map/reader.py"
click node_template "https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/dataconverter/template.py"
click node_validation "https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/dataconverter/validation.py"
click node_writer "https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/dataconverter/writer.py"
click node_schema_tree "https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/nexus/nexus_tree.py"
click node_schema_resolver "https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/nexus/schema_resolver.py"
click node_nexus_handler "https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/nexus/handler.py"
click node_annotator "https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/annotator/annotator.py"
click node_eln_mapper "https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/eln_mapper/eln.py"
click node_nomad_parser "https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/nomad/parsers/parser_v2.py"
click node_nomad_schema "https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/nomad/schema_packages/schema.py"
click node_nexus_annotations "https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/nomad/annotations.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_converter,node_multi_reader,node_json_reader,node_template,node_validation,node_writer,node_user toneBlue
class node_schema_tree,node_schema_resolver,node_nexus_handler,node_annotator,node_hdf5,node_nomad_archive toneAmber
class node_eln_mapper toneMint
class node_nomad_parser,node_nomad_schema,node_nexus_annotations toneRose
```

## Components

### Data conversion

- [Converter](https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/dataconverter/convert.py): `src/pynxtools/dataconverter/convert.py`
- [Multi reader](https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/dataconverter/readers/multi/reader.py): `src/pynxtools/dataconverter/readers/multi/reader.py`
- [JSON map reader](https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/dataconverter/readers/json_map/reader.py): `src/pynxtools/dataconverter/readers/json_map/reader.py`
- [Template mapping](https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/dataconverter/template.py): `src/pynxtools/dataconverter/template.py`
- [Validation](https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/dataconverter/validation.py): `src/pynxtools/dataconverter/validation.py`
- [HDF5 writer](https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/dataconverter/writer.py): `src/pynxtools/dataconverter/writer.py`

### NeXus schema and tools

- [Schema tree](https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/nexus/nexus_tree.py): `src/pynxtools/nexus/nexus_tree.py`
- [Schema resolver](https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/nexus/schema_resolver.py): `src/pynxtools/nexus/schema_resolver.py`
- [NeXus visitor](https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/nexus/handler.py): `src/pynxtools/nexus/handler.py`
- [File annotator](https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/annotator/annotator.py): `src/pynxtools/annotator/annotator.py`

### ELN mapping

- [ELN mapper](https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/eln_mapper/eln.py): `src/pynxtools/eln_mapper/eln.py`

### NOMAD integration

- [NOMAD parser](https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/nomad/parsers/parser_v2.py): `src/pynxtools/nomad/parsers/parser_v2.py`
- [NOMAD schema](https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/nomad/schema_packages/schema.py): `src/pynxtools/nomad/schema_packages/schema.py`
- [NeXus annotations](https://github.com/fairmat-nfdi/pynxtools/blob/master/src/pynxtools/nomad/annotations.py): `src/pynxtools/nomad/annotations.py`

### Other components

- **Data user**
- **NeXus HDF5**
- **NOMAD archive**

## Connections

- Data user → Converter: runs conversion
- Converter → Multi reader: loads reader (evidence: `src/pynxtools/dataconverter/convert.py`)
- Multi reader → JSON map reader: dispatches to (evidence: `src/pynxtools/dataconverter/readers/multi/reader.py`)
- Converter → Template mapping: uses mapping (evidence: `src/pynxtools/dataconverter/convert.py`)
- Converter → Validation: validates data (evidence: `src/pynxtools/dataconverter/convert.py`)
- Converter → HDF5 writer: writes output (evidence: `src/pynxtools/dataconverter/convert.py`)
- HDF5 writer → NeXus HDF5: writes HDF5
- Validation → Schema tree: checks structure (evidence: `src/pynxtools/dataconverter/validation.py`)
- Validation → Schema resolver: resolves schema (evidence: `src/pynxtools/dataconverter/validation.py`)
- File annotator → NeXus visitor: visits file (evidence: `src/pynxtools/annotator/annotator.py`)
- File annotator → Schema resolver: resolves concepts (evidence: `src/pynxtools/annotator/annotator.py`)
- ELN mapper → Converter: supplies metadata
- NOMAD parser → NeXus visitor: traverses HDF5 (evidence: `src/pynxtools/nomad/parsers/parser_v2.py`)
- NOMAD parser → Schema resolver: resolves fields (evidence: `src/pynxtools/nomad/parsers/parser_v2.py`)
- NOMAD parser → NeXus annotations: reads annotations
- NOMAD schema → NeXus annotations: defines schema
- NOMAD parser → NOMAD archive: populates archive
- NOMAD schema → NOMAD archive: enables integration
