# nvelden/geneviewer architecture

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

- Interactive diagram: https://gitdiagram.com/nvelden/geneviewer
- Repository: https://github.com/nvelden/geneviewer

## Overview

##### Project type & purpose
- It’s an R library/package (not a standalone web app).
- Bundles documentation (man pages, vignettes), example HTML widgets, and a pkgdown website.

##### Topology of components
A. User Layer (rectangle, light green)
- R console / RStudio / Shiny app
- Calls geneviewer API (e.g. GC_chart, GC_labels)
B. Core R Engine (rectangle, light blue)
- R/ folder: data‐import, normalization, alignment wrappers, plotting functions
- data/ & inst/extdata/: sample datasets & user‐provided files
- tests/ and vignettes/: validation and examples
C. External Tools (rectangle, orange)
- BLAST (BlastP)
- MUMmer
- Invoked by R wrappers (system calls)
D. Interactive Front‑end (rectangle, purple)
- htmlwidgets bridge:
– inst/htmlwidgets/geneviewerwidget.js + geneviewer.yaml
– lib dependencies: D3, FileSaver, html2canvas, geneviewer JS and Themes
- Produces interactive SVG/Canvas plots embedded in HTML
E. Static Plotting (rectangle, blue)
- Pure R graphics output (e.g. grid, ggplot) for PDF/PNG
F. Documentation Site (rectangle, gray)
- pkgdown generates docs/ HTML from man/, vignettes/, README.md
- Includes reference and articles generated under docs/articles
G. CI/CD & Distribution (rectangle, yellow)
- GitHub Actions (R‑CMD‑check)
- CRAN/GitHub releases

##### Relationships & data flow
- User → Core R Engine: calls API functions
- Core R Engine → External Tools: system calls for alignment
- Core R Engine → Static Plotting: draws gene maps
- Core R Engine → Interactive Front‑end: invokes htmlwidgets to wrap JS libs
- Interactive Front‑end → Browser: renders interactive plots
- Core R Engine + pkgdown → Documentation Site
- CI/CD → builds & tests Core R Engine and publishes package to CRAN/GitHub

##### Architectural patterns & design principles
- Layered separation:
– Data ingestion & transformation (R/data.R, read_*.R)
– Analysis (alignment, normalization)
– Visualization (static vs. interactive)
- Extensibility hooks: custom themes, labels, tooltips
- Standard R package layout: DESCRIPTION, NAMESPACE, R/, man/, inst/, tests/, vignettes/
- Decoupling of R logic from JS visualization via htmlwidgets

