# kojix2/minimap2-cr architecture

> Architecture diagram of the GitHub repository kojix2/minimap2-cr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kojix2/minimap2-cr
- Repository: https://github.com/kojix2/minimap2-cr

## Overview

#### Purpose and public entry point

`minimap2-cr` is a Crystal shard exposing in-process bindings to the minimap2 long-read mapper. Consumers load `src/minimap2.cr`, construct a `Minimap2::Aligner`, load a FASTA-backed reference index, and map query sequences without invoking the minimap2 CLI.

Paths: `src/minimap2.cr`, `src/minimap2/aligner.cr`

#### Native dependency lifecycle

The shard vendors/builds minimap2 during dependency installation through its postinstall configuration. `ext/build.cr` is the native build boundary: it produces the minimap2 library consumed by Crystal FFI. Linux builds require a C toolchain and zlib headers; runtime library discovery may require `LD_LIBRARY_PATH` pointing at `ext`.

Paths: `shard.yml`, `ext/build.cr`, `src/minimap2/ffi.cr`

#### FFI boundary

`Minimap2::LibMinimap2` declares bindings to minimap2’s C API, including native structures, constants, flags, index operations, and mapping calls. This file is the ABI-sensitive boundary: Crystal code should translate inputs/options before crossing it and convert native results immediately after return.

Paths: `src/minimap2/ffi.cr`, `src/minimap2/types.cr`

#### Aligner lifecycle and mapping flow

`Minimap2::Aligner` owns the loaded native reference/index and configured mapping options. Construction follows either the convenience initializer or builder pipeline; mapping accepts a query plus high-level tag toggles (`cs`, `md`, `ds`) and optional raw minimap2 flags. It invokes native mapping and returns Crystal mapping records. The aligner also provides indexed reference subsequence access via `seq(name, start, stop)`.

Paths: `src/minimap2/aligner.cr`, `src/minimap2/types.cr`

#### Configuration and builder stage

`Minimap2::Builder` is the explicit configuration layer. It selects minimap2 presets (such as ONT, HiFi, splice, assembly, and short-read modes), enables output behavior such as CIGAR generation, sets indexing threads, and loads a reference path. It materializes an `Aligner`, separating option assembly from native index creation.

Paths: `src/minimap2/builder.cr`, `src/minimap2/aligner.cr`

#### Data model and sequence utilities

Crystal-facing result and option types encapsulate mapping outputs, including coordinates, alignment metadata, and requested `cs`/`MD`/`ds` tag fields. Sequence-oriented utilities provide operations such as reverse complement independently of the native mapper.

Paths: `src/minimap2/types.cr`, `src/minimap2/seq_util.cr`

#### Validation and usage shape

The primary integration contract is demonstrated by mapping fixture/query sequences against FASTA input and asserting returned alignments. The example shows intended library embedding: configure once, then issue repeated `map` calls against the loaded index.

Paths: `spec/minimap2_spec.cr`, `spec/fixtures/test_data.fasta`, `examples/aligner_example.cr`

