n8n_clone

A full‑stack, from‑scratch clone of n8n — built and maintained by sohampirale.

This repository is not a fork of the upstream project. It is an independently implemented workflow automation platform inspired by n8n that includes the editor, runtime, persistence, and a set of built‑in nodes and tools — including a custom AI Agent node and messaging/email tools (Telegram send & wait, Gmail send, and more).

This README was drafted from the description you provided. I have created a complete, practical README to help users and contributors get started quickly. If you want me to read repository files and tailor sections (examples, exact scripts, env names, node names) to your code, tell me and I will fetch the repo or you can paste the key files (package.json, server start scripts, .env.example, Dockerfile, docker-compose.yml, and a sample workflow config).

Quick links

• Project: sohampirale/n8n_clone
• Maintainer: sohampirale
• Current date: 2025-11-10

What this project is

n8n_clone is a self-built workflow automation system with:

• Visual workflow editor (drag & drop nodes)
• Workflow runtime and execution engine
• Webhook handling and public webhook exposure support
• Credentials and secure storage
• Multiple persistence options (SQLite for dev, PostgreSQL recommended for production)
• Built-in nodes for common integrations and a set of custom nodes you created:
  • AI Agent node (LLM orchestration)
  • Telegram Send node
  • Telegram WaitForResponse node
  • Gmail Send node
  • Plus other HTTP / JSON / Utility nodes

Key goals

• Provide an extensible workflow automation platform suitable for experiments and production use
• Make it straightforward to add custom nodes and tools (AI tooling and messaging integrations)
• Keep the developer experience ergonomic (hot reload, TypeScript, Docker support)

Highlights — custom features you mentioned

AI Agent node

• Orchestrates prompts, chains, tools, and decisions inside workflows.
• Can call LLM providers (OpenAI, Anthropic, local LLM endpoints) depending on configured provider keys.
• Exposes inputs for prompt template, context, memory, and tool invocation spec.
• Can return structured data (JSON) or produce human‑readable text.
• Supports tool integration so the agent can call Telegram or Gmail tools (send messages, wait for user replies, send emails) as part of a single workflow run.

Telegram Send + WaitForResponse

• Telegram Send: sends messages to Telegram chat IDs using a bot token.
• Telegram WaitForResponse: opens a blocking or background wait for the next reply (useful for multi-turn conversations).
• Typical usage: Workflow sends a question with Telegram Send, then pipeline yields to WaitForResponse which resumes the workflow when a reply arrives.

Gmail Send

• Sends email using Gmail SMTP or Gmail API credentials (OAuth or app passwords depending on your setup).
• Supports attachments, HTML bodies, recipients, CC/BCC, and templating variables.

Architecture overview

• Frontend: Typescript React-based editor (single-page app).
• Backend: Typescript Node server providing:
  • REST & WebSocket APIs for editor and runtime control
  • Webhook endpoints for triggers
  • Execution engine that runs nodes in series/parallel with retry and error handling
• Persistence: TypeORM / Prisma or custom DB layer (SQLite for quick start and Postgres for production)
• Nodes: Each node is implemented as a TypeScript module with a defined input schema, output schema, and execute() handler
• Agent/Tooling: Agent node loads tool definitions (adapters that wrap Telegram/Gmail/HTTP/etc.) and LLM clients

Prerequisites

• Node.js 18+ (LTS recommended)
• pnpm / npm / yarn (pnpm recommended for monorepos)
• Docker & Docker Compose (recommended for production or to avoid local DB setup)
• PostgreSQL (for production)
• Optional API keys:
  • OPENAI_API_KEY (if using OpenAI)
  • TELEGRAM_BOT_TOKEN
  • GMAIL_CLIENT_ID / GMAIL_CLIENT_SECRET / GMAIL_REFRESH_TOKEN (if using Gmail API)

Environment variables (common)

Below are commonly used environment variables. Adjust names to match your repo's .env.example.

