Merge pull request #9 from rlorenzo/main

Add comprehensive Python-based n8n workflow documentation generator

CLAUDE.md

@@ -0,0 +1,108 @@
+# n8n-workflows Repository
+
+## Overview
+This repository contains a collection of n8n workflow automation files. n8n is a workflow automation tool that allows creating complex automations through a visual node-based interface. Each workflow is stored as a JSON file containing node definitions, connections, and configurations.
+
+## Repository Structure
+```
+n8n-workflows/
+├── workflows/           # Main directory containing all n8n workflow JSON files
+│   ├── *.json          # Individual workflow files
+├── README.md           # Repository documentation
+├── claude.md           # This file - AI assistant context
+└── [other files]       # Additional configuration or documentation files
+```
+
+## Workflow File Format
+Each workflow JSON file contains:
+- **name**: Workflow identifier
+- **nodes**: Array of node objects defining operations
+- **connections**: Object defining how nodes are connected
+- **settings**: Workflow-level configuration
+- **staticData**: Persistent data across executions
+- **tags**: Categorization tags
+- **createdAt/updatedAt**: Timestamps
+
+## Common Node Types
+- **Trigger Nodes**: webhook, cron, manual
+- **Integration Nodes**: HTTP Request, database connectors, API integrations
+- **Logic Nodes**: IF, Switch, Merge, Loop
+- **Data Nodes**: Function, Set, Transform Data
+- **Communication**: Email, Slack, Discord, etc.
+
+## Working with This Repository
+
+### For Analysis Tasks
+When analyzing workflows in this repository:
+1. Parse JSON files to understand workflow structure
+2. Examine node chains to determine functionality
+3. Identify external integrations and dependencies
+4. Consider the business logic implemented by node connections
+
+### For Documentation Tasks
+When documenting workflows:
+1. Verify existing descriptions against actual implementation
+2. Identify trigger mechanisms and schedules
+3. List all external services and APIs used
+4. Note data transformations and business logic
+5. Highlight any error handling or retry mechanisms
+
+### For Modification Tasks
+When modifying workflows:
+1. Preserve the JSON structure and required fields
+2. Maintain node ID uniqueness
+3. Update connections when adding/removing nodes
+4. Test compatibility with n8n version requirements
+
+## Key Considerations
+
+### Security
+- Workflow files may contain sensitive information in webhook URLs or API configurations
+- Credentials are typically stored separately in n8n, not in the workflow files
+- Be cautious with any hardcoded values or endpoints
+
+### Best Practices
+- Workflows should have clear, descriptive names
+- Complex workflows benefit from documentation nodes or comments
+- Error handling nodes improve reliability
+- Modular workflows (calling sub-workflows) improve maintainability
+
+### Common Patterns
+- **Data Pipeline**: Trigger → Fetch Data → Transform → Store/Send
+- **Integration Sync**: Cron → API Call → Compare → Update Systems
+- **Automation**: Webhook → Process → Conditional Logic → Actions
+- **Monitoring**: Schedule → Check Status → Alert if Issues
+
+## Helpful Context for AI Assistants
+
+When assisting with this repository:
+
+1. **Workflow Analysis**: Focus on understanding the business purpose by examining the node flow, not just individual nodes.
+
+2. **Documentation Generation**: Create descriptions that explain what the workflow accomplishes, not just what nodes it contains.
+
+3. **Troubleshooting**: Common issues include:
+   - Incorrect node connections
+   - Missing error handling
+   - Inefficient data processing in loops
+   - Hardcoded values that should be parameters
+
+4. **Optimization Suggestions**:
+   - Identify redundant operations
+   - Suggest batch processing where applicable
+   - Recommend error handling additions
+   - Propose splitting complex workflows
+
+5. **Code Generation**: When creating tools to analyze these workflows:
+   - Handle various n8n format versions
+   - Account for custom nodes
+   - Parse expressions in node parameters
+   - Consider node execution order
+
+## Repository-Specific Information
+[Add any specific information about your workflows, naming conventions, or special considerations here]
+
+## Version Compatibility
+- n8n version: [Specify the n8n version these workflows are compatible with]
+- Last updated: [Date of last major update]
+- Migration notes: [Any version-specific considerations]

README.md

@@ -1,63 +1,139 @@
-# 🧠 n8n Workflow Collection
+# 🧠 N8N Workflow Collection & Documentation
 
-This repository contains a collection of **n8n workflows** gathered from multiple sources, including:
+This repository contains a comprehensive collection of **2000+ n8n workflows** with an automated documentation system that provides detailed analysis and interactive browsing capabilities.
 
