diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..3876ac3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,130 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+BioShinyModules is an R package providing reusable Shiny modules for biological data visualization and exploration. The package follows standard R package structure with modules designed for interactive data analysis including heatmaps, PCA plots, volcano plots, survival analysis, methylation analysis, and more.
+
+## Architecture
+
+### Module Pattern
+
+All Shiny modules follow a three-component pattern:
+
+1. **Core function**: Generates the underlying plot/visualization (e.g., `plotVolcano()`)
+2. **UI function**: `modulename_ui()` - defines the user interface with namespaced inputs
+3. **Server function**: `modulename_server()` - handles reactive logic and renders outputs
+4. **Demo function**: `modulename_demo()` - standalone app for testing the module
+
+Example naming convention for a module called "test":
+- `test_ui(id)` - UI component
+- `test_server(id, df, ...)` - Server component
+- `test_demo()` - Demo application
+
+### Directory Structure
+
+- `R/` - Core module files
+  - `R/modules/` - Individual plot modules (plotVolcano.R, plotKM.R, etc.)
+  - `R/app/` - Standalone Shiny applications using modules
+  - Utility functions at root level (dataImport.R, selectVar.R, exportPlot.R)
+- `data/` - Sample datasets (.rda format)
+- `data-raw/` - Scripts to generate .rda files from raw data
+- `tests/testthat/` - Unit tests
+- `documentation/` - Project documentation and templates
+- `vignettes/` - Usage examples
+
+### Key Utilities
+
+- `dataImport` module: Import data from csv, xlsx, xls, or rda formats
+- `selectVar` module: Select columns from dataframes with filtering (e.g., numeric only)
+- `exportPlot` module: Export plots in various formats
+- `read_data()`: Core function handling file reading based on extension
+
+## Common Development Commands
+
+### Package Development
+
+```r
+# Generate documentation from ROxygen comments
+devtools::document()
+
+# Run tests
+devtools::test()
+
+# Test coverage report
+library(covr)
+report()
+
+# Build and check package
+devtools::build()
+devtools::check()
+
+# BiocCheck validation (for Bioconductor submission)
+BiocCheck::BiocCheckGitClone()
+BiocCheck::BiocCheck('BioShinyModules'=TRUE)
+```
+
+### Creating New Modules
+
+Use the template at `documentation/template.R` as a starting point. Follow these steps:
+
+1. Copy template and rename functions to match module name
+2. Implement core plotting function
+3. Implement UI function with namespaced inputs using `NS(id)`
+4. Implement server function with `moduleServer(id, function(input, output, session) {...})`
+5. Create demo function for standalone testing
+6. Add ROxygen documentation
+7. Create test file: `usethis::use_test("module_name")`
+
+### Testing Individual Modules
+
+Run demo functions directly in R console:
+```r
+# Example: Test volcano plot module
+plotVolcano_demo()
+```
+
+### Code Style
+
+Follow Tidyverse style guide. Auto-format with:
+```r
+library(styler)
+# Apply to entire package
+styler::style_pkg()
+```
+
+## Data Format Expectations
+
+Most modules expect data in one of these formats:
+
+1. **Expression/intensity data**:
+   - `df` - data.frame with features as rows, samples as columns
+   - `sample_meta` - sample metadata (names, groups, conditions)
+   - `feature_meta` - feature metadata (gene names, IDs, etc.)
+
+2. **Statistical results**:
+   - data.frame with columns for p-values, adjusted p-values, log2 fold changes
+   - Used by volcano plots, Manhattan plots
+
+Example data available: `MS_1.rda` and `MS_2.rda` in data/ directory
+
+## Module Conventions
+
+- All modules accept reactive dataframes as inputs in server functions: `df()` not `df`
+- UI elements use namespacing: `ns <- NS(id)` then `ns("elementId")`
+- Server functions return reactive objects when the output should be reused
+- Download handlers commonly included for plot export
+- Use ROxygen2 for documentation with @param, @returns, @examples tags
+
+## Dependencies
+
+Key packages used across modules:
+- shiny, shinyWidgets - UI framework
+- ggplot2, plotly - Plotting
+- heatmaply - Interactive heatmaps
+- pcaMethods - PCA analysis
+- readxl - Excel file reading
+- RColorBrewer - Color palettes
+
+Add new dependencies with: `usethis::use_package("packagename")`