Skip to content

abdo-hash1/n8n-intag-store

Repository files navigation

n8n SaaS Platform - Complete Documentation

Version: 1.0.0
Last Updated: January 2, 2026
Status: Development - Phase 1 Complete, Phase 2 Planned

A complete SaaS platform for hosting n8n automation instances with subscription-based billing, designed for the Egyptian market.


πŸ“‹ Table of Contents

  1. Project Overview
  2. Completed Features
  3. Technology Stack
  4. Project Structure
  5. Database Schema
  6. API Endpoints
  7. Business Logic
  8. Admin Panel Features
  9. Next Phase: n8n Instance Provisioning
  10. Infrastructure Architecture
  11. Setup Instructions
  12. Environment Variables
  13. Security Features

🎯 Project Overview

This platform enables customers to subscribe to hosted n8n automation instances. The system handles:

  • User Registration & Authentication
  • Subscription Management (Monthly/Annual plans)
  • Payment Processing (Paymob integration for Egyptian payments)
  • Support Ticketing System
  • Admin Dashboard for platform management
  • Automated n8n Instance Provisioning (Next Phase)

Target Market

  • Egyptian businesses needing automation
  • Pricing in EGP (Egyptian Pounds)
  • Arabic-friendly UI

βœ… Completed Features

Phase 1 - Core Platform (DONE)

Authentication System

  • User signup with email verification
  • Login with JWT tokens
  • Password reset flow
  • Session management
  • Role-based access (user, admin, super_admin, support_agent)

Subscription Management

  • Monthly plan (400 EGP/month)
  • Annual plan (3,800 EGP/year)
  • Plan upgrade/downgrade with proration
  • Subscription pause/resume
  • Subscription cancellation
  • Grace period (7 days) for failed payments

Payment System

  • Paymob payment gateway integration
  • Payment webhook handling
  • Invoice generation
  • Refund requests workflow
  • Payment retry logic

Coupon System

  • Percentage and fixed-amount discounts
  • Validity period (start/end dates)
  • Usage limits (total and per-user)
  • Plan-specific coupons
  • Minimum order amount requirements

Support System

  • Ticket creation with categories
  • Priority levels (low, normal, high, urgent)
  • Message threading
  • Admin assignment
  • Status workflow (open β†’ waiting β†’ resolved β†’ closed)
  • SLA tracking

Admin Panel

  • Dashboard with key metrics
  • User management (list, view, edit, suspend)
  • Subscription management
  • Payment history
  • Coupon management (CRUD)
  • Pricing configuration (edit plan prices and features)
  • Support ticket management
  • Activity logs
  • Pagination component - reusable across all list views
  • Search and filtering

Email System

  • SendGrid integration
  • Welcome emails
  • Payment confirmation
  • Subscription updates
  • Password reset
  • Support ticket notifications

πŸ› οΈ Technology Stack

Backend

Technology Purpose
Node.js 20+ Runtime environment
Express.js Web framework
TypeScript Type safety
Prisma ORM Database abstraction
SQLite (dev) / PostgreSQL (prod) Database
JWT Authentication tokens
bcrypt Password hashing
SendGrid Email delivery
Paymob Payment gateway

Frontend

Technology Purpose
Next.js 14+ React framework (App Router)
TypeScript Type safety
TailwindCSS Styling
Shadcn/ui UI component library
Lucide Icons Icon library
React Hook Form Form management
Zod Validation

Infrastructure (Planned)

Technology Purpose
Docker Containerization
Docker Swarm Orchestration
Hetzner Cloud VPS hosting
Traefik Reverse proxy & SSL
PostgreSQL Shared database
Redis Queue for n8n

πŸ“ Project Structure