Main entry points: [`src/minimap2/aligner.cr`](https://github.com/kojix2/minimap2-cr/blob/main/src/minimap2/aligner.cr) (Aligner), [`src/minimap2/builder.cr`](https://github.com/kojix2/minimap2-cr/blob/main/src/minimap2/builder.cr) (Builder), [`src/minimap2/types.cr`](https://github.com/kojix2/minimap2-cr/blob/main/src/minimap2/types.cr) (Crystal types), [`src/minimap2.cr`](https://github.com/kojix2/minimap2-cr/blob/main/src/minimap2.cr) (minimap2 entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_crystal["Crystal API"]
  node_entry["minimap2 entry point<br/>Crystal require<br/>[minimap2.cr]"]
  node_builder["Builder<br/>configuration<br/>[builder.cr]"]
  node_aligner["Aligner<br/>mapping facade<br/>[aligner.cr]"]
  node_types["Crystal types<br/>data model<br/>[types.cr]"]
  node_seq_util["Sequence utilities<br/>sequence helper<br/>[seq_util.cr]"]
end

subgraph group_native["Native integration"]
  node_ffi{{"LibMinimap2 FFI<br/>C ABI bindings<br/>[ffi.cr]"}}
  node_build["Native build<br/>postinstall build<br/>[build.cr]"]
  node_shard["Shard configuration<br/>package config<br/>[shard.yml]"]
  node_minimap2_lib[("minimap2 library<br/>native mapper")]
end

node_fasta["FASTA reference<br/>reference input<br/>[test_data.fasta]"]
node_example["Embedding example<br/>usage example<br/>[aligner_example.cr]"]
node_spec["Integration spec<br/>validation<br/>[minimap2_spec.cr]"]

node_entry -->|"exposes"| node_builder
node_entry -->|"exposes"| node_aligner
node_entry -->|"loads"| node_types
node_builder -->|"materializes"| node_aligner
node_builder -->|"assembles options"| node_types
node_builder -->|"loads reference path"| node_fasta
node_aligner -->|"accepts options and returns records"| node_types
node_aligner -->|"creates index and maps"| node_ffi
node_seq_util -->|"supports sequences"| node_types
node_ffi -->|"calls C API"| node_minimap2_lib
node_shard -->|"postinstall invokes"| node_build
node_build -->|"produces"| node_minimap2_lib
node_example -->|"configures"| node_builder
node_example -->|"repeated map calls"| node_aligner
node_spec -->|"validates mapping"| node_aligner
node_spec -->|"uses fixture"| node_fasta

click node_entry "https://github.com/kojix2/minimap2-cr/blob/main/src/minimap2.cr"
click node_builder "https://github.com/kojix2/minimap2-cr/blob/main/src/minimap2/builder.cr"
click node_aligner "https://github.com/kojix2/minimap2-cr/blob/main/src/minimap2/aligner.cr"
click node_types "https://github.com/kojix2/minimap2-cr/blob/main/src/minimap2/types.cr"
click node_seq_util "https://github.com/kojix2/minimap2-cr/blob/main/src/minimap2/seq_util.cr"
click node_ffi "https://github.com/kojix2/minimap2-cr/blob/main/src/minimap2/ffi.cr"
click node_build "https://github.com/kojix2/minimap2-cr/blob/main/ext/build.cr"
click node_shard "https://github.com/kojix2/minimap2-cr/blob/main/shard.yml"
click node_fasta "https://github.com/kojix2/minimap2-cr/blob/main/spec/fixtures/test_data.fasta"
click node_example "https://github.com/kojix2/minimap2-cr/blob/main/examples/aligner_example.cr"
click node_spec "https://github.com/kojix2/minimap2-cr/blob/main/spec/minimap2_spec.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_builder,node_aligner,node_types,node_seq_util toneBlue
class node_ffi,node_build,node_shard,node_minimap2_lib toneAmber
class node_fasta,node_example,node_spec toneNeutral
```

## Components

### Crystal API

Public library surface and mapping workflow.

- [minimap2 entry point](https://github.com/kojix2/minimap2-cr/blob/main/src/minimap2.cr): Crystal require · Public shard entry point. · `src/minimap2.cr`
- [Builder](https://github.com/kojix2/minimap2-cr/blob/main/src/minimap2/builder.cr): configuration · Assembles presets, options, threads, and reference input. · `src/minimap2/builder.cr`
- [Aligner](https://github.com/kojix2/minimap2-cr/blob/main/src/minimap2/aligner.cr): mapping facade · Owns the native index and exposes map and seq. · `src/minimap2/aligner.cr`
- [Crystal types](https://github.com/kojix2/minimap2-cr/blob/main/src/minimap2/types.cr): data model · Options and Crystal-facing mapping records. · `src/minimap2/types.cr`
- [Sequence utilities](https://github.com/kojix2/minimap2-cr/blob/main/src/minimap2/seq_util.cr): sequence helper · Provides Crystal-side operations such as reverse complement. · `src/minimap2/seq_util.cr`

### Native integration

Vendored minimap2 build and ABI boundary.

- [LibMinimap2 FFI](https://github.com/kojix2/minimap2-cr/blob/main/src/minimap2/ffi.cr): C ABI bindings · ABI-sensitive native declarations, flags, structures, and calls. · `src/minimap2/ffi.cr`
- [Native build](https://github.com/kojix2/minimap2-cr/blob/main/ext/build.cr): postinstall build · Builds the vendored minimap2 library. · `ext/build.cr`
- [Shard configuration](https://github.com/kojix2/minimap2-cr/blob/main/shard.yml): package config · Triggers the native postinstall lifecycle. · `shard.yml`
- **minimap2 library**: native mapper · Built C library loaded by Crystal FFI.

### Other components

- [FASTA reference](https://github.com/kojix2/minimap2-cr/blob/main/spec/fixtures/test_data.fasta): reference input · Loaded to create the native reference index. · `spec/fixtures/test_data.fasta`
- [Embedding example](https://github.com/kojix2/minimap2-cr/blob/main/examples/aligner_example.cr): usage example · Configure once and issue repeated map calls. · `examples/aligner_example.cr`
- [Integration spec](https://github.com/kojix2/minimap2-cr/blob/main/spec/minimap2_spec.cr): validation · Maps fixture queries and asserts returned alignments. · `spec/minimap2_spec.cr`

## Connections

- minimap2 entry point → Builder: exposes
- minimap2 entry point → Aligner: exposes
- minimap2 entry point → Crystal types: loads
- Builder → Aligner: materializes
- Builder → Crystal types: assembles options
- Builder → FASTA reference: loads reference path
- Aligner → Crystal types: accepts options and returns records
- Aligner → LibMinimap2 FFI: creates index and maps
- Sequence utilities → Crystal types: supports sequences
- LibMinimap2 FFI → minimap2 library: calls C API
- Shard configuration → Native build: postinstall invokes
- Native build → minimap2 library: produces
- Embedding example → Builder: configures
- Embedding example → Aligner: repeated map calls
- Integration spec → Aligner: validates mapping
- Integration spec → FASTA reference: uses fixture