##### Essential elements
- Annotations for key technologies (D3, htmlwidgets, pkgdown, GitHub Actions)
- Boundaries for “User space” vs. “Package internals” vs. “External dependencies”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        direction TB
        Shiny["Shiny Entrypoint"]:::user
        API["API Loader"]:::user
    end

    %% Core R Engine
    subgraph "Core R Engine"
        direction TB
        subgraph "Data Import & Transformation"
            direction TB
            DataR["data.R"]:::core
            ReadBed["read_bed.R"]:::core
            ReadFasta["read_fasta.R"]:::core
            ReadGenbank["read_genbank.R"]:::core
            ReadGff["read_gff.R"]:::core
        end
        subgraph "Analysis Wrappers"
            direction TB
            BlastWrap["cluster_blast.R"]:::core
            MummerWrap["mummer_alignment.R"]:::core
            GeneAlign["gene_alignment.R"]:::core
            Normalize["gene_normalization.R"]:::core
            Transcript["transcript.R"]:::core
        end
        subgraph "Plotting Utilities"
            direction TB
            Utils["utils.R"]:::core
            Viewer["geneviewer.R"]:::core
        end
        DataR -->|imports| ReadBed
        DataR --> ReadFasta
        DataR --> ReadGenbank
        DataR --> ReadGff
        BlastWrap -->|calls BLASTP| BLAST
        MummerWrap -->|calls MUMmer| MUMMER
    end

    %% External Tools
    subgraph "External Tools"
        direction TB
        BLAST["BlastP"]:::external
        MUMMER["MUMmer"]:::external
    end

    %% Static Plotting
    Static["Static Plotting\n(ggplot, grid)"]:::static

    %% Interactive Front-end
    subgraph "Interactive Front-end"
        direction TB
        Widget["htmlwidgets Bridge"]:::interactive
        subgraph "JS Dependencies"
            direction TB
            D3["D3-7.8.5"]:::interactive
            FileSaver["FileSaver-2.0.4"]:::interactive
            HTML2Canvas["html2canvas-1.4.1"]:::interactive
            GVJS["geneviewer-0.1.10"]:::interactive
            Styles["styles.css"]:::interactive
        end
    end

    Browser["Web Browser"]:::external

    %% Documentation Site
    subgraph "Documentation Site"
        direction TB
        Config["_pkgdown.yml"]:::docs
        Site["Generated Site"]:::docs
    end

    %% CI/CD & Distribution
    subgraph "CI/CD & Distribution"
        direction TB
        CI["GitHub Actions"]:::cicd
        Meta["DESCRIPTION, NAMESPACE,\nNEWS.md, LICENSE"]:::cicd
    end

    %% Sample & User Data
    DataBundled["Bundled Data (data/)"]:::core
    ExtData["External Data (inst/extdata/)"]:::core

    %% Tests & Vignettes
    Tests["tests/"]:::core
    Vignettes["vignettes/"]:::core

    %% Relationships
    Shiny -->|calls| API
    API -->|invokes| DataR
    API -->|invokes| BlastWrap
    API -->|invokes| MummerWrap
    API -->|invokes| Utils
    API -->|invokes| Viewer

    DataR --> DataBundled
    DataR --> ExtData

    Viewer --> Static
    Viewer --> Widget
    Widget --> D3
    Widget --> FileSaver
    Widget --> HTML2Canvas
    Widget --> GVJS
    Widget --> Styles
    Widget --> Browser

    BlastWrap --> BLAST
    MummerWrap --> MUMMER

    API --> Tests
    API --> Vignettes

    API --> Config
    Config --> Site
    Viewer --> Site

    CI --> API
    CI --> Tests
    CI --> Vignettes
    CI --> Site
    CI --> Meta

    %% Click Events
    click Shiny "https://github.com/nvelden/geneviewer/blob/main/R/geneviewer-shiny.R"
    click API "https://github.com/nvelden/geneviewer/blob/main/R/geneviewer.R"
    click DataR "https://github.com/nvelden/geneviewer/blob/main/R/data.R"
    click ReadBed "https://github.com/nvelden/geneviewer/blob/main/R/read_bed.R"
    click ReadFasta "https://github.com/nvelden/geneviewer/blob/main/R/read_fasta.R"
    click ReadGenbank "https://github.com/nvelden/geneviewer/blob/main/R/read_genbank.R"
    click ReadGff "https://github.com/nvelden/geneviewer/blob/main/R/read_gff.R"
    click BlastWrap "https://github.com/nvelden/geneviewer/blob/main/R/cluster_blast.R"
    click MummerWrap "https://github.com/nvelden/geneviewer/blob/main/R/mummer_alignment.R"
    click GeneAlign "https://github.com/nvelden/geneviewer/blob/main/R/gene_alignment.R"
    click Normalize "https://github.com/nvelden/geneviewer/blob/main/R/gene_normalization.R"
    click Transcript "https://github.com/nvelden/geneviewer/blob/main/R/transcript.R"
    click Utils "https://github.com/nvelden/geneviewer/blob/main/R/utils.R"
    click Viewer "https://github.com/nvelden/geneviewer/blob/main/R/geneviewer.R"
    click DataBundled "https://github.com/nvelden/geneviewer/tree/main/data/"
    click ExtData "https://github.com/nvelden/geneviewer/tree/main/inst/extdata/"
    click Widget "https://github.com/nvelden/geneviewer/blob/main/inst/htmlwidgets/geneviewerwidget.js"
    click Config "https://github.com/nvelden/geneviewer/blob/main/_pkgdown.yml"
    click CI "https://github.com/nvelden/geneviewer/blob/main/.github/workflows/R-CMD-check.yaml"

    %% Styles
    classDef user fill:#9f6,stroke:#333,stroke-width:1px
    classDef core fill:#6cf,stroke:#333,stroke-width:1px
    classDef external fill:#f96,stroke:#333,stroke-width:1px
    classDef interactive fill:#c9f,stroke:#333,stroke-width:1px
    classDef static fill:#6af,stroke:#333,stroke-width:1px
    classDef docs fill:#ccc,stroke:#333,stroke-width:1px
    classDef cicd fill:#fc9,stroke:#333,stroke-width:1px
```