n8n-intag-store/
β”œβ”€β”€ backend/
β”‚   β”œβ”€β”€ prisma/
β”‚   β”‚   β”œβ”€β”€ schema.prisma          # Database models
β”‚   β”‚   β”œβ”€β”€ seed.ts                # Seed data script
β”‚   β”‚   └── migrations/            # Database migrations
β”‚   β”œβ”€β”€ src/
β”‚   β”‚   β”œβ”€β”€ config/
β”‚   β”‚   β”‚   β”œβ”€β”€ database.ts        # Prisma client
β”‚   β”‚   β”‚   β”œβ”€β”€ env.ts             # Environment config
β”‚   β”‚   β”‚   └── swagger.ts         # API docs config
β”‚   β”‚   β”œβ”€β”€ controllers/
β”‚   β”‚   β”‚   β”œβ”€β”€ auth.controller.ts
β”‚   β”‚   β”‚   β”œβ”€β”€ user.controller.ts
β”‚   β”‚   β”‚   β”œβ”€β”€ subscription.controller.ts
β”‚   β”‚   β”‚   β”œβ”€β”€ payment.controller.ts
β”‚   β”‚   β”‚   β”œβ”€β”€ support.controller.ts
β”‚   β”‚   β”‚   β”œβ”€β”€ coupon.controller.ts
β”‚   β”‚   β”‚   β”œβ”€β”€ admin.controller.ts
β”‚   β”‚   β”‚   └── webhook.controller.ts
β”‚   β”‚   β”œβ”€β”€ middleware/
β”‚   β”‚   β”‚   β”œβ”€β”€ auth.middleware.ts     # JWT verification
β”‚   β”‚   β”‚   β”œβ”€β”€ admin.middleware.ts    # Admin role check
β”‚   β”‚   β”‚   β”œβ”€β”€ validate.middleware.ts # Request validation
β”‚   β”‚   β”‚   β”œβ”€β”€ error.middleware.ts    # Error handling
β”‚   β”‚   β”‚   └── rateLimiter.middleware.ts
β”‚   β”‚   β”œβ”€β”€ routes/
β”‚   β”‚   β”‚   β”œβ”€β”€ auth.routes.ts
β”‚   β”‚   β”‚   β”œβ”€β”€ user.routes.ts
β”‚   β”‚   β”‚   β”œβ”€β”€ subscription.routes.ts
β”‚   β”‚   β”‚   β”œβ”€β”€ payment.routes.ts
β”‚   β”‚   β”‚   β”œβ”€β”€ support.routes.ts
β”‚   β”‚   β”‚   β”œβ”€β”€ coupon.routes.ts
β”‚   β”‚   β”‚   β”œβ”€β”€ admin.routes.ts
β”‚   β”‚   β”‚   β”œβ”€β”€ webhook.routes.ts
β”‚   β”‚   β”‚   β”œβ”€β”€ pricing.routes.ts
β”‚   β”‚   β”‚   └── index.ts
β”‚   β”‚   β”œβ”€β”€ services/
β”‚   β”‚   β”‚   β”œβ”€β”€ auth.service.ts        # Authentication logic
β”‚   β”‚   β”‚   β”œβ”€β”€ user.service.ts        # User management
β”‚   β”‚   β”‚   β”œβ”€β”€ subscription.service.ts # Subscription logic
β”‚   β”‚   β”‚   β”œβ”€β”€ paymob.service.ts      # Payment gateway
β”‚   β”‚   β”‚   β”œβ”€β”€ support.service.ts     # Ticketing system
β”‚   β”‚   β”‚   β”œβ”€β”€ coupon.service.ts      # Coupon management
β”‚   β”‚   β”‚   β”œβ”€β”€ pricing.service.ts     # Dynamic pricing
β”‚   β”‚   β”‚   β”œβ”€β”€ admin.service.ts       # Admin operations
β”‚   β”‚   β”‚   β”œβ”€β”€ email.service.ts       # Email templates & sending
β”‚   β”‚   β”‚   β”œβ”€β”€ activityLog.service.ts # Audit logging
β”‚   β”‚   β”‚   └── docker.service.ts      # Container management (stub)
β”‚   β”‚   β”œβ”€β”€ utils/
β”‚   β”‚   β”‚   β”œβ”€β”€ jwt.ts                 # Token helpers
β”‚   β”‚   β”‚   β”œβ”€β”€ password.ts            # Hashing utilities
β”‚   β”‚   β”‚   β”œβ”€β”€ validators.ts          # Input validation
β”‚   β”‚   β”‚   β”œβ”€β”€ pagination.ts          # Pagination helper
β”‚   β”‚   β”‚   └── date.ts                # Date formatting
β”‚   β”‚   └── server.ts                  # Express app entry
β”‚   β”œβ”€β”€ .env.example
β”‚   β”œβ”€β”€ Dockerfile
β”‚   β”œβ”€β”€ package.json
β”‚   └── tsconfig.json
β”‚
β”œβ”€β”€ frontend/
β”‚   β”œβ”€β”€ app/
β”‚   β”‚   β”œβ”€β”€ (auth)/
β”‚   β”‚   β”‚   β”œβ”€β”€ login/page.tsx
β”‚   β”‚   β”‚   └── signup/page.tsx
β”‚   β”‚   β”œβ”€β”€ (dashboard)/
β”‚   β”‚   β”‚   └── dashboard/
β”‚   β”‚   β”‚       β”œβ”€β”€ page.tsx           # User dashboard
β”‚   β”‚   β”‚       β”œβ”€β”€ billing/page.tsx
β”‚   β”‚   β”‚       β”œβ”€β”€ settings/page.tsx
β”‚   β”‚   β”‚       β”œβ”€β”€ support/page.tsx
β”‚   β”‚   β”‚       └── layout.tsx
β”‚   β”‚   β”œβ”€β”€ admin/
β”‚   β”‚   β”‚   β”œβ”€β”€ page.tsx               # Admin dashboard
β”‚   β”‚   β”‚   β”œβ”€β”€ layout.tsx             # Admin layout with sidebar
β”‚   β”‚   β”‚   β”œβ”€β”€ users/page.tsx         # User management
β”‚   β”‚   β”‚   β”œβ”€β”€ subscriptions/page.tsx
β”‚   β”‚   β”‚   β”œβ”€β”€ payments/page.tsx
β”‚   β”‚   β”‚   β”œβ”€β”€ coupons/page.tsx
β”‚   β”‚   β”‚   β”œβ”€β”€ pricing/page.tsx
β”‚   β”‚   β”‚   β”œβ”€β”€ tickets/page.tsx
β”‚   β”‚   β”‚   β”œβ”€β”€ activity/page.tsx
β”‚   β”‚   β”‚   └── settings/page.tsx
β”‚   β”‚   β”œβ”€β”€ checkout/page.tsx
β”‚   β”‚   β”œβ”€β”€ pricing/page.tsx
β”‚   β”‚   β”œβ”€β”€ forgot-password/page.tsx
β”‚   β”‚   β”œβ”€β”€ reset-password/page.tsx
β”‚   β”‚   β”œβ”€β”€ verify-email/page.tsx
β”‚   β”‚   β”œβ”€β”€ layout.tsx                 # Root layout
β”‚   β”‚   β”œβ”€β”€ page.tsx                   # Landing page
β”‚   β”‚   └── globals.css
β”‚   β”œβ”€β”€ components/
β”‚   β”‚   β”œβ”€β”€ ui/                        # Shadcn components
β”‚   β”‚   β”‚   β”œβ”€β”€ button.tsx
β”‚   β”‚   β”‚   β”œβ”€β”€ card.tsx
β”‚   β”‚   β”‚   β”œβ”€β”€ input.tsx
β”‚   β”‚   β”‚   β”œβ”€β”€ table.tsx
β”‚   β”‚   β”‚   β”œβ”€β”€ dialog.tsx
β”‚   β”‚   β”‚   └── ...
β”‚   β”‚   β”œβ”€β”€ Pagination.tsx             # Reusable pagination
β”‚   β”‚   β”œβ”€β”€ Navbar.tsx
β”‚   β”‚   β”œβ”€β”€ Footer.tsx
β”‚   β”‚   └── ...
β”‚   β”œβ”€β”€ lib/
β”‚   β”‚   β”œβ”€β”€ api.ts                     # API client
β”‚   β”‚   β”œβ”€β”€ auth.ts                    # Auth context
β”‚   β”‚   └── utils.ts                   # Utility functions
β”‚   β”œβ”€β”€ .env.example
β”‚   β”œβ”€β”€ Dockerfile
β”‚   β”œβ”€β”€ package.json
β”‚   β”œβ”€β”€ tailwind.config.js
β”‚   └── tsconfig.json
β”‚
β”œβ”€β”€ docker/
β”‚   └── docker-compose.dev.yml
β”‚
β”œβ”€β”€ scripts/
β”‚   β”œβ”€β”€ setup-dev.ps1                  # Windows dev setup
β”‚   └── setup-dev.sh                   # Linux/Mac dev setup
β”‚
β”œβ”€β”€ .gitignore
└── README.md

