How mhbsiam/cafe works
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)