# digital-preservation-finland/dpx-validator architecture

> Architecture diagram of the GitHub repository digital-preservation-finland/dpx-validator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/digital-preservation-finland/dpx-validator
- Repository: https://github.com/digital-preservation-finland/dpx-validator

## Overview

DPX Validator checks selected DPX header fields and reports validity through a CLI or importable API. The workflow is CLI arguments → per-file API validation → truncation check and ordered field checks → messages and file metadata → command-line output. The validator owns field-check sequencing, while the header reader handles binary decoding and byte order. README documents the supported fields; the graph omits undocumented external integrations.

Main entry points: [`dpx_validator/api.py`](https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/api.py) (Validation API), [`dpx_validator/main.py`](https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/main.py) (CLI runner), [`dpx_validator/dpx_validator.py`](https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/dpx_validator.py) (Header validation), [`dpx_validator/file_header_reader.py`](https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/file_header_reader.py) (Header reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["CLI runner<br/>[main.py]"]
  node_api["Validation API<br/>[api.py]"]
end

subgraph group_validation["Validation workflow"]
  node_truncation["Truncation check<br/>[dpx_validator.py]"]
  node_validator["Header validation<br/>[dpx_validator.py]"]
  node_checks["Field checks<br/>[dpx_validator.py]"]
end

subgraph group_binary["Header decoding"]
  node_reader["Header reader"]
end

subgraph group_reporting["Results and reporting"]
  node_messages["Message types<br/>[messages.py]"]
  node_formatter["CLI formatter<br/>[messages.py]"]
end

node_user(("CLI user"))
node_file["DPX file"]
node_filesystem["Filesystem metadata"]
node_result["Validation result"]

node_user -->|"provides paths"| node_cli
node_cli -->|"validates files"| node_api
node_api -->|"checks truncation"| node_truncation
node_api -->|"runs validation"| node_validator
node_api -->|"opens bytes"| node_file
node_truncation -->|"reads file size"| node_filesystem
node_validator -->|"runs checks"| node_checks
node_checks -->|"reads fields"| node_reader
node_reader -->|"seeks and unpacks"| node_file
node_checks -->|"compares file size"| node_filesystem
node_validator -->|"collects message types"| node_messages
node_api -->|"returns metadata and logs"| node_result
node_cli -->|"formats logs"| node_formatter
node_formatter -->|"prints outcome"| node_user

click node_cli "https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/main.py"
click node_api "https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/api.py"
click node_truncation "https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/dpx_validator.py"
click node_validator "https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/dpx_validator.py"
click node_checks "https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/dpx_validator.py"
click node_reader "https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/file_header_reader.py"
click node_messages "https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/messages.py"
click node_formatter "https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/messages.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_cli,node_api,node_user toneBlue
class node_truncation,node_validator,node_checks toneAmber
class node_reader toneMint
class node_messages,node_formatter toneRose
class node_file,node_filesystem,node_result toneIndigo
```

## Components

### User entry points

- [CLI runner](https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/main.py): `dpx_validator/main.py`
- [Validation API](https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/api.py): `dpx_validator/api.py`

### Validation workflow

- [Truncation check](https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/dpx_validator.py): `dpx_validator/dpx_validator.py`
- [Header validation](https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/dpx_validator.py): `dpx_validator/dpx_validator.py`
- [Field checks](https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/dpx_validator.py): `dpx_validator/dpx_validator.py`

### Header decoding

- [Header reader](https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/file_header_reader.py): `dpx_validator/file_header_reader.py`

### Results and reporting

- [Message types](https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/messages.py): `dpx_validator/messages.py`
- [CLI formatter](https://github.com/digital-preservation-finland/dpx-validator/blob/master/dpx_validator/messages.py): `dpx_validator/messages.py`

### Other components

- **CLI user**
- **DPX file**
- **Filesystem metadata**
- **Validation result**

## Connections

- CLI user → CLI runner: provides paths (evidence: `dpx_validator/main.py`)
- CLI runner → Validation API: validates files (evidence: `dpx_validator/main.py`)
- Validation API → Truncation check: checks truncation (evidence: `dpx_validator/api.py`)
- Validation API → Header validation: runs validation (evidence: `dpx_validator/api.py`)
- Validation API → DPX file: opens bytes (evidence: `dpx_validator/api.py`)
- Truncation check → Filesystem metadata: reads file size (evidence: `dpx_validator/dpx_validator.py`)
- Header validation → Field checks: runs checks (evidence: `dpx_validator/dpx_validator.py`)
- Field checks → Header reader: reads fields (evidence: `dpx_validator/dpx_validator.py`)
- Header reader → DPX file: seeks and unpacks (evidence: `dpx_validator/file_header_reader.py`)
- Field checks → Filesystem metadata: compares file size (evidence: `dpx_validator/dpx_validator.py`)
- Header validation → Message types: collects message types (evidence: `dpx_validator/dpx_validator.py`)
- Validation API → Validation result: returns metadata and logs (evidence: `dpx_validator/api.py`)
- CLI runner → CLI formatter: formats logs (evidence: `dpx_validator/main.py`)
- CLI formatter → CLI user: prints outcome