πŸ—„οΈ Database Schema

Core Models

User

model User {
  id                String    @id @default(uuid())
  email             String    @unique
  password          String    // bcrypt hashed
  fullName          String
  phone             String?
  role              String    @default("user")  // user, admin, super_admin, support_agent
  status            String    @default("active") // active, suspended, deleted
  emailVerified     Boolean   @default(false)
  instanceUrl       String?   // n8n instance URL
  containerId       String?   // Docker container ID
  // ... timestamps and relations
}

Subscription

model Subscription {
  id                    String   @id @default(uuid())
  userId                String
  planType              String   // monthly, yearly
  status                String   // active, paused, cancelled, expired, payment_failed, suspended
  amount                Float
  currency              String   @default("EGP")
  currentPeriodStart    DateTime
  currentPeriodEnd      DateTime
  nextBillingDate       DateTime?
  pausedAt              DateTime?
  cancelledAt           DateTime?
  creditBalance         Float    @default(0)  // For proration
  // ... relations
}

Payment

model Payment {
  id                    String    @id @default(uuid())
  subscriptionId        String
  userId                String
  gatewayTransactionId  String?
  paymentGateway        String    // paymob
  amount                Float
  currency              String    @default("EGP")
  status                String    // success, failed, pending, refunded
  // ... relations
}

