# synbioexplorer/welly architecture

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

- Interactive diagram: https://gitdiagram.com/synbioexplorer/welly
- Repository: https://github.com/synbioexplorer/welly

## Overview

##### Project type and purpose
- This is a full-stack, single-service web application built on Flask (Python).
- Purpose: allow users to upload plate-reader CSV/Excel data, compute growth metrics (max growth rate, AUC), cache results, and render interactive visualizations (line plots, heatmaps).

##### Key elements in the file structure
- app.py: the Flask application entrypoint, contains route handlers (upload, plate selection, processing, download).
- templates/: Jinja2 HTML templates (index.html, media_selection.html, edit_96.html, edit_384.html, results.html). These are the “View” layer.
- Static/: CSS/JS assets and example data. Served directly to browsers.
- cache-directory/: file-system cache for intermediate analysis results (hashed subfolders). Acts as a simple “Model” persistence without a database.
- downloads/: storage for user downloads (e.g., trial.csv).
- Generated HTML reports at root (growth_analysis_report.html, heatmap.html, interactive_plot.html) are artifacts of the processing component.

##### Architectural patterns and workflows
- MVC-like separation:
- Model = file-system (cache-directory, downloads) + in-memory data structures (Pandas DataFrames).
- View = templates/ + Static/ assets.
- Controller = app.py with Flask routes.
- Caching layer reduces recomputation: each upload is hashed and stored.
- Report-generation module outputs standalone HTML (heatmap, interactive plot).
- No external database; everything lives on disk in structured dirs.

##### Main components
- Client (Web Browser)
- Upload interface, interactive JS for plots (served from Static/)
- Web Server (Flask app.py)
- Route handlers: /, /upload, /select-media, /process, /results, /download
- Orchestrates processing modules
- Processing Modules (Python libraries)
- Data ingestion (Pandas, openpyxl/csv reader)
- Metric calculation (growth rate, AUC)
- Plot generation (Plotly/Matplotlib → HTML files)
- Cache Store (cache-directory)
- File-system hash buckets for reusing prior computations
- Download Store (downloads/)
- CSV & report files exposed via /download routes
- Template Engine (Jinja2)
- Merges computed data into HTML views
- Static Assets
- JavaScript, CSS, example CSVs under Static/
- External dependencies
- Flask, Pandas, NumPy, Plotly or Matplotlib, openpyxl (per requirements.txt)

##### Relationships & data flows
1. Browser sends HTTP POST (file upload) → Flask app
2. Flask checks cache-directory for existing hash; if miss, read file → Pandas DataFrame
3. Processing module computes metrics → stores results in cache-directory
4. Plot generator writes heatmap.html, interactive_plot.html, growth_analysis_report.html
5. Flask renders Jinja2 template (results.html), embedding links to static reports and data
6. Browser fetches static assets (JS/CSS) and interacts with the plots
7. User triggers download → GET /download → files from downloads/

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        Browser["Web Browser"]:::frontend
    end

    subgraph "Application Layer"
        subgraph "Flask Application"
            Controller["Controller (routes)"]:::backend
            Processor["Processing Modules"]:::backend
            CacheMgr["Cache Manager"]:::backend
            Reporter["Report Generator"]:::backend
            TemplateEngine["Template Engine (Jinja2)"]:::backend
        end

        subgraph "Frontend Assets"
            Templates["Templates/"]:::frontend
            index["index.html"]:::frontend
            media["media_selection.html"]:::frontend
            edit96["edit_96.html"]:::frontend
            edit384["edit_384.html"]:::frontend
            results["results.html"]:::frontend
            StaticAssets["Static/"]:::frontend
            exampleCSV["example_data.csv"]:::frontend
        end

        ExternalDeps["requirements.txt"]:::external
    end

    subgraph "Storage Layer"
        CacheStore["cache-directory/"]:::storage
        DownloadStore["downloads/"]:::storage
        trialCSV["trial.csv"]:::storage
        Reports["Reports HTML"]:::storage
        reportGA["growth_analysis_report.html"]:::storage
        reportHM["heatmap.html"]:::storage
        reportIP["interactive_plot.html"]:::storage
    end

    Browser -->|POST /upload| Controller
    Controller -->|check hash| CacheMgr
    CacheMgr -->|read/write| CacheStore
    Controller -->|compute_metrics| Processor
    Processor -->|store results| CacheMgr
    Processor -->|generate_reports| Reporter
    Reporter -->|writes| reportGA
    Reporter -->|writes| reportHM
    Reporter -->|writes| reportIP
    Controller -->|render HTML| TemplateEngine
    TemplateEngine -->|uses| Templates
    TemplateEngine -->|serves static| StaticAssets
    Controller -->|response HTML| Browser
    Browser -->|GET JS/CSS| StaticAssets
    Browser -->|GET reports| reportGA
    Browser -->|GET reports| reportHM
    Browser -->|GET reports| reportIP
    Browser -->|GET /download| Controller
    Controller -->|serves file| trialCSV

    click Controller "https://github.com/synbioexplorer/welly/blob/main/app.py"
    click index "https://github.com/synbioexplorer/welly/blob/main/templates/index.html"
    click media "https://github.com/synbioexplorer/welly/blob/main/templates/media_selection.html"
    click edit96 "https://github.com/synbioexplorer/welly/blob/main/templates/edit_96.html"
    click edit384 "https://github.com/synbioexplorer/welly/blob/main/templates/edit_384.html"
    click results "https://github.com/synbioexplorer/welly/blob/main/templates/results.html"
    click exampleCSV "https://github.com/synbioexplorer/welly/blob/main/Static/examples/example_data.csv"
    click CacheStore "https://github.com/synbioexplorer/welly/tree/main/cache-directory/"
    click DownloadStore "https://github.com/synbioexplorer/welly/tree/main/downloads/"
    click trialCSV "https://github.com/synbioexplorer/welly/blob/main/downloads/trial.csv"
    click reportGA "https://github.com/synbioexplorer/welly/blob/main/growth_analysis_report.html"
    click reportHM "https://github.com/synbioexplorer/welly/blob/main/heatmap.html"
    click reportIP "https://github.com/synbioexplorer/welly/blob/main/interactive_plot.html"
    click ExternalDeps "https://github.com/synbioexplorer/welly/blob/main/requirements.txt"

    classDef frontend fill:#D0E8F2,stroke:#0066CC,color:#000
    classDef backend fill:#DFF2D8,stroke:#339933,color:#000
    classDef storage fill:#FFE5CC,stroke:#CC6600,color:#000
    classDef external fill:#F2D8E8,stroke:#CC3399,color:#000
```
