# m3metabolomics/metabolink architecture

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

- Interactive diagram: https://gitdiagram.com/m3metabolomics/metabolink
- Repository: https://github.com/m3metabolomics/metabolink

## Overview

##### Project type and purpose
- MetaboLink is a full-stack R/Shiny web application for processing and analyzing large-scale untargeted metabolomics data.
- It provides a GUI (ui.R + www folder) backed by server logic (server.R + global.R + modular scripts in R/) and is packaged in a Docker container.

##### File structure
Top-level:
- Dockerfile → environment and deployment
- README.md, LICENSE.md → docs
- csvfiles/ → lookup tables (adducts.csv)
- example_files/ → sample input data
- server.R, ui.R, global.R, functions.R, test.R → Shiny app entry points and common functions
- R/ → discrete processing modules (blank_filtration.R, normalization.R, pca.R, statistical_analysis.R, export.R, etc.)
- www/ → frontend assets (CallShiny.js)

##### README
- Describes deployment via Docker (port 3838), external Bioconductor and CRAN dependencies.
- Points to a Wiki for user documentation.
- Emphasizes that users upload CSVs and obtain processed results & visualizations.

##### Main components & their interactions
a. Presentation Layer
– User’s browser ←→ Shiny UI (ui.R + www/CallShiny.js + intro_text.html)
b. Application/Control Layer
– server.R & global.R receive inputs from UI, orchestrate workflows
– functions.R holds helper functions
c. Processing Modules (Model Layer)
– R/*.R each implement a step in the pipeline:
- blank_filtration.R
- missing_value_filtration.R
- imputation.R
- drift_correction.R
- normalization.R
- pca.R
- statistical_analysis.R
- export.R
- merge.R, data_utils.R, upload_utils.R, internal_standards.R
d. Data Sources
– csvfiles/adducts.csv (reference)
– User-provided CSVs (example_files/)
e. External Dependencies & Deployment
– R packages installed via BiocManager/CRAN
– Docker container wrapping Shiny Server (exposes 3838)

##### Relationships & data flow
1. User uploads CSV → upload_utils.R
2. Data merges and reference lookup via merge.R + data_utils.R
3. Filtration steps (blank, missing-value)
4. Imputation → drift correction → normalization
5. Dimensionality reduction (PCA) → statistical analysis
6. Results formatted & exported via export.R
7. UI renders plots (plotly/ggplot2) and tables

##### Architectural patterns & design principles
- MVC‐esque separation: ui.R (View), server.R (Controller), R modules (Model)
- Functional decomposition: each step in distinct R scripts
- Containerization: reproducible environment with Docker
- Reactive programming: Shiny’s reactive graph connects UI inputs to module outputs

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User Browser"]:::user

    subgraph "Docker Container" 
        direction TB
        subgraph "Presentation Layer"
            direction TB
            UI["ui.R"]:::ui
            JS["CallShiny.js"]:::ui
            HTML["intro_text.html"]:::ui
        end
        subgraph "Application Layer"
            direction TB
            Server["server.R"]:::srv
            Global["global.R"]:::srv
            Funcs["functions.R"]:::srv
            Test["test.R"]:::srv
        end
        subgraph "Processing Modules"
            direction TB
            Upload["upload_utils.R"]:::mod
            Merge["merge.R"]:::mod
            DataUtil["data_utils.R"]:::mod
            Blank["blank_filtration.R"]:::mod
            Missing["missing_value_filtration.R"]:::mod
            Impute["imputation.R"]:::mod
            Drift["drift_correction.R"]:::mod
            Internal["internal_standards.R"]:::mod
            Norm["normalization.R"]:::mod
            PCA["pca.R"]:::mod
            Stat["statistical_analysis.R"]:::mod
            Export["export.R"]:::mod
            PlotFunc["plotfunctions.R"]:::mod
        end
        subgraph "Data Sources Layer"
            direction TB
            CSV(("adducts.csv")):::data
            EXFILES(("example_files/")):::data
        end
        subgraph "Environment & Docs"
            direction TB
            Dockerfile["Dockerfile"]:::doc
            Readme["README.md"]:::doc
            License["LICENSE.md"]:::doc
            Env["R Packages via BiocManager/CRAN\nPort 3838"]:::doc
        end
    end

    %% Data & Control Flow
    User --> UI
    UI --> Server
    Server --> Upload
    Upload --> Merge
    Merge --> DataUtil
    DataUtil --> Blank
    Blank --> Missing
    Missing --> Impute
    Impute --> Drift
    Drift --> Norm
    Norm --> PCA
    PCA --> Stat
    Stat --> Export
    Export --> Server
    Server --> UI
    UI --> User

    CSV --> Merge
    EXFILES --> Upload

    %% Click Events
    click UI "https://github.com/m3metabolomics/metabolink/blob/main/ui.R"
    click JS "https://github.com/m3metabolomics/metabolink/blob/main/www/CallShiny.js"
    click HTML "https://github.com/m3metabolomics/metabolink/blob/main/intro_text.html"
    click Server "https://github.com/m3metabolomics/metabolink/blob/main/server.R"
    click Global "https://github.com/m3metabolomics/metabolink/blob/main/global.R"
    click Funcs "https://github.com/m3metabolomics/metabolink/blob/main/functions.R"
    click Test "https://github.com/m3metabolomics/metabolink/blob/main/test.R"
    click Upload "https://github.com/m3metabolomics/metabolink/blob/main/R/upload_utils.R"
    click Merge "https://github.com/m3metabolomics/metabolink/blob/main/R/merge.R"
    click DataUtil "https://github.com/m3metabolomics/metabolink/blob/main/R/data_utils.R"
    click Blank "https://github.com/m3metabolomics/metabolink/blob/main/R/blank_filtration.R"
    click Missing "https://github.com/m3metabolomics/metabolink/blob/main/R/missing_value_filtration.R"
    click Impute "https://github.com/m3metabolomics/metabolink/blob/main/R/imputation.R"
    click Drift "https://github.com/m3metabolomics/metabolink/blob/main/R/drift_correction.R"
    click Internal "https://github.com/m3metabolomics/metabolink/blob/main/R/internal_standards.R"
    click Norm "https://github.com/m3metabolomics/metabolink/blob/main/R/normalization.R"
    click PCA "https://github.com/m3metabolomics/metabolink/blob/main/R/pca.R"
    click Stat "https://github.com/m3metabolomics/metabolink/blob/main/R/statistical_analysis.R"
    click Export "https://github.com/m3metabolomics/metabolink/blob/main/R/export.R"
    click PlotFunc "https://github.com/m3metabolomics/metabolink/blob/main/R/plotfunctions.R"
    click CSV "https://github.com/m3metabolomics/metabolink/blob/main/csvfiles/adducts.csv"
    click EXFILES "https://github.com/m3metabolomics/metabolink/tree/main/example_files/"
    click Dockerfile "https://github.com/m3metabolomics/metabolink/tree/main/Dockerfile"
    click Readme "https://github.com/m3metabolomics/metabolink/blob/main/README.md"
    click License "https://github.com/m3metabolomics/metabolink/blob/main/LICENSE.md"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000000
    classDef srv fill:#90EE90,stroke:#000000
    classDef mod fill:#FFA500,stroke:#000000
    classDef data fill:#D3D3D3,stroke:#000000
    classDef docker stroke:#9370DB,stroke-width:2px
    classDef doc fill:#F0E68C,stroke:#000000
    classDef user fill:#87CEEB,stroke:#000000
```
