# kojix2/pod5.cr architecture

> Architecture diagram of the GitHub repository kojix2/pod5.cr, 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/kojix2/pod5.cr
- Repository: https://github.com/kojix2/pod5.cr

## Overview

pod5.cr is a Crystal binding for the native POD5 library. Its main workflow opens a POD5 file, enumerates or selects reads, and exposes read metadata and on-demand raw or calibrated signal data; records can be materialized to detach them from the reader. The other major workflows create POD5 files from metadata and signals, and compress or decompress signal data with VBZ. Source excerpts were not provided for the runtime modules, so relationships below are limited to capabilities and flows documented in the README.

Main entry points: [`src/pod5/reader.cr`](https://github.com/kojix2/pod5.cr/blob/main/src/pod5/reader.cr) (Reader), [`src/pod5/read.cr`](https://github.com/kojix2/pod5.cr/blob/main/src/pod5/read.cr) (Read record), [`src/pod5/writer.cr`](https://github.com/kojix2/pod5.cr/blob/main/src/pod5/writer.cr) (Writer), [`src/pod5/vbz.cr`](https://github.com/kojix2/pod5.cr/blob/main/src/pod5/vbz.cr) (VBZ codec)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_read["Read POD5"]
  node_entry["Pod5 API<br/>[pod5.cr]"]
  node_reader["Reader<br/>[reader.cr]"]
  node_readrecord["Read record<br/>[read.cr]"]
  node_metadata["Metadata<br/>[metadata.cr]"]
  node_runinfo["Run info<br/>[run_info.cr]"]
end

subgraph group_write["Write POD5"]
  node_writer["Writer<br/>[writer.cr]"]
  node_vbz["VBZ codec<br/>[vbz.cr]"]
end

subgraph group_interop["Native Interop"]
  node_core["Core bindings<br/>[core.cr]"]
  node_nativeapi["Native API bindings<br/>[lib_pod5.cr]"]
  node_native["Native POD5 library"]
end

node_user(("Crystal application"))

node_user -->|"uses"| node_entry
node_entry -->|"opens files"| node_reader
node_reader -->|"yields reads"| node_readrecord
node_reader -->|"selects reads"| node_readrecord
node_readrecord -->|"loads signal"| node_reader
node_readrecord -->|"materializes copy"| node_readrecord
node_user -->|"creates file"| node_writer
node_writer -->|"accepts metadata"| node_metadata
node_metadata -->|"includes"| node_runinfo
node_user -->|"compresses signals"| node_vbz
node_user -->|"decompresses signals"| node_vbz
node_reader -.->|"uses"| node_native
node_writer -.->|"uses"| node_native
node_vbz -.->|"uses"| node_native
node_core -.->|"binds API"| node_nativeapi

click node_entry "https://github.com/kojix2/pod5.cr/blob/main/src/pod5.cr"
click node_reader "https://github.com/kojix2/pod5.cr/blob/main/src/pod5/reader.cr"
click node_readrecord "https://github.com/kojix2/pod5.cr/blob/main/src/pod5/read.cr"
click node_metadata "https://github.com/kojix2/pod5.cr/blob/main/src/pod5/metadata.cr"
click node_runinfo "https://github.com/kojix2/pod5.cr/blob/main/src/pod5/run_info.cr"
click node_writer "https://github.com/kojix2/pod5.cr/blob/main/src/pod5/writer.cr"
click node_vbz "https://github.com/kojix2/pod5.cr/blob/main/src/pod5/vbz.cr"
click node_core "https://github.com/kojix2/pod5.cr/blob/main/src/pod5/core.cr"
click node_nativeapi "https://github.com/kojix2/pod5.cr/blob/main/src/pod5/lib_pod5.cr"

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_entry,node_reader,node_readrecord,node_metadata,node_runinfo toneBlue
class node_writer,node_vbz toneAmber
class node_core,node_nativeapi,node_native toneMint
class node_user toneIndigo
```

## Components

### Read POD5

- [Pod5 API](https://github.com/kojix2/pod5.cr/blob/main/src/pod5.cr): `src/pod5.cr`
- [Reader](https://github.com/kojix2/pod5.cr/blob/main/src/pod5/reader.cr): `src/pod5/reader.cr`
- [Read record](https://github.com/kojix2/pod5.cr/blob/main/src/pod5/read.cr): `src/pod5/read.cr`
- [Metadata](https://github.com/kojix2/pod5.cr/blob/main/src/pod5/metadata.cr): `src/pod5/metadata.cr`
- [Run info](https://github.com/kojix2/pod5.cr/blob/main/src/pod5/run_info.cr): `src/pod5/run_info.cr`

### Write POD5

- [Writer](https://github.com/kojix2/pod5.cr/blob/main/src/pod5/writer.cr): `src/pod5/writer.cr`
- [VBZ codec](https://github.com/kojix2/pod5.cr/blob/main/src/pod5/vbz.cr): `src/pod5/vbz.cr`

### Native Interop

- [Core bindings](https://github.com/kojix2/pod5.cr/blob/main/src/pod5/core.cr): `src/pod5/core.cr`
- [Native API bindings](https://github.com/kojix2/pod5.cr/blob/main/src/pod5/lib_pod5.cr): `src/pod5/lib_pod5.cr`
- **Native POD5 library**

### Other components

- **Crystal application**

## Connections

- Crystal application → Pod5 API: uses (evidence: `README.md`)
- Pod5 API → Reader: opens files (evidence: `README.md`)
- Reader → Read record: yields reads (evidence: `README.md`)
- Reader → Read record: selects reads (evidence: `README.md`)
- Read record → Reader: loads signal (evidence: `README.md`)
- Read record → Read record: materializes copy (evidence: `README.md`)
- Crystal application → Writer: creates file (evidence: `README.md`)
- Writer → Metadata: accepts metadata (evidence: `README.md`)
- Metadata → Run info: includes (evidence: `README.md`)
- Crystal application → VBZ codec: compresses signals (evidence: `README.md`)
- Crystal application → VBZ codec: decompresses signals (evidence: `README.md`)
- Reader → Native POD5 library: uses (evidence: `README.md`)
- Writer → Native POD5 library: uses (evidence: `README.md`)
- VBZ codec → Native POD5 library: uses (evidence: `README.md`)
- Core bindings → Native API bindings: binds API