# natera-open-source/vep-rs architecture

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

- Interactive diagram: https://gitdiagram.com/natera-open-source/vep-rs
- Repository: https://github.com/natera-open-source/vep-rs

## Overview

vep-rs is a Rust reimplementation of Ensembl VEP. Users provide variants and a transcript cache; the CLI parses and normalizes records, matches transcripts, computes consequences, adds plugin annotations, applies pick behavior, and writes VEP-compatible formats. The cache can be built from Ensembl inputs or converted from Perl VEP data. The map includes major documented capabilities, but some links to unsampled subsystems are based on README statements rather than inspected implementation details.

Main entry points: [`crates/vep-cli/src/pipeline.rs`](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cli/src/pipeline.rs) (Batch pipeline), [`crates/vep-cli/src/runner.rs`](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cli/src/runner.rs) (Run coordinator), [`crates/vep-effects/src/consequences.rs`](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-effects/src/consequences.rs) (Consequence calculation), [`crates/vep-io/src/output`](https://github.com/natera-open-source/vep-rs/tree/main/crates/vep-io/src/output) (VEP output formats)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cache["Cache preparation"]
  node_cache_builder["Cache builder<br/>[main.rs]"]
  node_cache_conversion["Perl cache converter<br/>[main.rs]"]
  node_cache_data[("JSON transcript cache")]
end

subgraph group_runtime["Annotation runtime"]
  node_cli["VEP CLI<br/>[main.rs]"]
  node_runner["Run coordinator<br/>[runner.rs]"]
  node_pipeline["Batch pipeline<br/>[pipeline.rs]"]
  node_cache_loader["Cache loading<br/>[json_cache.rs]"]
  node_transcript_index["Transcript lookup"]
  node_variation_matcher["Known variation match"]
  node_pick["Consequence selection<br/>[pick.rs]"]
end

subgraph group_biology["Effect computation"]
  node_variant_types["Variant model<br/>[variant.rs]"]
  node_transcript_model["Transcript model<br/>[transcript.rs]"]
  node_consequence_terms["Consequence terms<br/>[consequence.rs]"]
  node_effect_calculator["Consequence calculation<br/>[consequences.rs]"]
  node_coding_effects["Coding effects<br/>[coding.rs]"]
  node_sv_effects["Structural variant effects<br/>[mod.rs]"]
  node_hgvs["HGVS notation<br/>[hgvs.rs]"]
end

subgraph group_extensions["Annotation extensions"]
  node_builtin_plugins["Built-in databases<br/>[registry.rs]"]
  node_tabix["Tabix query engine<br/>[tabix.rs]"]
  node_dynamic_plugins["Dynamic plugins<br/>[loader.rs]"]
  node_plugin_registry["Plugin registry<br/>[registry.rs]"]
end

subgraph group_formats["Input and output"]
  node_vcf_parser["VCF parsing<br/>[vcf_parser.rs]"]
  node_output_formats["VEP output formats"]
  node_parquet_output["Parquet output<br/>[parquet.rs]"]
end

node_user(("Variant data user"))
node_external_plugins["Plugin libraries"]
node_ensembl_inputs["Ensembl files"]
node_perl_cache[("Existing Perl VEP cache")]

node_user -->|"supplies variants"| node_cli
node_ensembl_inputs -->|"provides source files"| node_cache_builder
node_cache_builder -->|"builds cache"| node_cache_data
node_perl_cache -->|"provides cache"| node_cache_conversion
node_cache_conversion -->|"converts cache"| node_cache_data
node_cli -.->|"starts run"| node_runner
node_runner -->|"runs batches"| node_pipeline
node_runner -->|"loads cache"| node_cache_loader
node_cache_data -->|"reads cache"| node_cache_loader
node_pipeline -->|"parses records"| node_vcf_parser
node_pipeline -->|"looks up transcripts"| node_transcript_index
node_pipeline -->|"matches variations"| node_variation_matcher
node_pipeline -.->|"calculates effects"| node_effect_calculator
node_pipeline -->|"selects results"| node_pick
node_pipeline -.->|"renders output"| node_output_formats
node_vcf_parser -->|"creates variants"| node_variant_types
node_effect_calculator -->|"delegates coding"| node_coding_effects
node_effect_calculator -->|"dispatches SVs"| node_sv_effects
node_effect_calculator -->|"assigns terms"| node_consequence_terms
node_effect_calculator -.->|"evaluates overlap"| node_transcript_model
node_runner -.->|"supports HGVS"| node_hgvs
node_runner -.->|"configures plugins"| node_builtin_plugins
node_builtin_plugins -->|"queries data"| node_tabix
node_runner -.->|"loads plugins"| node_plugin_registry
node_plugin_registry -->|"loads libraries"| node_dynamic_plugins
node_dynamic_plugins -->|"loads at runtime"| node_external_plugins
node_output_formats -.->|"supports Parquet"| node_parquet_output
node_output_formats -->|"writes results"| node_user

click node_cache_builder "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cache-builder/src/main.rs"
click node_cache_conversion "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cache-converter/src/main.rs"
click node_cli "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cli/src/main.rs"
click node_runner "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cli/src/runner.rs"
click node_pipeline "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cli/src/pipeline.rs"
click node_cache_loader "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cli/src/json_cache.rs"
click node_transcript_index "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cli/src/transcript_index.rs"
click node_variation_matcher "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cli/src/variation_matcher.rs"
click node_pick "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cli/src/pick.rs"
click node_variant_types "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-core/src/variant.rs"
click node_transcript_model "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-core/src/transcript.rs"
click node_consequence_terms "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-core/src/consequence.rs"
click node_effect_calculator "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-effects/src/consequences.rs"
click node_coding_effects "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-effects/src/coding.rs"
click node_sv_effects "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-effects/src/sv/mod.rs"
click node_hgvs "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-effects/src/hgvs.rs"
click node_builtin_plugins "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-builtins/src/registry.rs"
click node_tabix "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-builtins/src/tabix.rs"
click node_dynamic_plugins "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-plugin/src/loader.rs"
click node_plugin_registry "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-plugin/src/registry.rs"
click node_vcf_parser "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cli/src/vcf_parser.rs"
click node_output_formats "https://github.com/natera-open-source/vep-rs/tree/main/crates/vep-io/src/output"
click node_parquet_output "https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-io/src/output/parquet.rs"

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_cache_builder,node_cache_conversion,node_cache_data,node_user toneBlue
class node_cli,node_runner,node_pipeline,node_cache_loader,node_transcript_index,node_variation_matcher,node_pick,node_perl_cache toneAmber
class node_variant_types,node_transcript_model,node_consequence_terms,node_effect_calculator,node_coding_effects,node_sv_effects,node_hgvs toneMint
class node_builtin_plugins,node_tabix,node_dynamic_plugins,node_plugin_registry toneRose
class node_vcf_parser,node_output_formats,node_parquet_output,node_external_plugins,node_ensembl_inputs toneIndigo
```

## Components

### Cache preparation

- [Cache builder](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cache-builder/src/main.rs): `crates/vep-cache-builder/src/main.rs`
- [Perl cache converter](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cache-converter/src/main.rs): `crates/vep-cache-converter/src/main.rs`
- **JSON transcript cache**

### Annotation runtime

- [VEP CLI](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cli/src/main.rs): `crates/vep-cli/src/main.rs`
- [Run coordinator](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cli/src/runner.rs): `crates/vep-cli/src/runner.rs`
- [Batch pipeline](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cli/src/pipeline.rs): `crates/vep-cli/src/pipeline.rs`
- [Cache loading](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cli/src/json_cache.rs): `crates/vep-cli/src/json_cache.rs`
- [Transcript lookup](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cli/src/transcript_index.rs): `crates/vep-cli/src/transcript_index.rs`
- [Known variation match](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cli/src/variation_matcher.rs): `crates/vep-cli/src/variation_matcher.rs`
- [Consequence selection](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cli/src/pick.rs): `crates/vep-cli/src/pick.rs`

### Effect computation

- [Variant model](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-core/src/variant.rs): `crates/vep-core/src/variant.rs`
- [Transcript model](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-core/src/transcript.rs): `crates/vep-core/src/transcript.rs`
- [Consequence terms](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-core/src/consequence.rs): `crates/vep-core/src/consequence.rs`
- [Consequence calculation](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-effects/src/consequences.rs): `crates/vep-effects/src/consequences.rs`
- [Coding effects](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-effects/src/coding.rs): `crates/vep-effects/src/coding.rs`
- [Structural variant effects](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-effects/src/sv/mod.rs): `crates/vep-effects/src/sv/mod.rs`
- [HGVS notation](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-effects/src/hgvs.rs): `crates/vep-effects/src/hgvs.rs`

### Annotation extensions

- [Built-in databases](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-builtins/src/registry.rs): `crates/vep-builtins/src/registry.rs`
- [Tabix query engine](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-builtins/src/tabix.rs): `crates/vep-builtins/src/tabix.rs`
- [Dynamic plugins](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-plugin/src/loader.rs): `crates/vep-plugin/src/loader.rs`
- [Plugin registry](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-plugin/src/registry.rs): `crates/vep-plugin/src/registry.rs`

### Input and output

- [VCF parsing](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-cli/src/vcf_parser.rs): `crates/vep-cli/src/vcf_parser.rs`
- [VEP output formats](https://github.com/natera-open-source/vep-rs/tree/main/crates/vep-io/src/output): `crates/vep-io/src/output`
- [Parquet output](https://github.com/natera-open-source/vep-rs/blob/main/crates/vep-io/src/output/parquet.rs): `crates/vep-io/src/output/parquet.rs`

### Other components

- **Variant data user**
- **Plugin libraries**
- **Ensembl files**
- **Existing Perl VEP cache**

## Connections

- Variant data user → VEP CLI: supplies variants (evidence: `README.md`)
- Ensembl files → Cache builder: provides source files (evidence: `README.md`)
- Cache builder → JSON transcript cache: builds cache (evidence: `README.md`)
- Existing Perl VEP cache → Perl cache converter: provides cache (evidence: `README.md`)
- Perl cache converter → JSON transcript cache: converts cache (evidence: `README.md`)
- VEP CLI → Run coordinator: starts run
- Run coordinator → Batch pipeline: runs batches (evidence: `crates/vep-cli/src/runner.rs`)
- Run coordinator → Cache loading: loads cache (evidence: `crates/vep-cli/src/runner.rs`)
- JSON transcript cache → Cache loading: reads cache (evidence: `README.md`)
- Batch pipeline → VCF parsing: parses records (evidence: `crates/vep-cli/src/pipeline.rs`)
- Batch pipeline → Transcript lookup: looks up transcripts (evidence: `crates/vep-cli/src/pipeline.rs`)
- Batch pipeline → Known variation match: matches variations (evidence: `crates/vep-cli/src/pipeline.rs`)
- Batch pipeline → Consequence calculation: calculates effects
- Batch pipeline → Consequence selection: selects results (evidence: `crates/vep-cli/src/pipeline.rs`)
- Batch pipeline → VEP output formats: renders output
- VCF parsing → Variant model: creates variants (evidence: `crates/vep-cli/src/vcf_parser.rs`)
- Consequence calculation → Coding effects: delegates coding (evidence: `crates/vep-effects/src/consequences.rs`)
- Consequence calculation → Structural variant effects: dispatches SVs (evidence: `crates/vep-effects/src/consequences.rs`)
- Consequence calculation → Consequence terms: assigns terms (evidence: `crates/vep-effects/src/consequences.rs`)
- Consequence calculation → Transcript model: evaluates overlap
- Run coordinator → HGVS notation: supports HGVS
- Run coordinator → Built-in databases: configures plugins
- Built-in databases → Tabix query engine: queries data
- Run coordinator → Plugin registry: loads plugins
- Plugin registry → Dynamic plugins: loads libraries (evidence: `crates/vep-plugin/src/registry.rs`)
- Dynamic plugins → Plugin libraries: loads at runtime (evidence: `README.md`)
- VEP output formats → Parquet output: supports Parquet
- VEP output formats → Variant data user: writes results (evidence: `README.md`)