-* Workflows exported from the [n8n.io](https://n8n.io) website and community forum
+## 📊 Interactive Documentation
-* Publicly shared examples found across the web (GitHub, blogs, etc.)
 
-The goal is to provide a useful resource for inspiration, learning, and reuse in your own n8n projects.
+**Generate comprehensive documentation for all workflows:**
+
+```bash
+python3 generate_documentation.py
+```
+
+Then open `workflow-documentation.html` in your browser for:
+
+- 🔍 **Advanced Search & Filtering** - Find workflows by name, integration, or trigger type
+- 📈 **Statistics Dashboard** - Workflow counts, complexity metrics, and insights  
+- 🎯 **Smart Analysis** - Automatic categorization and description generation
+- 🌙 **Dark/Light Themes** - Accessible design with WCAG compliance
+- 📱 **Responsive Interface** - Works on desktop and mobile
+- 📄 **JSON Viewer** - Examine raw workflow files with copy/download
+- 🏷️ **Intelligent Tagging** - Automatic trigger type and complexity detection
+
+### Features
+
+The documentation system automatically analyzes each workflow to extract:
+- **Trigger Types**: Manual, Webhook, Scheduled, or Complex
+- **Complexity Levels**: Low (≤5 nodes), Medium (6-15), High (16+)
+- **Integrations**: All external services and APIs used
+- **Descriptions**: AI-generated summaries of workflow functionality
+- **Metadata**: Creation dates, tags, node counts, and more
 
 ---
 
-## 📂 Folder Structure
+## 📂 Workflow Sources
 
-* Each `.json` file represents a single exported workflow.
+This collection includes workflows from:
-* Files are named either based on their original title or source.
-* You may also find `.txt` files that were converted into `.json` (see below).
 
----
+* Official [n8n.io](https://n8n.io) website and community forum
+* Public GitHub repositories and community contributions
+* Blog posts, tutorials, and documentation examples
+* User-submitted automation examples
 
-## 🔄 TXT to JSON Conversion
+Files are organized with descriptive names indicating their functionality.
-
-Some workflows were originally saved as `.txt` files or copied from online sources. A script was used to:
-
-* Detect `.txt` files
-* Attempt to parse them as JSON or structured key-value pairs
-* Convert them to valid `.json` format
-
-If you’re looking to run the conversion yourself, check out `convert_txt_to_json.py` included in this repo.
 
 ---
 
 ## 🛠 Usage Instructions
 
-To import a workflow into your own n8n instance:
+### Import Workflows into n8n
 
 1. Open your [n8n Editor UI](https://docs.n8n.io/hosting/editor-ui/)
-2. Click on the **menu** (☰) in the top right → `Import workflow`
+2. Click the **menu** (☰) in top right → `Import workflow`
-3. Choose a `.json` file from this folder
+3. Choose any `.json` file from the `workflows/` folder
 4. Click "Import" to load the workflow
+5. Review and update credentials/webhook URLs before running
 
-Make sure to review and modify credentials or webhook URLs as needed before running.
+### Browse & Discover Workflows
+
+1. **Generate Documentation**: `python3 generate_documentation.py`
+2. **Open Documentation**: Open `workflow-documentation.html` in browser
+3. **Search & Filter**: Use the interface to find relevant workflows
+4. **Examine Details**: View descriptions, integrations, and raw JSON
+
+---
+
+## 🔧 Technical Details
+
+### Documentation Generator (`generate_documentation.py`)
+
+- **Static Analysis**: Processes all JSON files in `workflows/` directory
+- **No Dependencies**: Uses only Python standard library
+- **Performance**: Handles 2000+ workflows efficiently  
+- **Output**: Single self-contained HTML file with embedded data
+- **Compatibility**: Works with Python 3.6+ and all modern browsers
+
+### Analysis Capabilities
+
+- **Integration Detection**: Identifies external services from node types
+- **Trigger Classification**: Categorizes workflows by execution method
+- **Complexity Assessment**: Rates workflows based on node count and variety
+- **Description Generation**: Creates human-readable summaries automatically
+- **Metadata Extraction**: Pulls creation dates, tags, and configuration details
+
+---
+
+## 📊 Repository Statistics
+
+- **Total Workflows**: 2053+ automation workflows
+- **File Format**: n8n-compatible JSON exports
+- **Size Range**: Simple 2-node workflows to complex 50+ node automations
+- **Categories**: Data sync, notifications, integrations, monitoring, and more
+- **Services**: 100+ different platforms and APIs represented
 
 ---
 
 ## 🤝 Contribution
 
-Found a cool workflow or created your own?
+Found a useful workflow or created your own? Contributions welcome!
-Feel free to contribute by adding it to this collection!
 
-Just make sure to:
+**Adding Workflows:**
+1. Export your workflow as JSON from n8n
+2. Add the file to the `workflows/` directory with a descriptive name
+3. Run `python3 generate_documentation.py` to update documentation
+4. Submit a pull request
 
-* Name the file descriptively
+**Guidelines:**
-* Include a short comment at the top with the original source if applicable
+- Use descriptive filenames (e.g., `slack_notification_system.json`)
+- Test workflows before contributing
+- Remove sensitive data (credentials, URLs, etc.)
 
 ---
 
-## ⚠️ Disclaimer
+## 🚀 Quick Start
 
-All workflows here are shared **as-is**.
+1. **Clone Repository**: `git clone <repo-url>`
-Always inspect and test them in a safe environment before using them in production.
+2. **Generate Docs**: `python3 generate_documentation.py`  
+3. **Browse Workflows**: Open `workflow-documentation.html`
+4. **Import & Use**: Copy interesting workflows to your n8n instance
 
 ---
 
+## ⚠️ Important Notes
+
+- **Security**: All workflows shared as-is - always review before production use
+- **Credentials**: Remove/update API keys, tokens, and sensitive URLs
+- **Testing**: Verify workflows in safe environment before deployment
+- **Compatibility**: Some workflows may require specific n8n versions or community nodes
+
+---
+
+## 📋 Requirements
+
+- **For Documentation**: Python 3.6+ (no additional packages needed)
+- **For Workflows**: n8n instance (self-hosted or cloud)
+- **For Viewing**: Modern web browser (Chrome, Firefox, Safari, Edge)
+
+---
+
+*This automated documentation system makes it easy to discover, understand, and utilize the extensive collection of n8n workflows for your automation needs.*