Coupon

model Coupon {
  id                String    @id @default(uuid())
  code              String    @unique
  discountType      String    // percentage, fixed
  discountValue     Float
  maxUses           Int?      // null = unlimited
  usedCount         Int       @default(0)
  validFrom         DateTime
  validUntil        DateTime?
  isActive          Boolean   @default(true)
  applicablePlans   String?   // JSON: ["monthly", "yearly"]
  minOrderAmount    Float?
}

PricingConfig

model PricingConfig {
  id              String   @id @default(uuid())
  planType        String   @unique  // monthly, yearly
  price           Float
  currency        String   @default("EGP")
  displayName     String
  description     String?
  features        String   @default("[]")  // JSON array
  isActive        Boolean  @default(true)
}

SupportTicket & SupportMessage

  • Full ticketing system with message threading
  • Category: billing, technical, refund, other
  • Priority: low, normal, high, urgent
  • Status workflow with SLA tracking

Other Models

  • RefundRequest - Refund workflow
  • ActivityLog - Audit trail
  • EmailQueue - Reliable email delivery
  • WebhookLog - Payment webhook debugging
  • SystemSetting - Admin configuration
  • CouponUsage - Track coupon redemptions

πŸ”Œ API Endpoints

Authentication

Method Endpoint Description
POST /api/auth/signup Register new user
POST /api/auth/login User login
POST /api/auth/logout Logout (invalidate token)
POST /api/auth/refresh Refresh JWT token
POST /api/auth/forgot-password Request password reset
POST /api/auth/reset-password Reset password with token
GET /api/auth/verify-email/:token Verify email address

User

Method Endpoint Description
GET /api/user/profile Get current user profile
PUT /api/user/profile Update profile
PUT /api/user/password Change password
PUT /api/user/email-preferences Update email settings

Subscription

Method Endpoint Description
GET /api/subscription Get user's subscription
POST /api/subscription/create Create new subscription
POST /api/subscription/pause Pause subscription
POST /api/subscription/resume Resume subscription
POST /api/subscription/cancel Cancel subscription
POST /api/subscription/upgrade Upgrade to annual

