# fw1121/survivalml architecture

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

- Interactive diagram: https://gitdiagram.com/fw1121/survivalml
- Repository: https://github.com/fw1121/survivalml

## Overview

##### Project Type and Purpose
- SurvivalML is a Shiny web application built in R for “Efficient Discovery of Robust Prognostic Biomarkers and Signatures in Solid Tumors”. It is designed to facilitate multi-omics survival analysis for cancer research, including validation across multiple cohorts.
- The project leverages R’s Shiny framework for interactive web applications. It incorporates a modular design for both the UI and the server components, integrating complex analysis workflows, external data (spreadsheet and text files under “db”), and detailed documentation and help files.

##### File Structure
- Key directories include:
– Root files: LICENSE.txt, README.md, SurvivalML.Rproj, app.R (entry point), and init.config.R for configuration.
– db: Contains raw data files and auxiliary data/info (e.g., Excel files, text files) that serve as the database for analysis.
– doc: Contains user documentation, help materials (including FAQs, citation instructions, and policy files).
– lib: Contains common library scripts (global functions, package loaders, and utility scripts like shinyLink.R). There’s also a packaged dependency (KEGG.db tarball) and a script to list required R packages.
– server: Contains a set of modular R scripts (e.g., module_cm_candidate_agents.R, module_pm_functional_analysis.R, etc.) that encapsulate backend logic for various analysis workflows.
– ui: Contains modular UI components corresponding to the server modules (e.g., module_cm_candidate_agents.R, ui/home.R, etc.), which furnish the front-end layout.
– www: Contains static assets such as CSS, JavaScript, images, and HTML files needed for the frontend aesthetics and functionality.
– step by step: Contains workflow scripts and example runs (e.g., AM1, CM1 scripts) that likely demonstrate the analytical pipelines from data processing to model evaluation.
- This directory structure reveals a clear separation of concerns between the UI, server logic, libraries, data storage, and documentation.

a. Main Components:
- Client Interface (Frontend): Represented by the ui folder and www – these include user interface scripts (page layout, interactivity) and static assets (CSS, JS, images).
- Server (Backend) Application: Comprised of the app.R entry point, the server folder’s modular scripts for different functionalities (e.g., clinical associations, immunotherapy modules), and key configuration scripts.
- Business Logic and Utilities: The lib folder is crucial here, containing global functions, package-loading scripts, and supporting tools (e.g., shinyLink.R, database packages) that underpin both UI and server operations.
- Data Management and Storage: The db directory contains the primary datasets and preloaded information (Excel files, citation details, etc.) that feed into the analysis.
- Documentation and Help: The doc folder (and associated help files) explains the system, user guidance, and legal/copyright policies.
- Example Pipelines: The step by step folder, which shows example scripts for different analytical steps (calculations, evaluations, survival significance, etc.), illustrates the end-to-end processing workflows.

b. Relationships and Interactions:
- The user accesses the application via the UI elements (from the ui and www directories), which send interactions and inputs to the Shiny server.
- The Shiny server (via app.R) initializes the application, loading necessary global libraries from lib and processing requests by routing to appropriate server-side modules.
- Each server module (e.g., module_cm_candidate_agents.R, module_pm_immunotherapy.R) performs specific survival analysis functions using data from the db directory.
- Helper functions and shared resources in lib provide common functionalities (e.g., data loading, package management) available to both UI and server modules.

c. Architectural Patterns and Design Principles:
- Modular architecture: The separation of the UI and server directories into various modules encourages reusability and clearer maintenance.
- MVC-like separation: Even though it’s a Shiny app, the design separates the presentation (ui), business logic (server and lib) and data layer (db) akin to the Model-View-Controller (MVC) pattern.
- Configurability: The presence of configuration files (init.config.R, SurvivalML.Rproj) indicates environment-specific options and dependency management.

d. Relevant Technologies & Frameworks:
- R Language and Shiny Framework: The primary environment in which the application runs.
- Various R packages: As specified in the README (ComplexHeatmap, summaryBox, bsplus, etc.), which support data visualization, statistical analysis, and interactive components.
- Frontend assets: JavaScript and CSS in the www folder.
- External Data Sources: Excel files and text data within the db folder.

