# paulmndn/bescreen architecture

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

- Interactive diagram: https://gitdiagram.com/paulmndn/bescreen
- Repository: https://github.com/paulmndn/bescreen

## Overview

BEscreen is a command-line base-editing guide designer. Users provide variants, genes/transcripts, or genomic regions; the CLI selects a design mode, which generates candidate guides and annotations for output. The documented capabilities include rsID and protein-variant input, VEP annotation, BLAST match counts, and guide BAM output. The graph includes all indexed core modules. Some integrations are documented or imported but their invocation is not visible in the excerpts, so those links are marked unverified.

Main entry points: [`bescreen/bedesigner.py`](https://github.com/paulmndn/bescreen/blob/main/bescreen/bedesigner.py) (Variant guides), [`bescreen/besaturate.py`](https://github.com/paulmndn/bescreen/blob/main/bescreen/besaturate.py) (Gene saturation), [`bescreen/beregion.py`](https://github.com/paulmndn/bescreen/blob/main/bescreen/beregion.py) (Region guides), [`bescreen/bescreen.py`](https://github.com/paulmndn/bescreen/blob/main/bescreen/bescreen.py) (Mode dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and routing"]
  node_cli["Mode dispatcher<br/>[bescreen.py]"]
end

subgraph group_design["Guide design"]
  node_variant_design["Variant guides<br/>[bedesigner.py]"]
  node_gene_design["Gene saturation<br/>[besaturate.py]"]
  node_region_design["Region guides<br/>[beregion.py]"]
end

subgraph group_annotation["Variant annotation"]
  node_vep["VEP annotation<br/>[get_vep.py]"]
  node_dbsnp[("dbSNP lookup and database builder<br/>[dbsnp_sqlite3.py]")]
  node_blast["Guide BLAST matching<br/>[blast_guides.py]"]
end

subgraph group_support["Shared utilities"]
  node_shared["Sequence and annotation utilities<br/>[shared.py]"]
  node_protein["Protein variant conversion<br/>[protein_variant.py]"]
end

node_user(("CLI user"))
node_reference[("Reference genome and annotations")]
node_vep_service["Ensembl VEP"]
node_blast_service["NCBI BLAST tools"]
node_results["Guide tables and BAM"]

node_user -->|"provides input"| node_cli
node_cli -->|"routes variants"| node_variant_design
node_cli -->|"routes genes"| node_gene_design
node_cli -->|"routes regions"| node_region_design
node_variant_design -->|"queries rsIDs"| node_dbsnp
node_variant_design -.->|"converts protein input"| node_protein
node_variant_design -->|"uses utilities"| node_shared
node_gene_design -->|"uses utilities"| node_shared
node_region_design -->|"uses utilities"| node_shared
node_variant_design -->|"requests annotations"| node_vep
node_gene_design -->|"requests annotations"| node_vep
node_region_design -->|"requests annotations"| node_vep
node_vep -->|"runs offline"| node_vep_service
node_variant_design -.->|"checks guide matches"| node_blast
node_gene_design -.->|"checks guide matches"| node_blast
node_region_design -.->|"checks guide matches"| node_blast
node_blast -->|"runs search"| node_blast_service
node_variant_design -.->|"reads genome"| node_reference
node_gene_design -.->|"reads genome"| node_reference
node_region_design -.->|"reads genome"| node_reference
node_variant_design -->|"writes guides and BAM"| node_results
node_gene_design -->|"writes guides and BAM"| node_results
node_region_design -->|"writes guides and BAM"| node_results

click node_cli "https://github.com/paulmndn/bescreen/blob/main/bescreen/bescreen.py"
click node_variant_design "https://github.com/paulmndn/bescreen/blob/main/bescreen/bedesigner.py"
click node_gene_design "https://github.com/paulmndn/bescreen/blob/main/bescreen/besaturate.py"
click node_region_design "https://github.com/paulmndn/bescreen/blob/main/bescreen/beregion.py"
click node_shared "https://github.com/paulmndn/bescreen/blob/main/bescreen/shared.py"
click node_protein "https://github.com/paulmndn/bescreen/blob/main/bescreen/protein_variant.py"
click node_vep "https://github.com/paulmndn/bescreen/blob/main/bescreen/get_vep.py"
click node_dbsnp "https://github.com/paulmndn/bescreen/blob/main/bescreen/dbsnp_sqlite3.py"
click node_blast "https://github.com/paulmndn/bescreen/blob/main/bescreen/blast_guides.py"

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_user toneBlue
class node_variant_design,node_gene_design,node_region_design,node_reference toneAmber
class node_vep,node_dbsnp,node_blast toneMint
class node_shared,node_protein toneRose
class node_vep_service,node_blast_service,node_results toneIndigo
```

## Components

### CLI and routing

- [Mode dispatcher](https://github.com/paulmndn/bescreen/blob/main/bescreen/bescreen.py): `bescreen/bescreen.py`

### Guide design

- [Variant guides](https://github.com/paulmndn/bescreen/blob/main/bescreen/bedesigner.py): `bescreen/bedesigner.py`
- [Gene saturation](https://github.com/paulmndn/bescreen/blob/main/bescreen/besaturate.py): `bescreen/besaturate.py`
- [Region guides](https://github.com/paulmndn/bescreen/blob/main/bescreen/beregion.py): `bescreen/beregion.py`

### Variant annotation

- [VEP annotation](https://github.com/paulmndn/bescreen/blob/main/bescreen/get_vep.py): `bescreen/get_vep.py`
- [dbSNP lookup and database builder](https://github.com/paulmndn/bescreen/blob/main/bescreen/dbsnp_sqlite3.py): `bescreen/dbsnp_sqlite3.py`
- [Guide BLAST matching](https://github.com/paulmndn/bescreen/blob/main/bescreen/blast_guides.py): `bescreen/blast_guides.py`

### Shared utilities

- [Sequence and annotation utilities](https://github.com/paulmndn/bescreen/blob/main/bescreen/shared.py): `bescreen/shared.py`
- [Protein variant conversion](https://github.com/paulmndn/bescreen/blob/main/bescreen/protein_variant.py): `bescreen/protein_variant.py`

### Other components

- **CLI user**
- **Reference genome and annotations**
- **Ensembl VEP**
- **NCBI BLAST tools**
- **Guide tables and BAM**

## Connections

- CLI user → Mode dispatcher: provides input (evidence: `README.md`)
- Mode dispatcher → Variant guides: routes variants (evidence: `README.md`)
- Mode dispatcher → Gene saturation: routes genes (evidence: `README.md`)
- Mode dispatcher → Region guides: routes regions (evidence: `README.md`)
- Variant guides → dbSNP lookup and database builder: queries rsIDs (evidence: `bescreen/bedesigner.py`)
- Variant guides → Protein variant conversion: converts protein input (evidence: `bescreen/bedesigner.py`)
- Variant guides → Sequence and annotation utilities: uses utilities (evidence: `bescreen/bedesigner.py`)
- Gene saturation → Sequence and annotation utilities: uses utilities (evidence: `bescreen/besaturate.py`)
- Region guides → Sequence and annotation utilities: uses utilities (evidence: `bescreen/beregion.py`)
- Variant guides → VEP annotation: requests annotations (evidence: `bescreen/bedesigner.py`)
- Gene saturation → VEP annotation: requests annotations (evidence: `bescreen/besaturate.py`)
- Region guides → VEP annotation: requests annotations (evidence: `bescreen/beregion.py`)
- VEP annotation → Ensembl VEP: runs offline (evidence: `bescreen/get_vep.py`)
- Variant guides → Guide BLAST matching: checks guide matches (evidence: `bescreen/bedesigner.py`)
- Gene saturation → Guide BLAST matching: checks guide matches (evidence: `bescreen/besaturate.py`)
- Region guides → Guide BLAST matching: checks guide matches (evidence: `bescreen/beregion.py`)
- Guide BLAST matching → NCBI BLAST tools: runs search (evidence: `bescreen/blast_guides.py`)
- Variant guides → Reference genome and annotations: reads genome
- Gene saturation → Reference genome and annotations: reads genome
- Region guides → Reference genome and annotations: reads genome
- Variant guides → Guide tables and BAM: writes guides and BAM (evidence: `bescreen/bedesigner.py`)
- Gene saturation → Guide tables and BAM: writes guides and BAM (evidence: `bescreen/besaturate.py`)
- Region guides → Guide tables and BAM: writes guides and BAM (evidence: `bescreen/beregion.py`)