Payments

Method Endpoint Description
GET /api/payments List user's payments
GET /api/payments/:id Get payment details
GET /api/payments/:id/invoice Download invoice
POST /api/payments/checkout Initiate payment

Coupons

Method Endpoint Description
POST /api/coupons/validate Validate a coupon code
POST /api/coupons/apply Apply coupon to order

Support

Method Endpoint Description
GET /api/support/tickets List user's tickets
POST /api/support/tickets Create new ticket
GET /api/support/tickets/:id Get ticket details
POST /api/support/tickets/:id/messages Add message
PUT /api/support/tickets/:id/close Close ticket

Pricing

Method Endpoint Description
GET /api/pricing Get all pricing plans
GET /api/pricing/:planType Get specific plan

Webhooks (Paymob)

Method Endpoint Description
POST /api/webhooks/paymob Payment success/failure
POST /api/webhooks/paymob/refund Refund completed

Admin Routes (require admin role)

Method Endpoint Description
GET /api/admin/dashboard Dashboard metrics
GET /api/admin/users List all users (paginated)
GET /api/admin/users/:id Get user details
PUT /api/admin/users/:id Update user
PUT /api/admin/users/:id/suspend Suspend user
GET /api/admin/subscriptions List all subscriptions
GET /api/admin/payments List all payments
GET /api/admin/coupons List all coupons
POST /api/admin/coupons Create coupon
PUT /api/admin/coupons/:id Update coupon
DELETE /api/admin/coupons/:id Delete coupon
GET /api/admin/pricing Get pricing config
PUT /api/admin/pricing/:planType Update pricing
GET /api/admin/tickets List all tickets
PUT /api/admin/tickets/:id/assign Assign ticket
GET /api/admin/activity Activity logs
GET /api/admin/refunds Refund requests
PUT /api/admin/refunds/:id Process refund

πŸ’Ό Business Logic

Pricing Plans

Plan Price Billing Savings
Monthly 400 EGP Recurring -
Annual 3,800 EGP Upfront ~20%

Subscription Lifecycle

New User β†’ Signup β†’ Select Plan β†’ Payment
    ↓
Subscription Active β†’ n8n Instance Created
    ↓
[Payment Due] β†’ Payment Success β†’ Renewal
    ↓           ↓
    ↓       Payment Failed β†’ Grace Period (7 days)
    ↓           ↓
    ↓       Retry Days 3, 5, 7
    ↓           ↓
    ↓       Still Failed β†’ Suspended
    ↓
[User Action] β†’ Pause (max 30 days) β†’ Resume
    ↓
[User Action] β†’ Cancel β†’ Access until period end β†’ Expired

Refund Policy

  • 7-day money-back guarantee on first payment
  • Full refund only (no partial refunds)
  • One refund per customer lifetime
  • Refund processed back to original payment method

Grace Period

  • 7 days for failed payments
  • Automatic retry on days 3, 5, 7
  • Email notifications at each retry
  • Suspension after 7 days if still failed

πŸ”§ Admin Panel Features

Dashboard (/admin)

  • Active subscriptions count
  • Monthly revenue (MRR)
  • New signups (today/week/month)
  • Active users
  • Open support tickets
  • Recent activity feed
  • Revenue chart

User Management (/admin/users)

  • List all users with pagination
  • Search by email/name
  • Filter by status/role
  • View user details
  • Edit user information
  • Suspend/reactivate users

Subscription Management (/admin/subscriptions)

  • List all subscriptions with pagination
  • Filter by status/plan type
  • View subscription details
  • Manual status changes

Payment History (/admin/payments)

  • List all payments with pagination
  • Filter by status/gateway
  • View payment details
  • Download invoices

Coupon Management (/admin/coupons)

  • Create new coupons
  • Edit existing coupons
  • Set discount type (percentage/fixed)
  • Set validity period
  • Set usage limits
  • Enable/disable coupons
  • View usage statistics

