# igvteam/igv architecture

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

- Interactive diagram: https://gitdiagram.com/igvteam/igv
- Repository: https://github.com/igvteam/igv

## Overview

##### Project Type and Purpose
- IGV is a heavy-weight, desktop Java application for interactive genome visualization on Mac, Windows, and Linux.
- It also includes a command-line toolkit (“igvtools”) for batch processing genomic data and conversion tools, plus scripts for packaging and launching.

##### File Structure Analysis
- Top‐level:
- src/main/java – core Java packages for UI, data models, parsers, renderers, AWS support, session management, tools, etc.
- scripts/ – OS‐specific launchers (bash, bat, Mac .command), installer descriptors.
- lib_build/ – packaging dependencies for JRE bundling.
- examples/ – sample genome and OAuth config for testing.
- docs/ – user/developer documentation and web examples.
- build.gradle, gradlew – Gradle build scripts.
- src/test/java – automated unit and integration tests.

##### README Insights
- Desktop app built with Java 21; Gradle packaging produces an IGV distribution with embedded JREs, launcher scripts, and igvtools.
- Supports AWS S3 data access via OAuth/credentials.
- No central database; all data fed from local files or remote HTTP/S endpoints (UCSC, GA4GH, Htsget).

1. User Interface Layer
– Swing/AWT frames and panels (org.broad.igv.ui)
– Command Bar, Menus, Dialogs (track config, genome selection)
2. Core Engine
– Event Bus (IGVEventBus)
– Session Manager (load/save .xml sessions)
– Preferences Manager
– Track Manager (load/unload tracks)
3. Data Access & Parsing
– FileFormat Parsers (SAM, BAM, VCF, BigWig, TwoBit, GFF, BEDPE, etc.)
– DataSource Abstractions (local FS, HTTP, S3)
– AWS Client Module (org.broad.igv.aws)
4. Rendering Subsystem
– Renderers (feature tracks, alignments, heatmap, sashimi)
– Charting (scatter, bar, line)
– Graphics Utilities
5. Command‐Line Tools
– igvtools and converters (under org.broad.igv.tools)
6. Packaging & Launch Scripts
– Gradle distribution (build/IGV-dist)
– OS‐specific launchers (scripts/igv*.sh, .bat, Mac .command)
- UI → Core Engine (user actions dispatch events)
- Core Engine → Data Access (requests to load data)
- Data Access → Parsers → Data Models → Core Engine
- Core Engine → Rendering Subsystem → UI Canvas
- Core Engine ↔ Session Manager (persist state)
- Command‐Line Tools → Data Access → Parsers → Output Files
- AWS Client ↔ Amazon S3 (optional external data source)
c. Architectural Patterns & Principles
- MVC‐style separation: UI panels (View) bind to data models via event bus (Controller) leveraging data source abstractions (Model).
- Plugin/extension points: CLI plugins and OAuth providers loaded via resource descriptors.
- Single application monolith for desktop, with decoupled modules via Java packages and events.
d. Key Technologies
- Java 21, Swing/AWT for UI
- Gradle for build and packaging
- AWS SDK v1 for S3 integration
- JArgs for command‐line parsing
- ProGuard for packaging/minification

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "User Interface Layer"
        direction TB
        UI["Swing/AWT Frames & Panels"]:::ui
        UIAction["Menus & Command Bar"]:::ui
    end

    %% Core Engine
    subgraph "Core Engine"
        direction TB
        EB["IGVEventBus"]:::core
        SM["Session Manager"]:::core
        PM["Preferences Manager"]:::core
        TM["Track Loader/Manager"]:::core
    end

    %% Data Access & Parsing
    subgraph "Data Access & Parsing"
        direction TB
        DS["DataSource Abstractions"]:::data
        FP["File Format Parsers"]:::data
        HR["Htsget Reader"]:::data
        AWS["AWS S3 Integration"]:::data
    end

    %% Rendering Subsystem
    subgraph "Rendering Subsystem"
        direction TB
        REN["Track & Feature Renderer"]:::render
        CH["Charting Components"]:::render
    end

    %% Command-Line Tools
    subgraph "Command-Line Toolkit"
        direction TB
        CLI["IgvTools CLI"]:::cli
        CONV["CLI Converters & Plugins"]:::cli
    end

    %% Packaging & Launch
    subgraph "Packaging & Launch Scripts"
        direction TB
        PKG["Gradle Build & Packaging"]:::pkg
        JRE["JRE Bundling & Obfuscation"]:::pkg
        LS["OS-Specific Launch Scripts"]:::pkg
    end

    %% External Services
    S3["Amazon S3"]:::external
    HTTP["HTTP/S Endpoints"]:::external

    %% Data Flow & Dependencies
    UI -->|dispatch events| EB
    UIAction -->|dispatch events| EB
    EB -->|load/save sessions| SM
    EB -->|get/set prefs| PM
    EB -->|manage tracks| TM
    TM -->|request data| DS
    DS -->|read local/remote| FP
    DS -->|htsget protocol| HR
    DS -->|AWS requests| AWS
    FP -->|parsed models| EB
    EB -->|render requests| REN
    REN -->|draw on| UI

    CLI -->|batch load| DS
    CONV -->|convert formats| DS
    CLI -->|invoke converters| CONV

    AWS <-->|S3 API| S3
    DS <-->|fetch| HTTP

    PKG -->|build distribution| JRE
    PKG -->|include scripts| LS

    %% Click Events
    click UI "https://github.com/igvteam/igv/tree/main/src/main/java/org/broad/igv/ui"
    click UIAction "https://github.com/igvteam/igv/tree/main/src/main/java/org/broad/igv/ui/action"
    click EB "https://github.com/igvteam/igv/blob/main/src/main/java/org/broad/igv/event/IGVEventBus.java"
    click SM "https://github.com/igvteam/igv/tree/main/src/main/java/org/broad/igv/session"
    click PM "https://github.com/igvteam/igv/blob/main/src/main/java/org/broad/igv/prefs/PreferencesManager.java"
    click TM "https://github.com/igvteam/igv/blob/main/src/main/java/org/broad/igv/track/TrackLoader.java"
    click DS "https://github.com/igvteam/igv/tree/main/src/main/java/org/broad/igv/data"
    click FP "https://github.com/igvteam/igv/tree/main/src/main/java/org/broad/igv/feature"
    click AWS "https://github.com/igvteam/igv/tree/main/src/main/java/org/broad/igv/aws"
    click HR "https://github.com/igvteam/igv/blob/main/src/main/java/org/broad/igv/htsget/HtsgetReader.java"
    click REN "https://github.com/igvteam/igv/tree/main/src/main/java/org/broad/igv/renderer"
    click CH "https://github.com/igvteam/igv/tree/main/src/main/java/org/broad/igv/charts"
    click CLI "https://github.com/igvteam/igv/blob/main/src/main/java/org/broad/igv/tools/IgvTools.java"
    click CONV "https://github.com/igvteam/igv/tree/main/src/main/java/org/broad/igv/tools/converters"
    click PKG "https://github.com/igvteam/igv/blob/main/build.gradle"
    click JRE "https://github.com/igvteam/igv/tree/main/lib_build/"
    click LS "https://github.com/igvteam/igv/blob/main/scripts/igv.sh"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef core fill:#DDFFDD,stroke:#28A745,stroke-width:1px
    classDef data fill:#FFE4B5,stroke:#FF8C00,stroke-width:1px
    classDef render fill:#F3E5FF,stroke:#6F42C1,stroke-width:1px
    classDef cli fill:#FFF5CC,stroke:#D69E2E,stroke-width:1px
    classDef pkg fill:#F0E6D2,stroke:#8A4600,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#636363,stroke-width:1px
```
