n8n-workflows/README-nodejs.md

🚀 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

text

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
```text

text

text

#

#

# Development Mode

```text

text

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
```text

text

text

#

# 📂 Project Structure

```text

text

text
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
```text

text

text

#

# 🔧 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

```text

text

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">
```text

text

text

#

# 🎯 Usage Examples

#

#

# Basic Search

```text

text

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

text

text

#

#

# Advanced Filtering

```text

text

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

text

text

#

#

# Workflow Details

```text

text

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);
```text

text

text

#

# 🔍 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

```text

text

bash

# Install dependencies
npm ci --only=production

# Initialize database
npm run init

# Index workflows
npm run index

# Start server
NODE_ENV=production npm start
```text

text

text

#

#

# Docker Deployment

```text

text

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"]
```text

text

text

#

# 🛠️ 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

```text

text

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
```text

text

text

#

# 🔧 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

```text

text

bash

# Enable debug logging
NODE_ENV=development npm run dev

# Show detailed error messages
DEBUG=

* npm start
```text

text

text

#

# 🤝 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