Pricing Configuration (/admin/pricing)

  • Edit plan prices
  • Update plan features (JSON array)
  • Toggle plan availability

Support Tickets (/admin/tickets)

  • List all tickets with pagination
  • Filter by status/priority/category
  • Assign to admin
  • Reply to tickets
  • Close/resolve tickets

Activity Logs (/admin/activity)

  • Audit trail of all actions
  • Filter by user/action type
  • IP address tracking

πŸš€ Next Phase: n8n Instance Provisioning

Architecture Decision: Cluster Model (Cost-Optimized)

After analysis, we decided on a Docker Swarm cluster architecture using Hetzner Cloud ARM64 servers for maximum cost efficiency.

Architecture Overview

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                            INTERNET                                         β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                   β”‚
                                   β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                    LOAD BALANCER NODE (CAX11 - €3.79/mo)                   β”‚
β”‚                         Traefik + SSL Termination                           β”‚
β”‚                    Routes: customer1.n8n.yoursite.com                       β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                   β”‚
         β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
         β”‚                         β”‚                             β”‚
         β–Ό                         β–Ό                             β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  WORKER NODE #1  β”‚   β”‚  WORKER NODE #2  β”‚   β”‚      SERVICES NODE           β”‚
β”‚   CAX31 ARM64    β”‚   β”‚   CAX31 ARM64    β”‚   β”‚       CAX21 ARM64            β”‚
β”‚ 8 vCPU, 16GB RAM β”‚   β”‚ 8 vCPU, 16GB RAM β”‚   β”‚     4 vCPU, 8GB RAM          β”‚
β”‚    €12.49/mo     β”‚   β”‚    €12.49/mo     β”‚   β”‚        €6.49/mo              β”‚
β”‚ [8 n8n instances]β”‚   β”‚ [8 n8n instances]β”‚   β”‚  PostgreSQL + Redis          β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

n8n Resource Requirements (per instance)

  • RAM: 2GB minimum per instance
  • CPU: 1 core minimum
  • Storage: Each instance gets its own PostgreSQL database

Scaling Cost Table

Customers Worker Nodes Monthly Cost Cost/Customer
1-8 1Γ— CAX31 €22.77 €2.85
9-16 2Γ— CAX31 €35.26 €2.20
17-24 3Γ— CAX31 €53.75 €2.24
25-40 5Γ— CAX31 €81.43 €2.04

Provisioning Workflow

Customer Subscribes β†’ Payment Confirmed
         β”‚
         β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚      PROVISIONING SERVICE           β”‚
β”‚                                     β”‚
β”‚  1. Check cluster capacity          β”‚
β”‚  2. If full: Add worker via Hetzner β”‚
β”‚  3. Create PostgreSQL database      β”‚
β”‚  4. Deploy n8n container to swarm   β”‚
β”‚  5. Configure DNS (Cloudflare)      β”‚
β”‚  6. Wait for health check           β”‚
β”‚  7. Email customer with credentials β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Required New Database Models

model N8nInstance {
  id               String   @id @default(uuid())
  userId           String   @unique
  subdomain        String   @unique  // customer.n8n.yoursite.com
  status           InstanceStatus @default(PENDING)
  allocatedRam     Int      @default(2048)  // MB
  allocatedCpu     Int      @default(1)
  workerId         String?
  createdAt        DateTime @default(now())
  suspendedAt      DateTime?
  deletedAt        DateTime?
}

model ClusterNode {
  id           String   @id @default(uuid())
  ip           String
  type         String   // manager, worker, services
  hetznerId    String
  capacity     Int      @default(8)  // max n8n instances
  currentLoad  Int      @default(0)
  status       String   @default("active")
}

enum InstanceStatus {
  PENDING
  PROVISIONING
  ACTIVE
  SUSPENDED
  DELETING
  DELETED
  ERROR
}

Required New Services

// New services to implement:
β”œβ”€β”€ services/
β”‚   β”œβ”€β”€ cluster.service.ts       // Manage cluster nodes
β”‚   β”œβ”€β”€ hetzner.service.ts       // Hetzner Cloud API
β”‚   β”œβ”€β”€ provisioning.service.ts  // n8n instance lifecycle
β”‚   └── dns.service.ts           // Cloudflare DNS management