• N8N_PORT — port to run the web UI and API (default: 5678)
• N8N_HOST — host (default: 0.0.0.0)
• DB_TYPE — sqlite | postgres
• DB_SQLITE_PATH — path to sqlite file (e.g., ./data/database.sqlite)
• DB_POSTGRES_HOST
• DB_POSTGRES_PORT
• DB_POSTGRES_USER
• DB_POSTGRES_PASSWORD
• DB_POSTGRES_DATABASE
• NODE_ENV — development | production
• OPENAI_API_KEY — API key for OpenAI (if using)
• AGENT_DEFAULT_MODEL — default LLM model for AI Agent node
• TELEGRAM_BOT_TOKEN — for Telegram nodes
• GMAIL_* — keys/tokens for Gmail integration
• WEBHOOK_URL — public URL for webhooks (if behind proxy)
• N8N_BASIC_AUTH_ACTIVE — true/false
• N8N_BASIC_AUTH_USER — basic auth username
• N8N_BASIC_AUTH_PASSWORD — basic auth password

Quick start — Docker (recommended)

1. Create or update docker-compose.yml with your configuration. Example:

version: "3.8"
services:
  app:
    build: .
    image: sohampirale/n8n_clone:latest  # replace with your image name
    ports:
      - "5678:5678"
    environment:
      - N8N_PORT=5678
      - DB_TYPE=sqlite
      - DB_SQLITE_PATH=/data/database.sqlite
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=changeme
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - ./data:/data

2. Start:

docker compose up -d

3. Visit: http://localhost:5678

Quick start — Local development

1. Clone

git clone https://github.com/sohampirale/n8n_clone.git
cd n8n_clone

2. Install dependencies

# pnpm
pnpm install

# or npm / yarn
npm install

3. Copy .env.example to .env and populate keys:

cp .env.example .env
# Edit .env to add TELEGRAM_BOT_TOKEN, OPENAI_API_KEY, DB config, etc.

4. Run in development mode (hot reload)

pnpm dev
# or
npm run dev

5. Build & start (production mode)

pnpm build
pnpm start

Running tests

• Unit tests: npm run test (or pnpm test)
• Integration / E2E: follow instructions in the tests folder (may rely on external services / Docker)

Node development guide (how to add a node)

Each node in this platform follows a simple pattern:

1. Node metadata (name, displayName, description, inputs/outputs, credentials)
2. Node parameter definitions (fields shown in the editor)
3. Execution function which receives input data and context and returns output data
4. Tool declarations (for Agent tools)

To add a node:

• Create a new TypeScript module in src/nodes/
• Export the node descriptor and the execute handler
• Register the node in the node registry (src/nodes/index.ts)
• Rebuild and test in the editor

AI Agent node — recommended usage

The AI Agent node enables LLM-driven workflows with tool access.

Typical fields:

• model: string (model identifier)
• promptTemplate: string (handles templating using incoming workflow data)
• tools: list of tool connectors (TelegramSend, GmailSend, HTTP, etc.)
• maxTokens, temperature, top_p, stop

Example flow (high level):

1. Webhook trigger receives a user request.
2. AI Agent node generates a response and determines it needs to ask the user a follow-up on Telegram.
3. Telegram Send node sends the question.
4. Telegram WaitForResponse node pauses the workflow until user replies.
5. The reply resumes the workflow; AI Agent continues processing and sends a final email using Gmail Send.

Security notes

• Treat API keys and credentials as secrets. Use environment variables or secret stores in production.
• When enabling webhooks, ensure you configure a secure WEBHOOK_URL and optionally use signing/verification.
• If using OAuth credentials (Gmail), store refresh tokens securely.
• Limit access to the editor (enable basic auth or other auth mechanisms).

Production recommendations

• Use PostgreSQL for production (DB_TYPE=postgres).
• Run the app behind a reverse proxy (NGINX) with HTTPS.
• Use process managers (systemd, Docker, or Kubernetes) and monitor memory/CPU.
• Periodically backup the database and credential store.
• Consider separating execution workers from the API server for high throughput workflows.

Troubleshooting

• App won't start:
  • Check logs: docker compose logs -f app or pnpm start logs
  • Ensure DB is reachable and migrations applied
• Webhooks not firing:
  • Confirm WEBHOOK_URL is correct and reachable from outside
  • Check firewall or reverse proxy for route/port issues
• Telegram messages not delivered:
  • Verify TELEGRAM_BOT_TOKEN and chat_id are correct
  • Check Telegram API rate limits

Contributing

Thanks for considering contributing! Typical contribution workflow:

• Fork or branch from main
• Add your feature or fix
• Add tests where appropriate
• Open a pull request with a clear description and testing steps

Please follow the repo's code style (TypeScript, lint rules). If you want me to create a CONTRIBUTING.md, I can draft one that matches your repo rules — tell me or allow me to read the repo to align it exactly.