n8n-per-heru-architecture

Architecture

Every client Heru gets its own n8n instance across three environments:

Environment	n8n Location	Database	Cost
Local	Docker service (port 5678)	Same PostgreSQL, n8n schema	$0
Develop	Ephemeral EC2 (free tier t2.micro)	Develop database	$0 (free tier)
Production	IN the App Runner Docker container	Production database (PostgreSQL)	Part of App Runner cost

Key Rules

• QCS1 (n8n.quiknation.com) = Quik Nation INTERNAL only. Never for clients.
• Every Heru repo gets an n8n/ directory at root alongside frontend/, backend/, mobile/
• Workflow JSON files exported and stored in n8n/workflows/
• n8n uses PostgreSQL (NOT SQLite) — separate n8n schema in same database
• Credentials NEVER in git — stay in n8n instance
• Robert (Ephemeral Swarm agent) manages the EC2 lifecycle
• Otis creates the workflows, deploys to each environment

n8n CAN run on App Runner

n8n is a Node.js app. It runs in Docker. App Runner runs Docker containers. Previous session incorrectly said it couldn’t — that was WRONG. For production, n8n bundles into the same Docker container as the backend.

n8n Authentication — Use Client’s Clerk (Production)

• Each client Heru’s n8n uses that Heru’s PRODUCTION Clerk instance
• Route n8n.{domain}.com through backend → Clerk middleware validates JWT → proxy to n8n
• Cali/Ed/clients use same login for website, admin panel, AND n8n
• Admin role required to access n8n
• Same pattern for every client Heru

n8n URL Pattern

• Client-facing: n8n.fmogrooming.com (DNS pointed to EC2 during dev, App Runner in prod)
• NOT raw IP addresses for client visibility

n8n Lifecycle Per Heru

1. Local: Docker service (port 5678) — developer testing
2. Develop: EC2 instance with Clerk auth — client can see at n8n.{domain}.com
3. Production: Move n8n from EC2 INTO App Runner Docker container at MVP time
   • This is a MOVE, not a rebuild — same workflows, same config
   • All that changes is the hosting location

App Runner Pricing (CORRECTED)

• Pay per use: ~$5-15/month for low-traffic MVP
• NOT $160/month (that was wrong, from an old memory file)
• Actual: $0.064/vCPU-hour+$0.007/GB-hour when processing

FMO Reference Implementation

• docker-compose.yml updated with n8n service
• n8n/ directory created at project root with workflows/ and credentials/
• Local: http://localhost:5678 (admin/fmo2026)
• EC2: http://13.222.187.83:5678 → will become n8n.fmogrooming.com
• PostgreSQL schema: n8n in database