# andreaswt/variant-analysis-evo2 architecture

> Architecture diagram of the GitHub repository andreaswt/variant-analysis-evo2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andreaswt/variant-analysis-evo2
- Repository: https://github.com/andreaswt/variant-analysis-evo2

## Overview

##### Project type and purpose
- This is a full-stack variant effect prediction web application.
- Purpose: allow users to browse reference genomes, select or search genes, submit single nucleotide variants, and get pathogenicity predictions from the Evo2 large language model, as well as compare with ClinVar data.

##### File structure
- Top-level directories:
- evo2-backend: contains the Python FastAPI service, the Evo2 model code (packaged under evo2), notebooks, tests, and deployment scripts.
- evo2-frontend: a Next.js (React + TypeScript) web interface following the T3 Stack (Tailwind, Shadcn UI).
- Backend patterns:
- A main.py entrypoint for Modal deployment.
- A Python package “evo2” with configs, model loading, scoring logic, and utility modules.
- External data-fetching via UCSC and NCBI ClinVar (no local database).
- Frontend patterns:
- App router under src/app, UI components under src/components, API client utilities under src/utils/genome-api.ts.
- Environment variables (.env.example) for API endpoints.
- Standard Next.js configuration (next.config.js, tsconfig.json).

##### README for additional insights
- Backend is deployed serverless on GPUs (H100) via Modal.
- The FastAPI endpoint exposes variant scoring.
- Frontend uses Next.js + Tailwind + Shadcn UI to build a responsive interface for genome assembly selector, chromosome browser, gene viewer, variant input, prediction comparison.
- External APIs: UCSC Genome Browser for sequences, NCBI E-utilities or ClinVar for known variant data.

a. Main components to represent:
- User’s Browser (React UI)
- Next.js Frontend Layer
- HTTP API Layer (FastAPI backend)
- GPU Inference Service (Modal-managed H100 instances)
- Evo2 Model Component (model weights, configs, scoring module)
- External Data Sources (UCSC API, NCBI ClinVar/E-utilities)
b. Relationships and interactions:
- Browser ↔ Frontend: UI interactions, state updates.
- Frontend → FastAPI: REST calls for variant analysis and data fetch.
- FastAPI → Modal GPU Service: dispatch inference jobs.
- FastAPI ↔ Evo2 Model Code: load model, run scoring.
- FastAPI → External APIs: fetch reference sequences, known variants.
- FastAPI → Frontend: return JSON containing prediction results and ClinVar comparisons.
c. Architectural patterns and design principles:
- Clear separation of concerns: presentation (frontend), business logic & ML inference (backend), compute resources (GPU service), and data sources.
- Serverless GPU inference via Modal to decouple compute scaling from API logic.
- Config-driven model instantiation (YAML config files under evo2/configs).
d. Technologies/frameworks to call out:
- Frontend: Next.js, React, TypeScript, Tailwind CSS, Shadcn UI.
- Backend: Python 3.10, FastAPI, Modal, Evo2 Python package.
- Data sources: UCSC Genome Browser REST API, NCBI ClinVar/E-utilities.
- Deployment: Modal for serverless GPU, Vercel or similar for Next.js (optional).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface
    Browser["User's Browser"]:::ui

    subgraph "Next.js Frontend"
        direction TB
        AppRouter["src/app"]:::frontend
        UIComponents["src/components"]:::frontend
        APIClient["src/utils/genome-api.ts"]:::frontend
        EnvVars[".env.example"]:::frontend
        NextConfig["next.config.js"]:::frontend
        TSConfig["tsconfig.json"]:::frontend
    end

    subgraph "FastAPI Backend"
        direction TB
        API["main.py (FastAPI Endpoint)"]:::backend
        Requirements["requirements.txt"]:::backend
    end

    subgraph "Serverless GPU Inference Service"
        direction TB
        GPUService["Modal GPU Service"]:::compute
    end

    subgraph "Evo2 Model Package"
        direction TB
        Models["models.py & version.py"]:::model
        Scoring["scoring.py"]:::model
        Utils["utils.py"]:::model
        Configs["configs/*.yml"]:::model
    end

    subgraph "External Data Sources"
        direction TB
        ExternalUCSC["UCSC Genome API"]:::external
        ExternalClinvar["NCBI ClinVar API"]:::external
    end

    %% Flows
    Browser -->|interacts| AppRouter
    AppRouter --> UIComponents
    AppRouter --> APIClient
    APIClient -->|variant request| API
    API -->|fetch sequence| ExternalUCSC
    API -->|fetch known variants| ExternalClinvar
    API -->|dispatch inference| GPUService
    GPUService -->|runs inference| Scoring
    GPUService -->|loads model| Models
    Scoring --> Utils
    Models --> Configs
    API -->|invoke scoring| Scoring
    API -->|invoke models| Models
    API -->|use utilities| Utils
    API -->|returns results| AppRouter
    UIComponents -->|render UI| Browser

    %% Click Events
    click AppRouter "https://github.com/andreaswt/variant-analysis-evo2/tree/main/evo2-frontend/src/app"
    click UIComponents "https://github.com/andreaswt/variant-analysis-evo2/tree/main/evo2-frontend/src/components"
    click APIClient "https://github.com/andreaswt/variant-analysis-evo2/blob/main/evo2-frontend/src/utils/genome-api.ts"
    click EnvVars "https://github.com/andreaswt/variant-analysis-evo2/blob/main/evo2-frontend/.env.example"
    click NextConfig "https://github.com/andreaswt/variant-analysis-evo2/blob/main/evo2-frontend/next.config.js"
    click TSConfig "https://github.com/andreaswt/variant-analysis-evo2/blob/main/evo2-frontend/tsconfig.json"
    click API "https://github.com/andreaswt/variant-analysis-evo2/blob/main/evo2-backend/main.py"
    click Requirements "https://github.com/andreaswt/variant-analysis-evo2/blob/main/evo2-backend/requirements.txt"
    click Models "https://github.com/andreaswt/variant-analysis-evo2/blob/main/evo2-backend/evo2/evo2/models.py"
    click Scoring "https://github.com/andreaswt/variant-analysis-evo2/blob/main/evo2-backend/evo2/evo2/scoring.py"
    click Utils "https://github.com/andreaswt/variant-analysis-evo2/blob/main/evo2-backend/evo2/evo2/utils.py"
    click Configs "https://github.com/andreaswt/variant-analysis-evo2/tree/main/evo2-backend/evo2/evo2/configs"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef frontend fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32,stroke-width:1px;
    classDef backend fill:#FFF3E0,stroke:#EF6C00,color:#EF6C00,stroke-width:1px;
    classDef compute fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A,stroke-width:1px;
    classDef model fill:#E0F2F1,stroke:#00796B,color:#00796B,stroke-width:1px;
    classDef external fill:#ECEFF1,stroke:#455A64,color:#455A64,stroke-width:1px;
```
