⚡ FlowFactory AI

AI-powered n8n workflow engineering studio.

Describe your automation in plain English → get production-ready n8n workflow JSON with validation, documentation, and one-click deploy.

---

✨ Features

• Multi-agent pipeline — 6 specialized agents (Enhancer → Analyst → Architect → Builder → Repair → Designer) generate workflows step-by-step
• 106 specialist knowledge packs — domain experts for SEO, CRM, databases, AI/LLM, messaging, e-commerce, and more activate dynamically per prompt
• AI Agent pattern — generates modern n8n LangChain Agent workflows with proper sub-node connections (not raw HTTP)
• 20 validation rules — structural, expression, configuration, and security checks catch errors before you import
• Self-healing JSON — 3-stage repair (mechanical fixes → LLM-assisted → retry) handles malformed LLM output
• Coverage audit — detects missing services and auto-extends incomplete workflows
• Interactive canvas — pan, zoom, drag nodes, click to inspect parameters
• Chat-driven repair — describe an n8n error in the sidebar chat → workflow updates in-place
• Session persistence — every generation saved, rename/delete sessions, pick up where you left off
• Per-agent model selection — configure which Claude model each agent uses (Haiku for speed, Opus for reasoning)
• n8n instance management — connect, test, and deploy directly to your n8n servers
• Sticky note documentation — every workflow ships with visual section labels for the n8n canvas
• 10 prompt templates — pre-built recipes for common automation patterns
• Auto-fallback — if a model 503s, automatically retries with a lighter model

🏗️ Architecture

User prompt
  ↓
[Prompt Enhancer] — compresses + clarifies intent
  ↓
[Requirements Analyst] — extracts triggers, systems, steps
  ↓
[Workflow Architect] — selects nodes, maps connections
  ↓
[Skill Index] — picks top 7 specialists from 106 available
  ↓
[n8n Builder] — generates workflow JSON with specialist knowledge
  ↓
[Coverage Audit] — checks all services present, extends if missing
  ↓
[Validator] — 20 rules (structural, expression, config, security)
  ↓
[Repair Agent] — fixes validation failures (up to 3 attempts)
  ↓
[Designer] — adds sticky notes and section documentation
  ↓
Ready to deploy

See AGENTS.md for the full agent registry (106 specialists across 20 categories).

🚀 Quick Start

# Clone
git clone https://github.com/Xelson431/flowfactory-ai.git
cd flowfactory-ai

# Install
npm install

# Configure
cp .env.example .env.local
# Edit .env.local — set LLM_API_KEY (required)

# Run
npm run dev

# Open http://localhost:3000/studio

⚙️ Environment Variables

Variable	Required	Description
LLM_API_KEY	✅	API key for the LLM gateway
LLM_GATEWAY_URL	No	OpenAI-compatible endpoint (default: Kiro Gateway)
FLOWFACTORY_API_KEY	No	If set, all API routes require this key in x-api-key header
ENCRYPTION_KEY	No	AES-256-GCM key for encrypting n8n API keys at rest
DATABASE_URL	No	PostgreSQL connection (default: file-based)
NEXTAUTH_SECRET	No	Session encryption (auth disabled by default)

📁 Project Structure

src/
├── app/                    # Next.js App Router pages
│   ├── studio/             # Main IDE workspace (canvas + chat)
│   ├── templates/          # Prompt template library
│   ├── history/            # Generation archive
│   ├── instances/          # n8n connection management
│   └── api/                # API routes (generate, repair, deploy, sessions)
├── server/                 # Backend logic
│   ├── orchestrator.ts     # Multi-agent pipeline
│   ├── llm.ts              # LLM provider with auto-fallback
│   ├── validation.ts       # 20-rule validation engine
│   ├── json-repair.ts      # Self-healing JSON parser
│   ├── coverage-audit.ts   # Service coverage checker
│   ├── designer.ts         # Sticky note documentation agent
│   ├── prompt-enhancer.ts  # Input compression + clarification
│   ├── node-registry.ts    # Built-in vs community node detection
│   ├── models.ts           # Per-agent model configuration
│   └── specialists/        # 106 domain specialist knowledge packs
│       ├── core.ts         # Webhook, HTTP, DB, AI, messaging, etc.
│       ├── seo.ts          # 10 SEO specialists
│       ├── research.ts     # Market/niche/competitor research
│       ├── llm-endpoints.ts # 9 LLM provider API references
│       ├── node-catalog.ts # 100+ services → node type mapping
│       ├── meta.ts         # Always-on: linker, validator, best practices
│       └── ...             # Google, Microsoft, CRM, PM, e-commerce, etc.
├── schemas/                # Zod schemas for all data types
└── types/                  # Branded domain types

🧪 Testing

npm run test        # Run all tests (47 passing)
npm run build       # Production build

🔌 Custom LLM Endpoints

FlowFactory works with any OpenAI-compatible API. Set LLM_GATEWAY_URL to:

Provider	URL
OpenAI	https://api.openai.com/v1/chat/completions
Anthropic (via proxy)	Your proxy URL
Groq	https://api.groq.com/openai/v1/chat/completions
Together.AI	https://api.together.xyz/v1/chat/completions
OpenRouter	https://openrouter.ai/api/v1/chat/completions
Ollama (local)	http://localhost:11434/v1/chat/completions

🛡️ Security

• No secrets hardcoded — all credentials via environment variables
• API keys never logged or returned to the browser
• Generated workflows use {{CRED:name}} placeholders (never raw secrets)
• SQL injection prevention enforced in generated database nodes
• Prompt injection detection in user inputs
• HMAC signature verification patterns for webhook security
• Rate limiting — 30 requests/minute per IP on all API routes
• Optional API key auth — set FLOWFACTORY_API_KEY to lock down endpoints
• AES-256-GCM encryption — n8n instance API keys encrypted at rest
• Body size limits — 2MB max request body
• Prototype pollution protection — whitelist-only field updates on mutable routes

📖 API

Generate (streaming)

POST /api/workflows/generate
Content-Type: application/json

{
  "projectId": "uuid",
  "prompt": "When a webhook receives an order...",
  "style": "robust",
  "models": { "architect": "claude-sonnet-4.6" }
}
# Returns: SSE stream of generation events

Generate (non-streaming)

POST /api/generate
# Same body → returns { workflow, validation, id }

Repair

POST /api/repair
{ "workflowJson": {...}, "errorMessage": "Node X failed with 401" }
# Returns: { workflow, validation }

Deploy

POST /api/deploy
{ "instanceId": "uuid", "workflowJson": {...} }
# Pushes as inactive draft to n8n

🤝 Contributing

See CONTRIBUTING.md for development setup and guidelines.

📄 License

MIT — use it however you want.

🙏 Acknowledgments

• n8n — the workflow automation platform
• n8n-mcp — live node documentation
• Anthropic Claude — powers the generation agents
• ui-ux-pro-max — design intelligence