# bio-cr/bam-filter architecture

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

- Interactive diagram: https://gitdiagram.com/bio-cr/bam-filter
- Repository: https://github.com/bio-cr/bam-filter

## Overview

#### Purpose and CLI Entry Point
`bam-filter` is a Crystal command-line stream filter for SAM, BAM, and CRAM alignment records. Users supply Ruby expressions that decide whether each record is retained. The executable entry point and command orchestration are in:
- `src/bam-filter.cr`
- `src/ke.cr`

#### Processing Pipeline
The main flow is: parse CLI options → open alignment input → configure output format/reference/threads → load optional Ruby scripts → evaluate the expression for every record → write retained records with an updated header. Input and output may be standard streams or paths, with BAM as the default output mode and explicit SAM/CRAM modes.

Primary implementation boundary:
- `src/bam-filter.cr`

#### Embedded Ruby Evaluation Boundary
Filtering logic is intentionally delegated from Crystal to embedded mruby through Anyolite. The application exposes alignment-record fields, SAM flags, and auxiliary tags as Ruby-visible values, then applies Ruby truthiness plus the documented numeric-zero behavior to decide retention. `-r/--require` scripts are loaded before the per-record expression, enabling reusable domain filters.

Relevant code:
- `src/bam-filter.cr`
- `src/ke.cr`

#### Alignment Format and Header Handling
The tool operates on HTS alignment formats: SAM, BAM, and CRAM. CRAM output requires a FASTA reference, while thread count is passed through as a runtime option for underlying alignment I/O. Output generation also controls whether a `@PG` program-header line is appended, making header mutation part of the output boundary.

Relevant paths:
- `src/bam-filter.cr`
- `test/moo.bam`
- `test/moo.cram`

#### Record Data Model Exposed to Expressions
Each record is mapped into a compact Ruby-facing API: core mapping fields (`chr`, `pos`, `mapq`, mate coordinates, etc.), boolean flag predicates, and `tag_XX` auxiliary-tag access. Tags include scalar values and numeric `B` arrays; missing tags become `nil`. This conversion layer is architecture-defining because it isolates native alignment representation from user-authored Ruby.

Relevant paths:
- `src/ke.cr`
- `test/array-tags.sam`

#### Build, Distribution, and Runtime Environment
Crystal is the primary runtime and build target, with dependencies declared through the Crystal shard ecosystem. The repository supports native builds via Make, containerized execution/build through Docker, and GitHub Actions CI/build workflows. Releases are intended to distribute a standalone command-line binary rather than a web service.

Relevant paths:
- `shard.yml`
- `Makefile`
- `Dockerfile`
- `.github/workflows/ci.yml`
- `.github/workflows/build.yml`

#### Verification Assets
The test corpus covers SAM/BAM/CRAM reading, reference-backed CRAM handling, expression thresholds, Ruby helper loading, and array-tag behavior. Tests act as compatibility constraints for the Ruby-to-record data boundary and multi-format pipeline.

Relevant paths:
- `test.sh`
- `test/filters.rb`
- `test/thresholds.rb`
- `test/moo.fa`

