# eclipse-opensovd/odx-converter architecture

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

- Interactive diagram: https://gitdiagram.com/eclipse-opensovd/odx-converter
- Repository: https://github.com/eclipse-opensovd/odx-converter

## Overview

The product is an ODX/PDX-to-MDD converter with CLI workflows for conversion, signing, verification, and inspection. Conversion reads PDX inputs, builds diagnostic-description chunks, applies plugins, and writes MDD output; the README documents optional job-file inclusion, audience filtering, and automatic signing. The source excerpts confirm chunk construction and plugin processing, but do not show every internal call or the sign/verify command implementations, so some relationships are documented at the CLI level.

Main entry points: [`converter/src/main/kotlin/Converter.kt`](https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/Converter.kt) (Convert command), [`converter/src/main/kotlin/ChunkBuilder.kt`](https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/ChunkBuilder.kt) (Chunk builder), [`converter/src/main/kotlin/PluginHandling.kt`](https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/PluginHandling.kt) (Plugin handling), [`converter/src/main/kotlin/SignCommand.kt`](https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/SignCommand.kt) (Sign command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversion["Conversion"]
  node_convert_cli["Convert command<br/>[Converter.kt]"]
  node_pdx_input["PDX inputs"]
  node_odx_read["ODX parsing<br/>[Converter.kt]"]
  node_link_collect["Link collection"]
  node_odx_collection["ODX collections<br/>[ODXCollection.kt]"]
  node_collection_groups["Collection grouping"]
end

subgraph group_format["MDD Format"]
  node_db_writer["Description writer<br/>[DatabaseWriter.kt]"]
  node_chunk_builder["Chunk builder<br/>[ChunkBuilder.kt]"]
  node_mdd_file["MDD container<br/>[file_format.proto]"]
  node_data_model["Diagnostic model<br/>[DiagLayer.kt]"]
end

subgraph group_plugins["Plugin System"]
  node_plugin_dispatch["Plugin handling<br/>[PluginHandling.kt]"]
  node_plugin_contracts["Plugin contracts<br/>[ConverterPlugin.kt]"]
  node_compression["Compression plugin"]
  node_verification_plugin["Hash verification"]
end

subgraph group_commands["MDD Commands"]
  node_sign_command["Sign command<br/>[SignCommand.kt]"]
  node_signing_executor["Signing executor<br/>[SigningExecutor.kt]"]
  node_verify_command["Verify command<br/>[VerifyCommand.kt]"]
  node_view_command["View command<br/>[Viewer.kt]"]
  node_mdd_inputs["MDD files"]
end

node_user(("CLI user"))

node_user -->|"invokes"| node_convert_cli
node_convert_cli -->|"accepts"| node_pdx_input
node_convert_cli -->|"parses"| node_odx_read
node_odx_read -->|"collects links"| node_link_collect
node_convert_cli -->|"builds collections"| node_odx_collection
node_odx_collection -->|"groups inputs"| node_collection_groups
node_convert_cli -->|"builds chunks"| node_chunk_builder
node_chunk_builder -.->|"serializes description"| node_db_writer
node_db_writer -->|"encodes model"| node_data_model
node_chunk_builder -.->|"creates chunks"| node_mdd_file
node_convert_cli -->|"processes chunks"| node_plugin_dispatch
node_plugin_dispatch -.->|"invokes plugins"| node_plugin_contracts
node_compression -->|"implements"| node_plugin_contracts
node_plugin_dispatch -.->|"dispatches"| node_compression
node_convert_cli -->|"writes output"| node_mdd_file
node_user -->|"invokes"| node_sign_command
node_sign_command -.->|"delegates signing"| node_signing_executor
node_sign_command -->|"modifies in place"| node_mdd_inputs
node_user -->|"invokes"| node_verify_command
node_verify_command -->|"uses verifier plugins"| node_verification_plugin
node_verification_plugin -->|"implements contract"| node_plugin_contracts
node_verify_command -->|"checks signatures"| node_mdd_inputs
node_user -->|"invokes"| node_view_command
node_view_command -->|"inspects"| node_mdd_inputs

click node_convert_cli "https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/Converter.kt"
click node_odx_read "https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/Converter.kt"
click node_link_collect "https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/ODXLinkCollector.kt"
click node_odx_collection "https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/ODXCollection.kt"
click node_collection_groups "https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/ODXCollectionGroup.kt"
click node_db_writer "https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/DatabaseWriter.kt"
click node_chunk_builder "https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/ChunkBuilder.kt"
click node_mdd_file "https://github.com/eclipse-opensovd/odx-converter/blob/main/database/src/main/proto/file_format.proto"
click node_data_model "https://github.com/eclipse-opensovd/odx-converter/blob/main/database/src/main/kotlin/dataformat/DiagLayer.kt"
click node_plugin_dispatch "https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/PluginHandling.kt"
click node_plugin_contracts "https://github.com/eclipse-opensovd/odx-converter/blob/main/converter-plugin-api/src/main/kotlin/converter/plugin/api/ConverterPlugin.kt"
click node_compression "https://github.com/eclipse-opensovd/odx-converter/blob/main/converter-plugins-default/src/main/kotlin/converter/plugins/default/CompressionPlugin.kt"
click node_sign_command "https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/SignCommand.kt"
click node_signing_executor "https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/SigningExecutor.kt"
click node_verify_command "https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/VerifyCommand.kt"
click node_verification_plugin "https://github.com/eclipse-opensovd/odx-converter/blob/main/converter-plugins-default/src/main/kotlin/converter/plugins/default/HashVerificationPlugin.kt"
click node_view_command "https://github.com/eclipse-opensovd/odx-converter/blob/main/viewer/src/main/kotlin/Viewer.kt"

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_convert_cli,node_pdx_input,node_odx_read,node_link_collect,node_odx_collection,node_collection_groups,node_user toneBlue
class node_db_writer,node_chunk_builder,node_mdd_file,node_data_model toneAmber
class node_plugin_dispatch,node_plugin_contracts,node_compression,node_verification_plugin toneMint
class node_sign_command,node_signing_executor,node_verify_command,node_view_command,node_mdd_inputs toneRose
```

## Components

### Conversion

- [Convert command](https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/Converter.kt): `converter/src/main/kotlin/Converter.kt`
- **PDX inputs**
- [ODX parsing](https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/Converter.kt): `converter/src/main/kotlin/Converter.kt`
- [Link collection](https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/ODXLinkCollector.kt): `converter/src/main/kotlin/ODXLinkCollector.kt`
- [ODX collections](https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/ODXCollection.kt): `converter/src/main/kotlin/ODXCollection.kt`
- [Collection grouping](https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/ODXCollectionGroup.kt): `converter/src/main/kotlin/ODXCollectionGroup.kt`

### MDD Format

- [Description writer](https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/DatabaseWriter.kt): `converter/src/main/kotlin/DatabaseWriter.kt`
- [Chunk builder](https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/ChunkBuilder.kt): `converter/src/main/kotlin/ChunkBuilder.kt`
- [MDD container](https://github.com/eclipse-opensovd/odx-converter/blob/main/database/src/main/proto/file_format.proto): `database/src/main/proto/file_format.proto`
- [Diagnostic model](https://github.com/eclipse-opensovd/odx-converter/blob/main/database/src/main/kotlin/dataformat/DiagLayer.kt): `database/src/main/kotlin/dataformat/DiagLayer.kt`

### Plugin System

- [Plugin handling](https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/PluginHandling.kt): `converter/src/main/kotlin/PluginHandling.kt`
- [Plugin contracts](https://github.com/eclipse-opensovd/odx-converter/blob/main/converter-plugin-api/src/main/kotlin/converter/plugin/api/ConverterPlugin.kt): `converter-plugin-api/src/main/kotlin/converter/plugin/api/ConverterPlugin.kt`
- [Compression plugin](https://github.com/eclipse-opensovd/odx-converter/blob/main/converter-plugins-default/src/main/kotlin/converter/plugins/default/CompressionPlugin.kt): `converter-plugins-default/src/main/kotlin/converter/plugins/default/CompressionPlugin.kt`
- [Hash verification](https://github.com/eclipse-opensovd/odx-converter/blob/main/converter-plugins-default/src/main/kotlin/converter/plugins/default/HashVerificationPlugin.kt): `converter-plugins-default/src/main/kotlin/converter/plugins/default/HashVerificationPlugin.kt`

### MDD Commands

- [Sign command](https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/SignCommand.kt): `converter/src/main/kotlin/SignCommand.kt`
- [Signing executor](https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/SigningExecutor.kt): `converter/src/main/kotlin/SigningExecutor.kt`
- [Verify command](https://github.com/eclipse-opensovd/odx-converter/blob/main/converter/src/main/kotlin/VerifyCommand.kt): `converter/src/main/kotlin/VerifyCommand.kt`
- [View command](https://github.com/eclipse-opensovd/odx-converter/blob/main/viewer/src/main/kotlin/Viewer.kt): `viewer/src/main/kotlin/Viewer.kt`
- **MDD files**

### Other components

- **CLI user**

## Connections

- CLI user → Convert command: invokes (evidence: `README.md`)
- Convert command → PDX inputs: accepts (evidence: `README.md`)
- Convert command → ODX parsing: parses (evidence: `converter/src/main/kotlin/Converter.kt`)
- ODX parsing → Link collection: collects links (evidence: `converter/src/main/kotlin/Converter.kt`)
- Convert command → ODX collections: builds collections (evidence: `converter/src/main/kotlin/Converter.kt`)
- ODX collections → Collection grouping: groups inputs (evidence: `converter/src/main/kotlin/ODXCollectionGroup.kt`)
- Convert command → Chunk builder: builds chunks (evidence: `converter/src/main/kotlin/Converter.kt`)
- Chunk builder → Description writer: serializes description
- Description writer → Diagnostic model: encodes model (evidence: `converter/src/main/kotlin/DatabaseWriter.kt`)
- Chunk builder → MDD container: creates chunks
- Convert command → Plugin handling: processes chunks (evidence: `converter/src/main/kotlin/Converter.kt`)
- Plugin handling → Plugin contracts: invokes plugins
- Compression plugin → Plugin contracts: implements (evidence: `converter-plugins-default/src/main/kotlin/converter/plugins/default/CompressionPlugin.kt`)
- Plugin handling → Compression plugin: dispatches
- Convert command → MDD container: writes output (evidence: `README.md`)
- CLI user → Sign command: invokes (evidence: `README.md`)
- Sign command → Signing executor: delegates signing
- Sign command → MDD files: modifies in place (evidence: `README.md`)
- CLI user → Verify command: invokes (evidence: `README.md`)
- Verify command → Hash verification: uses verifier plugins (evidence: `README.md`)
- Hash verification → Plugin contracts: implements contract
- Verify command → MDD files: checks signatures (evidence: `README.md`)
- CLI user → View command: invokes (evidence: `README.md`)
- View command → MDD files: inspects (evidence: `README.md`)
