# mhbsiam/cafe architecture

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

- Interactive diagram: https://gitdiagram.com/mhbsiam/cafe
- Repository: https://github.com/mhbsiam/cafe

## Overview

##### Project Type and Purpose
- CAFE is a monolithic Python–based data-analysis platform with two user interfaces (CLI and web) plus a companion static documentation site.
- It targets high-dimensional spectral flow cytometry data: ingesting CSV/H5AD, processing/visualizing clusters, and producing publication-quality figures.

##### File-Structure Analysis
- Top-level directories and files
– CAFE/ – core Python package containing scripts, modules, configs
- bin/ – entry‐points and subpackages (Adv, App, Tools, web)
- cafe.py, cafe_hpc.py, web.py – convenience launchers
- cafe.yaml, pixi.toml – pipeline and package configs
- .streamlit/ – Streamlit UI configuration
– public/, src/ – static-site (documentation) code (Astro+MDX)
– .github/ – CI/CD workflow for deployments
– package.json, astro.config.mjs, tsconfig.json – static-site build config
- Key patterns
– Modular Python “core” for data-processing (Tools) and clustering tasks (Adv)
– Dual interfaces calling the same core modules:
- CLI app (CAFE/bin/App/CAFE.py via pixi run cafe)
- Web app (Streamlit scripts in CAFE/bin/web)
– Documentation site built separately with Astro

##### README Insights
- Confirms dual-mode (“no-code” web and CLI) operation, installation via Pixi or Conda, and deployment on regular desktops.