##### Elements to Explicitly Include
- UI Components: "Home, About, Contact, Analysis Modules" derived from ui/ files.
- Server Modules: "Clinical Association," "Prognostic Model," "Candidate Agents," etc., from server/ files.
- Utility/Library Functions: "Global Functions, Package Loaders" from the lib directory.
- Data Layer: "Raw Data & Database Files" from the db directory.
- Workflow Scripts: "Step-by-Step Analysis Pipelines" from the step by step directory.
- Configuration and documentation elements as supportive blocks, showing how external data and user guidance integrate into the overall system.

- Under the Backend, further segment it into domain-specific modules (e.g., clinical, prognostic, consensus model modules).
- Link the backend with the data repository (db) to showcase data flow and processing.
- Ancillary components such as setup (init.config.R) and documentation (doc), perhaps as peripheral yet connected modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    U["User Browser"]:::user

    %% Configuration
    subgraph "Configuration"
        CFG1["SurvivalML.Rproj"]:::config
        CFG2["init.config.R"]:::config
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        UI["UI Components"]:::frontend
        STATIC["Static Assets"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        APP["app.R (Entry Point)"]:::backend
        subgraph "Server Modules"
            SM1["module_cm_candidate_agents.R"]:::backend
            SM2["module_pm_immunotherapy.R"]:::backend
        end
        subgraph "Business Logic & Utilities"
            LIB["lib (Global Functions & Utilities)"]:::backend
        end
    end

    %% Data, Documentation and Workflow
    DATA["Data Repository (db folder)"]:::data
    DOC["Documentation & Help (doc folder)"]:::doc
    WORK["Workflow Scripts (step by step)"]:::workflow

    %% Connections
    U -->|"Accesses"| UI
    U -->|"Accesses"| STATIC
    UI -->|"SendsUserInput"| APP
    STATIC -->|"DeliversAssets"| UI
    APP -->|"InitiatesProcessing"| SM1
    APP -->|"InitiatesProcessing"| SM2
    APP -->|"UsesLibraries"| LIB
    SM1 -->|"QueriesData"| DATA
    SM2 -->|"QueriesData"| DATA
    LIB -->|"FetchesData"| DATA
    APP -->|"References"| DOC
    APP -->|"References"| WORK
    CFG1 -->|"Configures"| APP
    CFG2 -->|"SetsEnvironment"| APP

    %% Click Events
    click UI "https://github.com/fw1121/survivalml/tree/master/ui/"
    click STATIC "https://github.com/fw1121/survivalml/tree/master/www/"
    click APP "https://github.com/fw1121/survivalml/blob/master/app.R"
    click SM1 "https://github.com/fw1121/survivalml/blob/master/server/module_cm_candidate_agents.R"
    click SM2 "https://github.com/fw1121/survivalml/blob/master/server/module_pm_immunotherapy.R"
    click LIB "https://github.com/fw1121/survivalml/tree/master/lib/"
    click DATA "https://github.com/fw1121/survivalml/tree/master/db/"
    click DOC "https://github.com/fw1121/survivalml/tree/master/doc/"
    click WORK "https://github.com/fw1121/survivalml/tree/master/step by step/"
    click CFG1 "https://github.com/fw1121/survivalml/blob/master/SurvivalML.Rproj"
    click CFG2 "https://github.com/fw1121/survivalml/blob/master/init.config.R"

    %% Styles
    classDef user fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef frontend fill:#A6CEE3,stroke:#333,stroke-width:2px;
    classDef backend fill:#B2DF8A,stroke:#333,stroke-width:2px;
    classDef config fill:#FB9A99,stroke:#333,stroke-width:2px;
    classDef data fill:#CAB2D6,stroke:#333,stroke-width:2px;
    classDef doc fill:#FDBF6F,stroke:#333,stroke-width:2px;
    classDef workflow fill:#C0C0C0,stroke:#333,stroke-width:2px;
```
