# opencb/iva architecture

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

- Interactive diagram: https://gitdiagram.com/opencb/iva
- Repository: https://github.com/opencb/iva

## Overview

##### Project Type and Purpose
- IVA is a single‐page web application (SPA) written in JavaScript that serves as the front‐end for the OpenCGA genomic‐data platform.
- It provides real‐time interactive features for variant browsing, case interpretation, sample/family/cohort browsing, jobs monitoring, and clinical analysis.

##### File Structure
- src/ – all front‐end code (HTML templates, CSS, JS modules, configuration).
- lib/jsorolla/ – embedded JSorolla library (shared OpenCB UI components).
- cypress/ and test/e2e/ – end‐to‐end test suites and test runners.
- docker/iva-app/ – Dockerfile and entrypoint for packaging the UI into a container.
- CI configs (Jenkinsfile, .github/workflows/*.yml) – continuous integration and release pipelines.
- Webpack/Rollup config files – build and bundling tools to generate production assets.

##### Readme Highlights
- The UI communicates via HTTP with the OpenCGA REST API (hosted elsewhere).
- Build & run: npm scripts for dev server (`npm run serve`), build (`npm run build`), and E2E tests (Cypress).
- Deployment: containerized through Docker, recommended to serve static assets behind a web server.

##### Main Components and Their Interactions
a. User’s Web Browser (UI):
– Loads the SPA (HTML, JS bundles, CSS) from a web / CDN server.
– Renders pages (variant browser, case interpreter, cohort browser, etc.).
– Uses JSorolla modules plus IVA business‐logic modules for UI widgets and charts.
b. Static Web Server (Dockerized IVA App):
– Serves built assets (index.html, .js, .css, images).
– Could be Nginx or Node.js static‐file server inside the IVA Docker container.
c. OpenCGA REST API (External Service):
– Provides genomic‐data endpoints.
– Accepts authentication tokens, returns JSON data.
d. Build & Test Pipeline (CI/CD):
– GitHub Actions / Jenkins runs:
- `npm install` + JSorolla submodule preparation
- `npm run build` (Webpack/Rollup)
- `npm run e2e` (Cypress)
- Docker image build and publish
e. End‐to‐End Test Runner:
– Cypress (interactive and headless)
– Nightwatch config for legacy tests

##### Architectural Patterns & Design Principles
- SPA Architecture: clear separation of concerns—routing, data services, UI components.
- Modular JavaScript: each feature under src/ is a self‐contained module.
- Containerization: Docker ensures environment consistency.
- CI/CD: automated builds, tests, and releases.
- External API Integration: all data interactions go through REST calls to OpenCGA.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Subgraphs
    subgraph "Development" 
        UI["User Web Browser\n(IVA SPA)"]:::ui
        SPA["IVA SPA\n(src/)"]:::app
        Entry["UI Entry Point\n(src/index.html)"]:::app
        AppLogic["Main Application Logic\n(src/iva-app.js)"]:::app
        ConfDir["Configuration Modules\n(src/conf/)"]:::config
        SharedLib["Shared UI Library\n(lib/jsorolla/)"]:::lib
        StylesAssets["Styles & Assets\n(src/styles/, src/img/)"]:::assets
    end

    subgraph "Production"
        Server["Web Server\n(Dockerized IVA App)"]:::server
        ExtAPI["OpenCGA REST API\n(External)"]:::api
    end

    subgraph "CI/CD Pipeline"
        CI["CI/CD Services\n(Jenkins/GitHub Actions)"]:::ci
        Tests["E2E Test Runner\n(Cypress/Nightwatch)"]:::test
        DockerReg["Docker Registry"]:::registry
    end

    %% Connections
    UI -->|loads SPA| Entry
    Entry -->|initializes| SPA
    SPA -->|imports| SharedLib
    SPA -->|uses| AppLogic
    SPA -->|reads configs| ConfDir
    SPA -->|applies styles| StylesAssets
    UI -->|fetch assets| Server
    Server -->|serves static files| UI
    SPA -->|REST calls| ExtAPI
    CI -->|npm install & build| SPA
    CI -->|npm run e2e| Tests
    CI -->|docker build & push| DockerReg
    DockerReg -->|deploy image| Server

    %% Click Events for component mapping
    click SPA "https://github.com/opencb/iva/tree/develop/src/"
    click Entry "https://github.com/opencb/iva/blob/develop/src/index.html"
    click AppLogic "https://github.com/opencb/iva/blob/develop/src/iva-app.js"
    click ConfDir "https://github.com/opencb/iva/tree/develop/src/conf/"
    click SharedLib "https://github.com/opencb/iva/tree/develop/lib/jsorolla/"
    click StylesAssets "https://github.com/opencb/iva/blob/develop/src/styles/global.css"
    click StylesAssets "https://github.com/opencb/iva/blob/develop/src/styles/magic-check.css"
    click StylesAssets "https://github.com/opencb/iva/blob/develop/src/styles/toggle-switch.css"
    click StylesAssets "https://github.com/opencb/iva/tree/develop/src/img/"
    click Tests "https://github.com/opencb/iva/tree/develop/cypress/integration/"
    click Tests "https://github.com/opencb/iva/tree/develop/cypress/plugins/"
    click Tests "https://github.com/opencb/iva/tree/develop/test/e2e/"
    click CI "https://github.com/opencb/iva/tree/develop/Jenkinsfile"
    click CI "https://github.com/opencb/iva/blob/develop/.github/workflows/docker.yml"
    click CI "https://github.com/opencb/iva/blob/develop/.github/workflows/release.yml"
    click CI "https://github.com/opencb/iva/blob/develop/nightwatch.conf.js"
    click CI "https://github.com/opencb/iva/blob/develop/webpack.config.js"
    click CI "https://github.com/opencb/iva/blob/develop/src/rollup.html"
    click CI "https://github.com/opencb/iva/blob/develop/live-server.js"
    click CI "https://github.com/opencb/iva/tree/develop/docker/iva-app/Dockerfile"
    click CI "https://github.com/opencb/iva/blob/develop/docker/iva-app/entrypoint.sh"

    %% Styles
    classDef ui fill:#FFD5E5,stroke:#FF0077,color:#000;
    classDef app fill:#D0E8FF,stroke:#0066CC,color:#000;
    classDef config fill:#FFF4C1,stroke:#FFCC00,color:#000;
    classDef lib fill:#E8F0D7,stroke:#7FB800,color:#000;
    classDef assets fill:#F0E6FF,stroke:#9933CC,color:#000;
    classDef server fill:#FFE6CC,stroke:#FF6600,color:#000;
    classDef api fill:#CCE7FF,stroke:#3399FF,color:#000;
    classDef ci fill:#E5E5E5,stroke:#888888,color:#000;
    classDef test fill:#FDEBD0,stroke:#E67E22,color:#000;
    classDef registry fill:#D5F5E3,stroke:#27AE60,color:#000;
```