Integration Points

When subscription events occur:

Event Action
subscription.created + payment.success Provision n8n instance
payment.failed (after grace period) Suspend instance (scale to 0)
payment.success (after failed) Resume instance (scale to 1)
subscription.cancelled Suspend immediately, schedule deletion in 30 days

πŸ”§ Setup Instructions

Prerequisites

  • Node.js 20+
  • PostgreSQL 15+ (or SQLite for dev)
  • npm or yarn
  • Git

Backend Setup

# Clone repository
git clone <repository-url>
cd n8n-intag-store/backend

# Install dependencies
npm install

# Create environment file
cp .env.example .env

# Edit .env with your configuration
# Required: DATABASE_URL, JWT_SECRET

# Run database migrations
npx prisma migrate dev

# Seed initial data (optional)
npx prisma db seed

# Start development server
npm run dev
# Server runs on http://localhost:3001

Frontend Setup

cd n8n-intag-store/frontend

# Install dependencies
npm install

# Create environment file
cp .env.example .env.local

# Edit .env.local
# Required: NEXT_PUBLIC_API_URL=http://localhost:3001

# Start development server
npm run dev
# App runs on http://localhost:3000

Using Docker (Development)

cd n8n-intag-store

# Start all services
docker-compose -f docker/docker-compose.dev.yml up -d

# View logs
docker-compose -f docker/docker-compose.dev.yml logs -f

πŸ” Environment Variables

Backend (.env)

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/n8n_saas?schema=public"
# For SQLite (dev): DATABASE_URL="file:./dev.db"

# JWT Authentication
JWT_SECRET="your-secure-random-string-min-32-chars"
JWT_EXPIRES_IN="1d"

# Server
PORT=3001
NODE_ENV=development

# Payment Gateway (Paymob)
PAYMOB_API_KEY="your-paymob-api-key"
PAYMOB_INTEGRATION_ID="your-integration-id"
PAYMOB_HMAC_SECRET="your-hmac-secret"
PAYMOB_IFRAME_ID="your-iframe-id"

# Email (SendGrid)
SENDGRID_API_KEY="SG.xxxxxxx"
SENDGRID_FROM_EMAIL="noreply@yoursite.com"
SENDGRID_FROM_NAME="n8n SaaS"

# Frontend URL (for emails/redirects)
FRONTEND_URL="http://localhost:3000"

# Admin Credentials (for seeding)
ADMIN_EMAIL="admin@yoursite.com"
ADMIN_PASSWORD="secure-admin-password"

# Future: Hetzner Cloud
HETZNER_API_TOKEN=""

# Future: Cloudflare
CLOUDFLARE_API_TOKEN=""
CLOUDFLARE_ZONE_ID=""

Frontend (.env.local)

NEXT_PUBLIC_API_URL="http://localhost:3001"
NEXT_PUBLIC_APP_NAME="n8n SaaS"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

πŸ”’ Security Features

  • HTTPS enforced in production
  • Passwords hashed with bcrypt (12 rounds)
  • JWT tokens with 24-hour expiration
  • Input validation on all endpoints (Zod)
  • SQL injection prevention via Prisma ORM
  • XSS prevention with input sanitization
  • CSRF protection on state-changing endpoints
  • Rate limiting on auth endpoints
  • Helmet.js for secure HTTP headers
  • CORS configured for allowed origins

πŸ“ Development Notes

Running Tests

cd backend
npm run test

cd frontend
npm run test

Database Migrations

# Create new migration
npx prisma migrate dev --name migration_name

# Apply migrations
npx prisma migrate deploy

# Reset database
npx prisma migrate reset

Code Style

  • ESLint + Prettier configured
  • Run npm run lint to check
  • Run npm run format to auto-fix

🀝 Contributing

This is a private project. Contact the owner for access.

πŸ“„ License

Private - All Rights Reserved


Built with ❀️ for Egyptian businesses

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors