# collaborativebioinformatics/genevar2 architecture

> Architecture diagram of the GitHub repository collaborativebioinformatics/genevar2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/collaborativebioinformatics/genevar2
- Repository: https://github.com/collaborativebioinformatics/genevar2

## Overview

##### Project type and purpose
- GeneVar2 is a hybrid bioinformatics application combining:
- An R/Shiny web application for interactive gene-centric SV (structural variant) exploration
- A command-line annotation pipeline (R scripts and Python utilities) for bulk VCF SV annotation

##### File structure
- Top-level directories and files
- R/               → core R annotation modules (annotate_vcf.R, annotate_genes.R, etc.)
- genevarapp/      → Shiny application (ui.R, server.R, run-app.R), Python support (VCFanalyse.py, retrieve.py), prebuilt data, test data
- scripts/genevar/ → Snakefile workflow and helper R/Python scripts for batch pipeline
- testdata/        → example VCF and annotation_data.RData for local testing
- results/         → sample output files (TSV, CSV, VCF)
- Configuration and metadata
- LICENSE, .gitattributes, README.md

##### README for additional insights
- The README describes two user flows: “enter individual gene” and “upload a VCF”
- It references external resources (gencode, gnomAD-SV, ClinVar) and a DNAnexus deployment
- It lists R/Bioconductor dependencies, pipeline usage examples, enrichment analysis steps

##### Main components
a. User interfaces
1. Web UI (Shiny front end: genevarapp/ui.R)
2. CLI scripts (Rscript entry points in R/, scripts/genevar/Snakefile)
b. Application servers/modules
1. Shiny server logic (genevarapp/server.R)
2. Annotation modules (R scripts in R/: annotate_vcf.R, annotate_frequency.R, annotate_clinical_score.R, GeneAnnotationFromCSV.R)
3. Python utilities (genevarapp/retrieve.py for data fetching, VCFanalyse.py for parsing and initial VCF handling)
4. Batch workflow engine (Snakemake in scripts/genevar/Snakefile orchestrating R/Python scripts)
c. Data storage and resources
1. Static annotation data files (annotation_data.RData, gencode.tsv.gz, dbvar38.ann.tsv.gz, pli.gene.tsv.gz)
2. Test data (testdata/) and results (results/)
3. External databases (ClinVar, gnomAD-SV, OMIM, GTEx) accessed via APIs or predownloaded files
d. Outputs
1. Annotated VCF and CSV (test.output.vcf, test.output.csv)
2. Enrichment tables (TSV) and plots (PNG)
3. Dynamic tables and plots in Shiny UI
4. Downloadable files for user

##### Relationships and interactions
- Web flow:
User → Shiny UI → server.R
├─ if “gene query” → Python retrieve.py fetches SV + regulatory data → R functions annotate_genes, annotate_frequency, annotate_clinical_score → dynamic table + plots
└─ if “VCF upload” → server saves file → R annotate_vcf.R (calls helper scripts) → outputs CSV, VCF → R GeneAnnotationFromCSV.R for enrichment → tables + plots
- CLI flow (batch):
User → Snakefile → runs prepare_gencode.R, prepare_gnomadsv_freq.R → annotate_freq.R → vcf_plot.py → final VCF/CSV → GeneAnnotationFromCSV.R
- All modules read from/write to the static data folder under genevarapp/ or scripts/genevar/

