# 🚀 N8N Workflow Documentation - Node.js Implementation

A fast, modern documentation system for N8N workflows built with Node.js and Express.js.

## ✨ Features

- **Lightning Fast Search**: SQLite FTS5 full-text search with sub-100ms response times
- **Smart Categorization**: Automatic workflow categorization by integrations and complexity
- **Visual Workflow Diagrams**: Interactive Mermaid diagrams for workflow visualization
- **Modern UI**: Clean, responsive interface with dark/light themes
- **RESTful API**: Complete API for workflow management and search
- **Real-time Statistics**: Live workflow stats and analytics
- **Secure by Default**: Built-in security headers and rate limiting

## 🛠️ Quick Start

### Prerequisites

- Node.js 19+ (configured to use `~/.nvm/versions/node/v19.9.0/bin/node`)
- npm or yarn package manager

### Installation

```bash
# Clone the repository
git clone <repository-url>
cd n8n-workflows

# Install dependencies
npm install

# Initialize database and directories
npm run init

# Copy your workflow JSON files to the workflows directory
cp your-workflows/*.json workflows/

# Index workflows
npm run index

# Start the server
npm start
```

### Development Mode

```bash
# Start with auto-reload
npm run dev

# Start on custom port
npm start -- --port 3000

# Start with external access
npm start -- --host 0.0.0.0 --port 8000
```

## 📂 Project Structure

```
n8n-workflows/
├── src/
│   ├── server.js           # Main Express server
│   ├── database.js         # SQLite database operations
│   ├── index-workflows.js  # Workflow indexing script
│   └── init-db.js         # Database initialization
├── static/
│   └── index.html         # Frontend interface
├── workflows/             # N8N workflow JSON files
├── database/             # SQLite database files
├── package.json          # Dependencies and scripts
└── README-nodejs.md      # This file
```

## 🔧 Configuration

### Environment Variables

- `NODE_ENV`: Set to 'development' for debug mode
- `PORT`: Server port (default: 8000)
- `HOST`: Server host (default: 127.0.0.1)

### Database

The system uses SQLite with FTS5 for optimal performance:
- Database file: `database/workflows.db`
- Automatic WAL mode for concurrent access
- Optimized indexes for fast filtering

## 📊 API Endpoints

### Core Endpoints

- `GET /` - Main documentation interface
- `GET /health` - Health check
- `GET /api/stats` - Workflow statistics

### Workflow Operations

- `GET /api/workflows` - Search workflows with filters
- `GET /api/workflows/:filename` - Get workflow details
- `GET /api/workflows/:filename/download` - Download workflow JSON
- `GET /api/workflows/:filename/diagram` - Get Mermaid diagram
- `POST /api/reindex` - Reindex workflows

### Search and Filtering

```bash
# Search workflows
curl "http://localhost:8000/api/workflows?q=slack&trigger=Webhook&complexity=low"

# Get statistics
curl "http://localhost:8000/api/stats"

# Get integrations
curl "http://localhost:8000/api/integrations"
```

## 🎯 Usage Examples

### Basic Search

```javascript
// Search for Slack workflows
const response = await fetch('/api/workflows?q=slack');
const data = await response.json();
console.log(`Found ${data.total} workflows`);
```

### Advanced Filtering

```javascript
// Get only active webhook workflows
const response = await fetch('/api/workflows?trigger=Webhook&active_only=true');
const data = await response.json();
```

### Workflow Details

```javascript
// Get specific workflow
const response = await fetch('/api/workflows/0001_Telegram_Schedule_Automation_Scheduled.json');
const workflow = await response.json();
console.log(workflow.name, workflow.description);
```

## 🔍 Search Features

### Full-Text Search
- Searches across workflow names, descriptions, and integrations
- Supports boolean operators (AND, OR, NOT)
- Phrase search with quotes: `"slack notification"`

### Filters
- **Trigger Type**: Manual, Webhook, Scheduled, Triggered
- **Complexity**: Low (≤5 nodes), Medium (6-15 nodes), High (16+ nodes)
- **Active Status**: Filter by active/inactive workflows

### Sorting and Pagination
- Sort by name, date, or complexity
- Configurable page size (1-100 items)
- Efficient offset-based pagination

## 🎨 Frontend Features

### Modern Interface
- Clean, responsive design
- Dark/light theme toggle
- Real-time search with debouncing
- Lazy loading for large result sets

### Workflow Visualization
- Interactive Mermaid diagrams
- Node type highlighting
- Connection flow visualization
- Zoom and pan controls

## 🔒 Security

### Built-in Protection
- Helmet.js for security headers
- Rate limiting (1000 requests/15 minutes)
- Input validation and sanitization
- CORS configuration

### Content Security Policy
- Strict CSP headers
- Safe inline styles/scripts only
- External resource restrictions

## 📈 Performance

### Optimization Features
- Gzip compression for responses
- SQLite WAL mode for concurrent reads
- Efficient database indexes
- Response caching headers

### Benchmarks
- Search queries: <50ms average
- Workflow indexing: ~1000 workflows/second
- Memory usage: <100MB for 10k workflows

## 🚀 Deployment

### Production Setup

```bash
# Install dependencies
npm ci --only=production

# Initialize database
npm run init

# Index workflows
npm run index

# Start server
NODE_ENV=production npm start
```

### Docker Deployment

```dockerfile
FROM node:19-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run init
EXPOSE 8000
CMD ["npm", "start"]
```

## 🛠️ Development

### Architecture

The system follows SOLID principles with clear separation of concerns:

- **Database Layer**: SQLite with FTS5 for search
- **API Layer**: Express.js with middleware
- **Frontend**: Vanilla JavaScript with modern CSS
- **CLI Tools**: Commander.js for command-line interface

### Code Style

- **YAGNI**: Only implement required features
- **KISS**: Simple, readable solutions
- **DRY**: Shared utilities and helpers
- **Kebab-case**: Filenames use kebab-case convention

### Testing

```bash
# Run basic health check
curl http://localhost:8000/health

# Test search functionality
curl "http://localhost:8000/api/workflows?q=test"

# Verify database stats
npm run index -- --stats
```

## 🔧 Troubleshooting

### Common Issues

1. **Database locked**: Ensure no other processes are using the database
2. **Memory issues**: Increase Node.js memory limit for large datasets
3. **Search not working**: Verify FTS5 is enabled in SQLite
4. **Slow performance**: Check database indexes and optimize queries

### Debug Mode

```bash
# Enable debug logging
NODE_ENV=development npm run dev

# Show detailed error messages
DEBUG=* npm start
```

## 🤝 Contributing

1. Follow the coding guidelines (YAGNI, SOLID, KISS, DRY)
2. Use English for all comments and documentation
3. Use kebab-case for filenames
4. Add tests for new features
5. Update README for API changes

## 📝 License

MIT License - see LICENSE file for details

## 🙏 Acknowledgments

- Original Python implementation as reference
- N8N community for workflow examples
- SQLite team for excellent FTS5 implementation
- Express.js and Node.js communities