Main entry points: [`src/bam-filter.cr`](https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr) (CLI options), [`test.sh`](https://github.com/bio-cr/bam-filter/blob/main/test.sh) (Format and expression tests), [`Makefile`](https://github.com/bio-cr/bam-filter/blob/main/Makefile) (Native build), [`src/ke.cr`](https://github.com/bio-cr/bam-filter/blob/main/src/ke.cr) (Anyolite bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["CLI runtime"]
  node_cli["bam-filter CLI<br/>Crystal entry point<br/>[bam-filter.cr]"]
  node_options["CLI options<br/>[bam-filter.cr]"]
  node_filter_loop["Record filter loop<br/>processing loop<br/>[bam-filter.cr]"]
end

subgraph group_ruby["Embedded Ruby"]
  node_ruby_bridge{{"Anyolite bridge<br/>Crystal–mruby adapter<br/>[ke.cr]"}}
  node_ruby_scripts["Required Ruby scripts<br/>Ruby extensions<br/>[bam-filter.cr]"]
  node_ruby_expression["Filter expression<br/>Ruby predicate<br/>[bam-filter.cr]"]
  node_record_api["Ruby record API<br/>record projection<br/>[ke.cr]"]
end

subgraph group_formats["Alignment I/O"]
  node_alignment_input[("SAM/BAM/CRAM input<br/>alignment reader<br/>[bam-filter.cr]")]
  node_reference["FASTA reference<br/>CRAM reference<br/>[bam-filter.cr]"]
  node_output_writer[("Alignment output<br/>SAM/BAM/CRAM writer<br/>[bam-filter.cr]")]
  node_header["Output header<br/>header mutation<br/>[bam-filter.cr]"]
end

subgraph group_delivery["Build &amp; delivery"]
  node_shard["Crystal dependencies<br/>shard manifest<br/>[shard.yml]"]
  node_native_build["Native build<br/>Make build"]
  node_container["Container build/runtime<br/>Docker"]
  node_ci["CI verification<br/>GitHub Actions<br/>[ci.yml]"]
  node_release["Binary release build<br/>GitHub Actions<br/>[build.yml]"]
end

node_test_suite["Format and expression tests<br/>shell test suite<br/>[test.sh]"]
node_ruby_fixtures["Ruby test helpers<br/>Ruby fixtures<br/>[filters.rb]"]
node_cram_fixture["CRAM reference fixture<br/>FASTA fixture<br/>[moo.fa]"]

node_cli -->|"parses"| node_options
node_options -->|"opens"| node_alignment_input
node_options -->|"configures format and threads"| node_output_writer
node_options -->|"loads -r scripts"| node_ruby_scripts
node_alignment_input -->|"records"| node_filter_loop
node_filter_loop -->|"projects record"| node_ruby_bridge
node_ruby_bridge -->|"exposes"| node_record_api
node_ruby_scripts -->|"extends evaluation context"| node_ruby_expression
node_record_api -->|"evaluated against"| node_ruby_expression
node_ruby_expression -->|"retention decision"| node_filter_loop
node_filter_loop -->|"retained records"| node_output_writer
node_header -->|"writes updated header"| node_output_writer
node_reference -->|"required for CRAM"| node_output_writer
node_shard -->|"resolves dependencies"| node_native_build
node_native_build -.->|"builds binary"| node_cli
node_container -.->|"runs/builds"| node_cli
node_ci -->|"runs"| node_test_suite
node_release -->|"builds"| node_native_build
node_test_suite -->|"loads"| node_ruby_fixtures
node_test_suite -->|"uses for CRAM"| node_cram_fixture

click node_cli "https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr"
click node_options "https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr"
click node_filter_loop "https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr"
click node_ruby_bridge "https://github.com/bio-cr/bam-filter/blob/main/src/ke.cr"
click node_ruby_scripts "https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr"
click node_ruby_expression "https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr"
click node_record_api "https://github.com/bio-cr/bam-filter/blob/main/src/ke.cr"
click node_alignment_input "https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr"
click node_reference "https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr"
click node_output_writer "https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr"
click node_header "https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr"
click node_shard "https://github.com/bio-cr/bam-filter/blob/main/shard.yml"
click node_native_build "https://github.com/bio-cr/bam-filter/blob/main/Makefile"
click node_container "https://github.com/bio-cr/bam-filter/blob/main/Dockerfile"
click node_ci "https://github.com/bio-cr/bam-filter/blob/main/.github/workflows/ci.yml"
click node_release "https://github.com/bio-cr/bam-filter/blob/main/.github/workflows/build.yml"
click node_test_suite "https://github.com/bio-cr/bam-filter/blob/main/test.sh"
click node_ruby_fixtures "https://github.com/bio-cr/bam-filter/blob/main/test/filters.rb"
click node_cram_fixture "https://github.com/bio-cr/bam-filter/blob/main/test/moo.fa"

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_options,node_filter_loop toneBlue
class node_ruby_bridge,node_ruby_scripts,node_ruby_expression,node_record_api toneAmber
class node_alignment_input,node_reference,node_output_writer,node_header toneMint
class node_shard,node_native_build,node_container,node_ci,node_release toneRose
class node_test_suite,node_ruby_fixtures,node_cram_fixture toneNeutral
```

## Components

### CLI runtime

- [bam-filter CLI](https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr): Crystal entry point · Parses options and orchestrates record filtering. · `src/bam-filter.cr`
- [CLI options](https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr): options · Selects input/output, format, reference, threads, scripts, and expression. · `src/bam-filter.cr`
- [Record filter loop](https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr): processing loop · Evaluates every record and writes retained records. · `src/bam-filter.cr`

### Embedded Ruby

- [Anyolite bridge](https://github.com/bio-cr/bam-filter/blob/main/src/ke.cr): Crystal–mruby adapter · Maps native records into Ruby-visible values. · `src/ke.cr`
- [Required Ruby scripts](https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr): Ruby extensions · Reusable filters loaded before the expression. · `src/bam-filter.cr`
- [Filter expression](https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr): Ruby predicate · Ruby truthiness and numeric-zero behavior determine retention. · `src/bam-filter.cr`
- [Ruby record API](https://github.com/bio-cr/bam-filter/blob/main/src/ke.cr): record projection · Core fields, flag predicates, scalar tags, and B arrays. · `src/ke.cr`

### Alignment I/O

- [SAM/BAM/CRAM input](https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr): alignment reader · Reads a path or standard input. · `src/bam-filter.cr`
- [FASTA reference](https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr): CRAM reference · Required for CRAM output. · `src/bam-filter.cr`
- [Alignment output](https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr): SAM/BAM/CRAM writer · Writes a path or standard output; BAM is the default. · `src/bam-filter.cr`
- [Output header](https://github.com/bio-cr/bam-filter/blob/main/src/bam-filter.cr): header mutation · Optionally appends a @PG program line. · `src/bam-filter.cr`

### Build & delivery

- [Crystal dependencies](https://github.com/bio-cr/bam-filter/blob/main/shard.yml): shard manifest · `shard.yml`
- [Native build](https://github.com/bio-cr/bam-filter/blob/main/Makefile): Make build · `Makefile`
- [Container build/runtime](https://github.com/bio-cr/bam-filter/blob/main/Dockerfile): Docker · `Dockerfile`
- [CI verification](https://github.com/bio-cr/bam-filter/blob/main/.github/workflows/ci.yml): GitHub Actions · `.github/workflows/ci.yml`
- [Binary release build](https://github.com/bio-cr/bam-filter/blob/main/.github/workflows/build.yml): GitHub Actions · Produces the standalone command binary. · `.github/workflows/build.yml`

### Other components

- [Format and expression tests](https://github.com/bio-cr/bam-filter/blob/main/test.sh): shell test suite · Compatibility coverage for formats, scripts, thresholds, and tags. · `test.sh`
- [Ruby test helpers](https://github.com/bio-cr/bam-filter/blob/main/test/filters.rb): Ruby fixtures · `test/filters.rb`
- [CRAM reference fixture](https://github.com/bio-cr/bam-filter/blob/main/test/moo.fa): FASTA fixture · `test/moo.fa`

## Connections

- bam-filter CLI → CLI options: parses
- CLI options → SAM/BAM/CRAM input: opens
- CLI options → Alignment output: configures format and threads
- CLI options → Required Ruby scripts: loads -r scripts
- SAM/BAM/CRAM input → Record filter loop: records
- Record filter loop → Anyolite bridge: projects record
- Anyolite bridge → Ruby record API: exposes
- Required Ruby scripts → Filter expression: extends evaluation context
- Ruby record API → Filter expression: evaluated against
- Filter expression → Record filter loop: retention decision
- Record filter loop → Alignment output: retained records
- Output header → Alignment output: writes updated header
- FASTA reference → Alignment output: required for CRAM
- Crystal dependencies → Native build: resolves dependencies
- Native build → bam-filter CLI: builds binary
- Container build/runtime → bam-filter CLI: runs/builds
- CI verification → Format and expression tests: runs
- Binary release build → Native build: builds
- Format and expression tests → Ruby test helpers: loads
- Format and expression tests → CRAM reference fixture: uses for CRAM