##### Architectural patterns and design principles
- Modular scripting: each annotation task is a separate R/Python script, assembled by a master script or by Snakemake
- Two‐tier deployment: lightweight RShiny front end backed by statistical annotation logic
- Reproducible pipeline: Snakefile ensures consistent ordering of data preparation and annotation steps
- Separation of concerns: UI vs. compute vs. data retrieval

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Web App Lane
    subgraph "Web Application" 
        direction TB
        UserBrowser["User Browser"]:::frontend
        ShinyUI["Shiny UI"]:::frontend
        ShinyServer["Shiny Server Logic"]:::compute
        PyRetrieve["Python Retrieval Module"]:::compute
        RAnnotGenes["R Annotate Genes"]:::compute
        RAnnotFreq["R Annotate Frequency"]:::compute
        RAnnotClin["R Annotate Clinical Score"]:::compute
        RAnnotVCF["R Annotate VCF"]:::compute
        RAnnotFromCSV["R GeneAnnotationFromCSV"]:::compute
        ResultsStore["Results Store"]:::datastore
        StaticData["Static Annotation Data"]:::datastore
        ExternalDB["External DB APIs"]:::external
        TestData["Test Data"]:::datastore
    end

    %% Batch Pipeline Lane
    subgraph "Batch Pipeline (CLI)" 
        direction TB
        CLIUser["User CLI"]:::frontend
        Snakemake["Snakemake Pipeline"]:::compute
        PrepGencode["prepare_gencode.R"]:::compute
        PrepGnomad["prepare_gnomadsv_freq.R"]:::compute
        AnnotFreqBatch["annotate_freq.R"]:::compute
        VcfPlot["vcf_plot.py"]:::compute
        RAnnotFromCSV2["R GeneAnnotationFromCSV"]:::compute
        ResultsStore2["Results Store"]:::datastore
    end

    %% Web Flow
    UserBrowser -->|"visit UI"| ShinyUI
    ShinyUI -->|"user input"| ShinyServer
    ShinyServer -->|"gene ID"| PyRetrieve
    PyRetrieve -->|"SV + regulatory data"| RAnnotGenes
    RAnnotGenes --> RAnnotFreq
    RAnnotFreq --> RAnnotClin
    RAnnotClin --> ResultsStore
    ResultsStore -->|"dynamic tables/plots"| ShinyUI

    ShinyServer -->|"VCF file"| RAnnotVCF
    RAnnotVCF --> RAnnotFromCSV
    RAnnotFromCSV --> ResultsStore
    ResultsStore -->|"downloadable files"| ShinyUI

    StaticData --> RAnnotGenes
    StaticData --> RAnnotFreq
    StaticData --> RAnnotClin
    StaticData --> RAnnotVCF
    ExternalDB --> PyRetrieve
    TestData --> ShinyServer

    %% Batch Flow
    CLIUser -->|"run pipeline"| Snakemake
    Snakemake --> PrepGencode
    Snakemake --> PrepGnomad
    Snakemake --> AnnotFreqBatch
    AnnotFreqBatch --> VcfPlot
    VcfPlot --> RAnnotFromCSV2
    RAnnotFromCSV2 --> ResultsStore2

    StaticData --> PrepGencode
    StaticData --> PrepGnomad
    StaticData --> AnnotFreqBatch
    ExternalDB --> PrepGencode
    ExternalDB --> PrepGnomad

    %% Click Events Web App
    click ShinyUI "https://github.com/collaborativebioinformatics/genevar2/blob/main/genevarapp/ui.R"
    click ShinyServer "https://github.com/collaborativebioinformatics/genevar2/blob/main/genevarapp/server.R"
    click PyRetrieve "https://github.com/collaborativebioinformatics/genevar2/blob/main/genevarapp/retrieve.py"
    click RAnnotGenes "https://github.com/collaborativebioinformatics/genevar2/blob/main/R/annotate_genes.R"
    click RAnnotFreq "https://github.com/collaborativebioinformatics/genevar2/blob/main/R/annotate_frequency.R"
    click RAnnotClin "https://github.com/collaborativebioinformatics/genevar2/blob/main/R/annotate_clinical_score.R"
    click RAnnotVCF "https://github.com/collaborativebioinformatics/genevar2/blob/main/R/annotate_vcf.R"
    click RAnnotFromCSV "https://github.com/collaborativebioinformatics/genevar2/blob/main/R/GeneAnnotationFromCSV.R"
    click StaticData "https://github.com/collaborativebioinformatics/genevar2/blob/main/genevarapp/annotation_data.RData"
    click TestData "https://github.com/collaborativebioinformatics/genevar2/blob/main/genevarapp/testdata/test.input.vcf"

    %% Click Events Batch Pipeline
    click Snakemake "https://github.com/collaborativebioinformatics/genevar2/tree/main/scripts/genevar/Snakefile"
    click PrepGencode "https://github.com/collaborativebioinformatics/genevar2/blob/main/scripts/genevar/prepare_gencode.R"
    click PrepGnomad "https://github.com/collaborativebioinformatics/genevar2/blob/main/scripts/genevar/prepare_gnomadsv_freq.R"
    click AnnotFreqBatch "https://github.com/collaborativebioinformatics/genevar2/blob/main/scripts/genevar/annotate_freq.R"
    click VcfPlot "https://github.com/collaborativebioinformatics/genevar2/blob/main/scripts/genevar/vcf_plot.py"

    %% Styles
    classDef frontend fill:#D0E6F8,stroke:#0366D6,color:#0366D6;
    classDef compute fill:#E6F5D0,stroke:#3C763D,color:#3C763D;
    classDef datastore fill:#F8E6D0,stroke:#8A6D3B,color:#8A6D3B,shape:cylinder;
    classDef external fill:#FDEBD0,stroke:#E67E22,color:#E67E22,shape:cloud;
```
