# innovative-io/io-dicom architecture

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

- Interactive diagram: https://gitdiagram.com/innovative-io/io-dicom
- Repository: https://github.com/innovative-io/io-dicom

## Overview

io-dicom is a Go DICOM library and command-line client/server, supporting DICOM object parsing and writing, network associations, DIMSE services, pixel codecs and transcoding, plus DICOMweb. A typical network workflow starts at the CLI or an integrating application, runs through SCU/SCP services, exchanges PDUs and DIMSE commands, and reads or writes DICOM objects; pixel operations dispatch through codecs. The README also documents WADO-RS/STOW-RS/QIDO-RS client and server support. Some subsystem links are documented rather than source-verified because their implementations were not sampled.

Main entry points: [`codecs/dispatch.go`](https://github.com/innovative-io/io-dicom/blob/main/codecs/dispatch.go) (Codec Dispatch), [`media/dicom_object.go`](https://github.com/innovative-io/io-dicom/blob/main/media/dicom_object.go) (DICOM Objects), [`network/pdu_service.go`](https://github.com/innovative-io/io-dicom/blob/main/network/pdu_service.go) (PDU Service), [`services/scp_handlers.go`](https://github.com/innovative-io/io-dicom/blob/main/services/scp_handlers.go) (SCP Handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Applications"]
  node_cli["CLI<br/>[main.go]"]
end

subgraph group_protocol["DICOM Protocol"]
  node_scu["SCU Services<br/>[scu.go]"]
  node_scp["SCP Handlers<br/>[scp_handlers.go]"]
  node_network["PDU Service<br/>[pdu_service.go]"]
  node_dimse["DIMSE Commands"]
end

subgraph group_data["Objects and Metadata"]
  node_media["DICOM Objects<br/>[dicom_object.go]"]
  node_index["Metadata Index<br/>[dicom_index.go]"]
  node_dictionary["DICOM Dictionaries"]
  node_conformance["Conformance Validation<br/>[validator.go]"]
end

subgraph group_pixels["Pixel Processing"]
  node_transcoder["Transfer Transcoder<br/>[transcoder.go]"]
  node_dispatch["Codec Dispatch<br/>[dispatch.go]"]
  node_jpeg["JPEG Codecs<br/>[codec.go]"]
  node_jpeg2000["JPEG2000 Codecs<br/>[codec.go]"]
  node_jpegls["JPEG-LS Codecs<br/>[codec.go]"]
  node_jpegxl["JPEG XL Codecs<br/>[codec.go]"]
  node_rle["RLE Codec<br/>[rle.go]"]
end

subgraph group_web["DICOMweb"]
  node_wado_client["WADO Client<br/>[client.go]"]
  node_wado_server["WADO Server<br/>[server.go]"]
end

node_peer(("DICOM Peer"))
node_web_store[("DICOMweb Store")]

node_cli -->|"starts client"| node_scu
node_cli -->|"starts server"| node_scp
node_scu -.->|"uses associations"| node_network
node_scp -->|"handles PDUs"| node_network
node_scp -->|"dispatches commands"| node_dimse
node_network -->|"parses datasets"| node_media
node_network -.->|"exchanges PDUs"| node_peer
node_media -->|"uses tag metadata"| node_dictionary
node_media -->|"decodes pixels"| node_dispatch
node_transcoder -->|"rewrites pixel data"| node_media
node_transcoder -->|"selects codecs"| node_dispatch
node_dispatch -->|"dispatches JPEG"| node_jpeg
node_dispatch -->|"dispatches JPEG2000"| node_jpeg2000
node_dispatch -->|"dispatches JPEG-LS"| node_jpegls
node_dispatch -->|"dispatches JPEG XL"| node_jpegxl
node_dispatch -->|"dispatches RLE"| node_rle
node_wado_client -.->|"requests DICOMweb"| node_peer
node_peer -.->|"sends HTTP requests"| node_wado_server
node_wado_server -->|"retrieves and stores"| node_web_store
node_wado_server -->|"parses DICOM parts"| node_media
node_index -.->|"indexes DICOM files"| node_media

click node_cli "https://github.com/innovative-io/io-dicom/blob/main/cmd/io-dicom/main.go"
click node_scu "https://github.com/innovative-io/io-dicom/blob/main/services/scu.go"
click node_scp "https://github.com/innovative-io/io-dicom/blob/main/services/scp_handlers.go"
click node_network "https://github.com/innovative-io/io-dicom/blob/main/network/pdu_service.go"
click node_dimse "https://github.com/innovative-io/io-dicom/tree/main/dimse"
click node_media "https://github.com/innovative-io/io-dicom/blob/main/media/dicom_object.go"
click node_index "https://github.com/innovative-io/io-dicom/blob/main/media/dicom_index.go"
click node_dictionary "https://github.com/innovative-io/io-dicom/tree/main/dictionary"
click node_conformance "https://github.com/innovative-io/io-dicom/blob/main/conformance/validator.go"
click node_transcoder "https://github.com/innovative-io/io-dicom/blob/main/transcoder/transcoder.go"
click node_dispatch "https://github.com/innovative-io/io-dicom/blob/main/codecs/dispatch.go"
click node_jpeg "https://github.com/innovative-io/io-dicom/blob/main/codecs/jpeg/codec.go"
click node_jpeg2000 "https://github.com/innovative-io/io-dicom/blob/main/codecs/jpeg2000/codec.go"
click node_jpegls "https://github.com/innovative-io/io-dicom/blob/main/codecs/jpegls/codec.go"
click node_jpegxl "https://github.com/innovative-io/io-dicom/blob/main/codecs/jpegxl/codec.go"
click node_rle "https://github.com/innovative-io/io-dicom/blob/main/codecs/rle/rle.go"
click node_wado_client "https://github.com/innovative-io/io-dicom/blob/main/wado/client.go"
click node_wado_server "https://github.com/innovative-io/io-dicom/blob/main/wado/server.go"

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 toneBlue
class node_scu,node_scp,node_network,node_dimse,node_web_store toneAmber
class node_media,node_index,node_dictionary,node_conformance toneMint
class node_transcoder,node_dispatch,node_jpeg,node_jpeg2000,node_jpegls,node_jpegxl,node_rle toneRose
class node_wado_client,node_wado_server,node_peer toneIndigo
```

## Components

### Applications

- [CLI](https://github.com/innovative-io/io-dicom/blob/main/cmd/io-dicom/main.go): `cmd/io-dicom/main.go`

### DICOM Protocol

- [SCU Services](https://github.com/innovative-io/io-dicom/blob/main/services/scu.go): `services/scu.go`
- [SCP Handlers](https://github.com/innovative-io/io-dicom/blob/main/services/scp_handlers.go): `services/scp_handlers.go`
- [PDU Service](https://github.com/innovative-io/io-dicom/blob/main/network/pdu_service.go): `network/pdu_service.go`
- [DIMSE Commands](https://github.com/innovative-io/io-dicom/tree/main/dimse): `dimse`

### Objects and Metadata

- [DICOM Objects](https://github.com/innovative-io/io-dicom/blob/main/media/dicom_object.go): `media/dicom_object.go`
- [Metadata Index](https://github.com/innovative-io/io-dicom/blob/main/media/dicom_index.go): `media/dicom_index.go`
- [DICOM Dictionaries](https://github.com/innovative-io/io-dicom/tree/main/dictionary): `dictionary`
- [Conformance Validation](https://github.com/innovative-io/io-dicom/blob/main/conformance/validator.go): `conformance/validator.go`

### Pixel Processing

- [Transfer Transcoder](https://github.com/innovative-io/io-dicom/blob/main/transcoder/transcoder.go): `transcoder/transcoder.go`
- [Codec Dispatch](https://github.com/innovative-io/io-dicom/blob/main/codecs/dispatch.go): `codecs/dispatch.go`
- [JPEG Codecs](https://github.com/innovative-io/io-dicom/blob/main/codecs/jpeg/codec.go): `codecs/jpeg/codec.go`
- [JPEG2000 Codecs](https://github.com/innovative-io/io-dicom/blob/main/codecs/jpeg2000/codec.go): `codecs/jpeg2000/codec.go`
- [JPEG-LS Codecs](https://github.com/innovative-io/io-dicom/blob/main/codecs/jpegls/codec.go): `codecs/jpegls/codec.go`
- [JPEG XL Codecs](https://github.com/innovative-io/io-dicom/blob/main/codecs/jpegxl/codec.go): `codecs/jpegxl/codec.go`
- [RLE Codec](https://github.com/innovative-io/io-dicom/blob/main/codecs/rle/rle.go): `codecs/rle/rle.go`

### DICOMweb

- [WADO Client](https://github.com/innovative-io/io-dicom/blob/main/wado/client.go): `wado/client.go`
- [WADO Server](https://github.com/innovative-io/io-dicom/blob/main/wado/server.go): `wado/server.go`

### Other components

- **DICOM Peer**
- **DICOMweb Store**

## Connections

- CLI → SCU Services: starts client (evidence: `cmd/io-dicom/main.go`)
- CLI → SCP Handlers: starts server (evidence: `cmd/io-dicom/main.go`)
- SCU Services → PDU Service: uses associations
- SCP Handlers → PDU Service: handles PDUs (evidence: `services/scp_handlers.go`)
- SCP Handlers → DIMSE Commands: dispatches commands (evidence: `services/scp_handlers.go`)
- PDU Service → DICOM Objects: parses datasets (evidence: `network/pdu_service.go`)
- PDU Service → DICOM Peer: exchanges PDUs
- DICOM Objects → DICOM Dictionaries: uses tag metadata (evidence: `media/dicom_object.go`)
- DICOM Objects → Codec Dispatch: decodes pixels (evidence: `media/dicom_object.go`)
- Transfer Transcoder → DICOM Objects: rewrites pixel data (evidence: `transcoder/transcoder.go`)
- Transfer Transcoder → Codec Dispatch: selects codecs (evidence: `transcoder/transcoder.go`)
- Codec Dispatch → JPEG Codecs: dispatches JPEG (evidence: `codecs/dispatch.go`)
- Codec Dispatch → JPEG2000 Codecs: dispatches JPEG2000 (evidence: `codecs/dispatch.go`)
- Codec Dispatch → JPEG-LS Codecs: dispatches JPEG-LS (evidence: `codecs/dispatch.go`)
- Codec Dispatch → JPEG XL Codecs: dispatches JPEG XL (evidence: `codecs/dispatch.go`)
- Codec Dispatch → RLE Codec: dispatches RLE (evidence: `codecs/dispatch.go`)
- WADO Client → DICOM Peer: requests DICOMweb
- DICOM Peer → WADO Server: sends HTTP requests
- WADO Server → DICOMweb Store: retrieves and stores (evidence: `wado/server.go`)
- WADO Server → DICOM Objects: parses DICOM parts (evidence: `wado/server.go`)
- Metadata Index → DICOM Objects: indexes DICOM files