a. Main Components
1. End Users
- CLI Users (Terminal)
- Web Users (Browser)
2. Interfaces
- CLI Launcher (“pixi run cafe” → CAFE.bin.run.py)
- Streamlit Web UI (CAFE/bin/web/CAFE.py + config)
3. Core Processing Modules
- Data_Processing (Tools/Data_Processing.py)
- Visualization (Tools/Visualization.py)
- Clustering Suite (Adv/*: Downsampling, Merge, Annotation, Evaluation, Selective)
4. Configuration
- cafe.yaml (pipeline parameters)
- pixi.toml (package metadata)
- .streamlit/config.toml
5. Static Documentation Site
- Astro code (src/, public/) → GitHub Pages
6. External Services & Tools
- Pixi package manager
- Conda (alternative)
- GitHub Actions (CI/CD)
- Python environment & dependencies (Scanpy, numpy, Streamlit)

b. Relationships & Data Flow
1. User invokes CLI or opens web UI
2. Launcher reads cafe.yaml → initializes core modules
3. Core modules process input data → generate intermediate results
4. Visualization module creates plots → returns to user
5. User downloads figures; logs saved
6. Documentation site is built independently and served via GitHub Pages

c. Architectural Patterns & Principles
– Layered Modularization:
- Interface Layer (CLI/Web)
- Business Logic Layer (Core Processing modules)
- Configuration Layer (YAML, TOML)
– Code Reuse: both interfaces share the same core modules
– Separation of Concerns: static docs separated from runtime code

d. Key Technologies & Frameworks
– Python 3.12 with Scanpy, numpy, Streamlit
– Pixi (package management)
– Astro + MDX + TypeScript for docs
– GitHub Actions for CI/CD

##### Elements
- Blue for Interface components
- Green for Core modules
- Gray for Config/Infrastructure
- Rectangles for software modules
– Annotations for key dependencies (Python libs, Pixi, GitHub Actions)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Tier
    subgraph "User Tier"
        CLI_User["CLI User"]:::interface
        Browser_User["Web User"]:::interface
    end

    %% Application Tier
    subgraph "Application Tier"
        subgraph "Interface Layer"
            CLILauncher["CLI Launcher<br/>(pixi run cafe)"]:::interface
            StreamlitUI["Streamlit Web UI"]:::interface
        end
        subgraph "Core Processing Modules"
            DataProc["Data_Processing Module"]:::core
            Viz["Visualization Module"]:::core
            subgraph "Clustering Suite"
                Down["Downsampling"]:::core
                Merge["Merge_Clusters"]:::core
                Annot["Cluster_Annotation"]:::core
                Eval["Cluster_Evaluation"]:::core
                Selective["Selective_Clustering"]:::core
            end
        end
    end

    %% Infrastructure Tier
    subgraph "Infrastructure Tier"
        ConfigYAML["cafe.yaml"]:::infra
        ConfigPixi["pixi.toml"]:::infra
        StreamlitConf[".streamlit/config.toml"]:::infra
        PythonEnv["Python Env & Deps"]:::infra
        PixiPM["Pixi Package Manager"]:::infra
        Conda["Conda"]:::infra
        CI["GitHub Actions (CI/CD)"]:::infra
        subgraph "Convenience Launchers"
            CafePy["cafe.py"]:::infra
            CafeHPC["cafe_hpc.py"]:::infra
            WebPy["web.py"]:::infra
        end
    end

    %% Static Documentation Site
    subgraph "Static Documentation Site"
        DocsSrc["src/"]:::infra
        DocsPublic["public/"]:::infra
        AstroConf["astro.config.mjs"]:::infra
        PackageJSON["package.json"]:::infra
        TSConfig["tsconfig.json"]:::infra
    end

    %% Data Flow & Dependencies
    CLI_User -->|"invokes"| CLILauncher
    Browser_User -->|"opens"| StreamlitUI
    CLILauncher -->|"reads config"| ConfigYAML
    StreamlitUI -->|"reads config"| StreamlitConf
    CLILauncher --> DataProc
    StreamlitUI --> DataProc
    DataProc --> Down
    DataProc --> Merge
    DataProc --> Annot
    DataProc --> Eval
    DataProc --> Selective
    Down --> Viz
    Merge --> Viz
    Annot --> Viz
    Eval --> Viz
    Selective --> Viz
    Viz --> CLI_User
    Viz --> Browser_User

    CLILauncher --> PixiPM
    CLILauncher --> Conda
    StreamlitUI --> PythonEnv

    CI -->|"deploy docs"| DocsSrc
    CI -->|"deploy docs"| DocsPublic

    %% Click Events
    click CLILauncher "https://github.com/mhbsiam/cafe/blob/main/CAFE/bin/run.py"
    click CLILauncher "https://github.com/mhbsiam/cafe/blob/main/CAFE/bin/App/CAFE.py"
    click StreamlitUI "https://github.com/mhbsiam/cafe/blob/main/CAFE/bin/web/CAFE.py"
    click StreamlitUI "https://github.com/mhbsiam/cafe/blob/main/CAFE/.streamlit/config.toml"
    click DataProc "https://github.com/mhbsiam/cafe/blob/main/CAFE/bin/Tools/Data_Processing.py"
    click Viz "https://github.com/mhbsiam/cafe/blob/main/CAFE/bin/Tools/Visualization.py"
    click Down "https://github.com/mhbsiam/cafe/blob/main/CAFE/bin/Adv/Downsampling.py"
    click Merge "https://github.com/mhbsiam/cafe/blob/main/CAFE/bin/Adv/Merge_Clusters.py"
    click Annot "https://github.com/mhbsiam/cafe/blob/main/CAFE/bin/Adv/Cluster_Annotation.py"
    click Eval "https://github.com/mhbsiam/cafe/blob/main/CAFE/bin/Adv/Cluster_Evaluation.py"
    click Selective "https://github.com/mhbsiam/cafe/blob/main/CAFE/bin/Adv/Selective_Clustering.py"
    click ConfigYAML "https://github.com/mhbsiam/cafe/blob/main/CAFE/cafe.yaml"
    click ConfigPixi "https://github.com/mhbsiam/cafe/blob/main/CAFE/pixi.toml"
    click StreamlitConf "https://github.com/mhbsiam/cafe/blob/main/CAFE/.streamlit/config.toml"
    click CafePy "https://github.com/mhbsiam/cafe/blob/main/CAFE/cafe.py"
    click CafeHPC "https://github.com/mhbsiam/cafe/blob/main/CAFE/cafe_hpc.py"
    click WebPy "https://github.com/mhbsiam/cafe/blob/main/CAFE/web.py"
    click AstroConf "https://github.com/mhbsiam/cafe/blob/main/astro.config.mjs"
    click PackageJSON "https://github.com/mhbsiam/cafe/blob/main/package.json"
    click TSConfig "https://github.com/mhbsiam/cafe/blob/main/tsconfig.json"
    click DocsSrc "https://github.com/mhbsiam/cafe/tree/main/src/"
    click DocsPublic "https://github.com/mhbsiam/cafe/tree/main/public/"

    %% Styles
    classDef interface fill:#B3CDE3,stroke:#000,stroke-width:1px
    classDef core fill:#C7E9C0,stroke:#000,stroke-width:1px
    classDef infra fill:#D9D9D9,stroke:#000,stroke-width:1px
```
