Skip to content

nikkkhil2935/FlowReachAI

BranchesTags
 
 

Repository files navigation

FlowReach AI

🚀 FlowReach AI

AI-Powered Multi-Channel Lead Outreach & Workflow Automation Platform
Build visual workflows, generate personalized AI messages, automate outreach across Email, Discord, Telegram, Slack & SMS — all in one platform.

React Vite Express Supabase Groq Socket.io Tailwind Complete

22 Nodes 51+ APIs 11 Tables 5 Channels

📋 Table of Contents

🚀 Overview

FlowReach AI is a full-stack, production-ready lead outreach workflow automation platform inspired by tools like n8n, Make.com, and Instantly.ai. It combines a powerful visual workflow builder with AI-driven personalization to automate multi-channel outreach campaigns at scale.

What You Can Do

Capability Description
Import Leads Upload CSV/Excel files with smart column mapping and validation
Build Visual Workflows Drag-and-drop 22 node types on an n8n-style canvas
Generate AI Messages Create personalized outreach using Groq LLaMA 3.3 70B
Multi-Channel Outreach Email (Gmail SMTP), Discord (Webhook), Telegram (Bot API), Slack (Webhook), SMS (Twilio)
Bulk Send Send AI-generated messages to selected leads across any channel
Execute Workflows Run automated sequences on leads with real-time monitoring
Track Messages Full message history with status tracking across all channels
Monitor Everything Live dashboard with charts, Kanban board, stats, and execution feeds
Stay Safe Blacklist management, daily send limits, safety scoring
Chat with AI Natural language AI assistant for content & workflow creation
Manage Channels Connect and configure WhatsApp, Telegram, Discord, Slack accounts
Manage Credentials Securely store API keys for 8+ providers
Manage Profile Update personal info, upload avatar photo, view account details

✨ Key Features

� Authentication & Route Protection

  • Supabase Auth Integration: Full email/password authentication powered by Supabase
  • Sign In Page: Clean split-screen design with credentials form on the right and branding panel on the left
  • Sign Up Flow:
    • User signs up with email and password via supabase.auth.signUp()
    • If email confirmation is required (no auto-session), user is shown a success message: "Your account has been created. Please check your email and verify your address before logging in."
    • Email is pre-filled on the sign-in form after successful signup
    • No auto-redirect until the email is verified and a real session exists
  • Sign In Flow:
    • User signs in with supabase.auth.signInWithPassword()
    • On success, redirects to /dashboard
    • On error, displays the error message inline below the form
  • Google OAuth: "Continue with Google" button using supabase.auth.signInWithOAuth({ provider: 'google' })
    • Requires Google OAuth credentials configured in Supabase Dashboard → Authentication → Providers → Google
    • Requires redirect URI https://<your-project>.supabase.co/auth/v1/callback added in Google Cloud Console
  • Route Protection:
    • AppLayout checks for an active Supabase session via supabase.auth.getSession()
    • If no session exists, user is redirected to / (sign-in page)
    • Listens to onAuthStateChange for real-time session updates (login/logout)
    • Shows a loading spinner while session is being verified
  • Auto-Redirect: If a user visits / while already authenticated, they are automatically redirected to /dashboard
  • Session Persistence: Supabase handles session tokens and refresh automatically

�📊 Dashboard & Analytics

  • 4 real-time stat cards: Total Leads, Total Workflows, Active Workflows, Total Executions
  • Bar Chart: Leads distribution by status (new, contacted, replied, converted, bounced)
  • Line Chart: Messages sent over the last 7 days with daily breakdown
  • Kanban Board: 4 columns (Backlog, Active, Review, Done) with draggable cards
  • Recent Leads Table: Latest imported leads with timestamps and status badges
  • Auto-refresh: Dashboard data refreshes every 10 seconds automatically
  • Manual Refresh: One-click refresh button for instant data reload
  • Loading Skeletons: Smooth skeleton animations during data fetch

👥 Lead Management

  • 3-Step CSV/Excel Import Wizard:
    • Step 1: Drag-and-drop file upload (supports .csv, .xlsx, .xls)
    • Step 2: Smart column mapping — required fields (name, email) + optional (company, title, source)
    • Step 3: Preview first 10 rows, confirm and bulk import
  • Searchable Leads Table: Real-time search across name, email, company
  • Pagination: 50 leads per page with page navigation
  • Status Filter: Filter by new, contacted, replied, converted, bounced, unsubscribed
  • Status Badges: Color-coded badges (blue=new, amber=contacted, green=replied, emerald=converted, red=bounced)
  • Inline Actions: Edit and delete individual leads
  • Bulk Import: Handles up to 5,000 leads per upload
  • Email Validation: Regex validation on import to catch malformed emails
  • Download Sample CSV: One-click sample CSV download for easy onboarding

🔄 Visual Workflow Builder (n8n-Style)

  • 19 Node Types across 6 categories (see Workflow Nodes)
  • Drag-and-Drop Canvas: Powered by @xyflow/react (React Flow)
  • Categorized Node Palette: Searchable sidebar with 6 categories:
    • Triggers, AI & ML, Communication, Logic & Flow, Integrations, Flow
  • Node Configuration Panel: Right-side panel with per-node-type forms
  • Edge Connections: Visual connections between nodes with labeled condition branches (Yes/No)
  • MiniMap: Overview map for navigating large workflows
  • Controls: Zoom in/out, fit view, lock/unlock canvas
  • Full CRUD: Create, read, update, delete workflows
  • Duplicate Workflows: Clone existing workflows with one click
  • 5 Seed Templates: Pre-built workflows for common outreach scenarios
  • Auto-Save: Workflows saved to database on save button click
  • Execute from Builder: Run workflow directly from the builder with lead selection modal

🤖 AI Message Generation

  • Groq SDK Integration: LLaMA 3.3 70B Versatile model for high-quality content
  • 4 AI Provider Support: Groq, OpenAI, Anthropic, Google AI (via credentials system)
  • Template Variables: Dynamic interpolation — {{name}}, {{email}}, {{company}}, {{title}}
  • 9 Tone Options: Professional, Friendly, Casual, Formal, Persuasive, Urgent, Empathetic, Humorous, Inspirational
  • 8 Message Types: Cold outreach, Follow-up, Introduction, Meeting request, Thank you, Proposal, Newsletter, Custom
  • Personalization Fields: Sender name, company name, industry, pain points, CTA, signature, language
  • AI Preview Modal: Preview personalized messages for up to 5 leads before sending
  • Send & Bulk Send: Send individual or bulk messages across any channel directly from the AI interface
  • Mock Fallback: When no API key is configured, AI features gracefully fall back to realistic mock data
  • Copy to Clipboard: One-click copy for all generated content
  • Regenerate: Re-generate messages with different parameters

📡 Multi-Channel Outreach

FlowReach supports 5 communication channels, each with dedicated workflow nodes and backend handlers:

Channel Protocol Config Required Workflow Node
Email Gmail SMTP / Ethereal (test) SMTP credentials or env vars EmailNode
Discord Webhook API DISCORD_WEBHOOK_URL env var or credential DiscordNode
Telegram Bot API (sendMessage) TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID TelegramNode
Slack Incoming Webhook SLACK_WEBHOOK_URL env var or credential SlackNode
SMS Twilio REST API Twilio Account SID + Auth Token SmsNode

Channel Features:

  • Channel Accounts Page: Connect, configure, and manage channel accounts with status indicators
  • Inbound Webhooks: Receive inbound messages from WhatsApp, Telegram, Discord, and Slack via dedicated webhook endpoints
  • Credential Linking: Link stored credentials to workflow nodes for secure channel configuration
  • Fallback Handling: Each channel handler gracefully handles missing credentials with informative error messages

💬 AI Chat & Workflow Creator

  • Interactive Chat Interface: Full conversational AI with message history
  • 6 Quick Prompt Templates: Pre-written prompts for common tasks
  • Message Generator Tab: Form-based AI message creation with lead picker, channel selector, and full personalization controls
  • Bulk Send: Select multiple leads and send AI-generated messages in bulk across any channel
  • AI Workflow Creator: Describe a workflow in natural language → AI generates the node graph
  • Tab-Based Interface: Switch between Chat, Message Generator, and Workflow Creator

⚡ Workflow Execution Engine

  • Graph Traversal: Walks through workflow from Start to End node
  • 22 Node Type Handlers: Each node type has dedicated execution logic
  • Multi-Channel Sends: Execute Email, Discord, Telegram, Slack, and SMS sends within workflows
  • Real-time Streaming: Socket.io event emission during execution for live monitoring
  • Context Preservation: Execution context (generated messages, AI responses, classifications) flows between nodes
  • Error Resilience: Per-node try/catch — one failing node doesn't crash the entire workflow
  • Blacklist Enforcement: Email sends automatically blocked for blacklisted addresses/domains
  • Rate Limiting: Daily send limit enforcement (default 50/day)
  • Execution Logs: Detailed timestamped logs (info, warn, error) stored per execution
  • Live Feed: Real-time execution log streaming in the Executions page
  • Execution History: Full history with expandable log details

🔌 Real-time Architecture

  • Socket.io: Bidirectional WebSocket communication between client and server
  • Live Events:
    • execution:log — Real-time log entries during workflow execution
    • execution:status — Status updates (running → completed/failed)
  • Connection Indicator: Visual system online/offline indicator in the UI
  • Auto-Reconnect: Automatic reconnection on connection loss
  • Manual Reconnect: Button to force reconnection

� Message Tracking

  • Unified Message History: Track all messages sent across every channel in one view
  • Status Tracking: draft, sent, delivered, opened, failed, blocked, rate_limited, ai_generated
  • Channel Filtering: Filter messages by channel type (email, sms, whatsapp, telegram, discord, slack)
  • Type Filtering: Filter by message type (cold outreach, follow-up, etc.)
  • Search: Search across lead name/email and message content
  • Pagination: Paginated message list with datetime sorting
  • Expandable Details: Click to view full message body, subject, and metadata
  • Color-Coded Badges: Status and channel badges for quick visual scanning

�🛡️ Safety & Compliance Controls

  • Email Blacklist: CRUD management for blocked emails and domains
    • Emails are checked against the blacklist before every send
    • Blocked sends are logged with "blocked" status
  • Daily Send Limit: Configurable maximum emails per day (default: 50)
    • Counter tracks sends per calendar day
    • Emails exceeding the limit are logged as "rate_limited"
    • Manual reset button available in Settings
  • Safety Score: Real-time 100-point safety gauge with 7 checks (see Safety Score System)
  • Send History: 7-day rolling history of daily send counts

🔑 Credentials & API Key Management

  • 8 Provider Types:
    • AI: Groq, OpenAI, Anthropic, Google AI
    • Communication: SMTP (email), Slack, Twilio (SMS)
    • Generic: API Key (for any custom integration)
  • Secure Storage: Credentials stored as JSONB in Supabase
  • Masked Display: API keys shown masked in the UI (only backend has full access)
  • Credential Linking: Link credentials to workflow nodes (e.g., SMTP credential → Email node)
  • Full CRUD: Create, view, update, delete credentials

👤 Profile Management

  • Personal Info: Update full name, email, phone, company, job title, and bio
  • Avatar Upload: Upload a profile photo (up to 5MB) stored in Supabase Storage with instant preview
  • Default Initials Avatar: Gradient circle with computed initials when no photo is uploaded
  • Timezone Selection: Choose from 14 timezone options
  • Account Info Card: View current plan, member since date, and last updated timestamp
  • Quick Access: Click avatar in header or profile area in sidebar to navigate to Profile page
  • Keyboard Shortcut: Press P to navigate to Profile from anywhere

⌨️ Keyboard Shortcuts

Shortcut Action
D Navigate to Dashboard
L Navigate to Leads
W Navigate to Workflows
E Navigate to Executions
S Navigate to Settings
A Navigate to AI Chat
P Navigate to Profile
? Show keyboard shortcuts help modal
Esc Close any open modal

🛠 Complete Tech Stack

Frontend

Package Version Purpose
react 19.1 UI framework
react-dom 19.1 React DOM renderer
vite 6.3 Build tool & dev server
tailwindcss 4.2 Utility-first CSS (light theme, indigo #6366f1 primary, zinc neutrals)
@tailwindcss/vite 4.2 Tailwind CSS Vite plugin
@xyflow/react 12.10 Visual workflow canvas (React Flow)
recharts 2.15 Charts for dashboard (Bar, Line)
xlsx 0.18 CSV/Excel parsing (SheetJS)
socket.io-client 4.8 Real-time WebSocket client
axios 1.13 HTTP client for API calls
react-router-dom 7.13 Client-side routing
lucide-react 0.577 Icon library (200+ icons used)
react-hot-toast 2.6 Toast notifications
prop-types 15.8 Runtime prop type validation
@radix-ui/react-* Various Accessible UI primitives (dialog, dropdown, tooltip, etc.)
@supabase/supabase-js 2.98 Supabase client (frontend)
clsx 2.1 Conditional class names
tailwind-merge 3.5 Tailwind class deduplication

Backend

Package Version Purpose
express 4.21 HTTP server framework
@supabase/supabase-js 2.98 Supabase PostgreSQL client
groq-sdk 0.8 Groq AI (LLaMA 3.3 70B)
socket.io 4.8 Real-time WebSocket server
nodemailer 6.9 Email sending (SMTP + Ethereal test)
cors 2.8 Cross-origin resource sharing
dotenv 16.4 Environment variable loading

Dev Tools

Package Version Purpose
concurrently 8.2 Run frontend + backend simultaneously
eslint 9.25 JavaScript/JSX linting

📁 Project Structure

flowreach-ai/
├── package.json                     # Root — concurrently script, install:all
├── render.yaml                      # Render.com deployment configuration
├── .gitignore                       # Git ignore rules
│
├── backend/
│   ├── package.json                 # Backend dependencies (type: module)
│   ├── .env.example                 # Environment variable template
│   ├── index.js                     # Express server + Socket.io + CORS + static serving + route mounting
│   ├── db.js                        # Supabase client initialization
│   ├── ai.js                        # Groq SDK integration + multi-channel handlers + mock fallback
│   ├── executor.js                  # WorkflowExecutor class (22 node handlers, multi-channel)
│   ├── seed.js                      # Demo data generator (50 leads, 12 executions, etc.)
│   ├── migrations/
│   │   └── 001_channels.sql         # Channel accounts + inbound messages table schema
│   └── routes/
│       ├── leads.js                 # GET/POST/PUT/DELETE /api/leads + bulk import
│       ├── workflows.js             # GET/POST/PUT/DELETE /api/workflows + seed templates
│       ├── executions.js            # POST /api/executions/run + GET /api/executions
│       ├── stats.js                 # GET /api/stats/overview
│       ├── ai.js                    # AI generate, preview, chat, create-workflow, send, bulk-send
│       ├── messages.js              # GET /api/messages (history + filtering)
│       ├── channels.js              # Channel account CRUD + inbound webhooks (WhatsApp/Telegram/Discord/Slack)
│       ├── settings.js              # Blacklist CRUD + daily stats + safety score
│       ├── credentials.js           # GET/POST/PUT/DELETE /api/credentials
│       └── profile.js               # GET/PUT /api/profile + POST /api/profile/avatar
│
├── frontend/
│   ├── package.json                 # Frontend dependencies
│   ├── .env.example                 # VITE_API_URL template
│   ├── .env.production              # Production env (empty VITE_API_URL for same-origin)
│   ├── vite.config.js               # Vite config with API proxy to :3001
│   ├── index.html                   # HTML entry point (FlowReach AI title + rocket favicon)
│   ├── components.json              # shadcn/ui component config
│   ├── jsconfig.json                # Path aliases (@/)
│   ├── eslint.config.js             # ESLint configuration
│   │
│   └── src/
│       ├── main.jsx                 # App entry — BrowserRouter + Toaster provider
│       ├── App.jsx                  # Route definitions (21 routes)
│       ├── index.css                # Tailwind CSS imports + custom properties
│       ├── supabaseClient.js        # Supabase client (frontend)
│       │
│       ├── lib/
│       │   ├── supabaseService.js   # 30+ functions — all API/DB operations
│       │   └── utils.js             # cn() helper (clsx + tailwind-merge)
│       │
│       ├── hooks/
│       │   └── use-mobile.js        # Responsive breakpoint hook
│       │
│       ├── components/
│       │   ├── AppLayout.jsx        # Main layout — sidebar + outlet + keyboard shortcuts
│       │   ├── Header.jsx           # Top bar — Socket.io status, notifications
│       │   ├── Sidebar.jsx          # Navigation — 9 links in 4 sections, brand logo, profile
│       │   ├── LeadImport.jsx       # 3-step CSV/Excel import wizard
│       │   ├── LeadsTable.jsx       # Searchable, paginated lead table
│       │   ├── NodeConfigPanel.jsx  # Config forms for all 22 node types
│       │   ├── AIPreviewModal.jsx   # AI message preview modal (up to 5 leads)
│       │   │   # AppLayout includes Supabase session guard (redirects to / if unauthenticated)
│       │   │
│       │   ├── nodes/               # 22 visual workflow node components
│       │   │   ├── StartNode.jsx          # Manual trigger entry point
│       │   │   ├── ScheduleNode.jsx       # Cron/interval trigger
│       │   │   ├── WebhookNode.jsx        # HTTP webhook trigger
│       │   │   ├── AIGenerateNode.jsx     # AI content generation
│       │   │   ├── AIAgentNode.jsx        # Multi-provider AI agent
│       │   │   ├── SummarizerNode.jsx     # Text summarization
│       │   │   ├── ClassifierNode.jsx     # Data classification
│       │   │   ├── EmailNode.jsx          # SMTP email send
│       │   │   ├── SmsNode.jsx            # Twilio SMS
│       │   │   ├── SlackNode.jsx          # Slack message (webhook)
│       │   │   ├── DiscordNode.jsx        # Discord message (webhook)
│       │   │   ├── TelegramNode.jsx       # Telegram message (Bot API)
│       │   │   ├── WhatsAppNode.jsx       # WhatsApp message (Meta Cloud API)
│       │   │   ├── ConditionNode.jsx      # If/else branching (Yes/No handles)
│       │   │   ├── FilterNode.jsx         # Lead filtering
│       │   │   ├── DelayNode.jsx          # Time delay
│       │   │   ├── SplitNode.jsx          # A/B split routing
│       │   │   ├── MergeNode.jsx          # Branch merging
│       │   │   ├── HttpRequestNode.jsx    # External API calls
│       │   │   ├── CodeNode.jsx           # Custom JS/Python code
│       │   │   ├── UpdateLeadNode.jsx     # Lead status update
│       │   │   └── EndNode.jsx            # Terminal node
│       │   │
│       │   └── ui/                  # Reusable UI components (Radix-based)
│       │       ├── avatar.jsx, badge.jsx, breadcrumb.jsx, button.jsx
│       │       ├── card.jsx, chart.jsx, dropdown-menu.jsx, input.jsx
│       │       ├── progress.jsx, separator.jsx, sheet.jsx, sidebar.jsx
│       │       ├── skeleton.jsx, table.jsx, tabs.jsx, tooltip.jsx
│       │
│       └── pages/
│           ├── LandingPage.jsx      # Authentication page (Sign In / Sign Up / Google OAuth)
│           ├── Dashboard.jsx        # Stats cards + charts + Kanban board + recent leads
│           ├── Leads.jsx            # Lead table + CSV/Excel import (2 tabs)
│           ├── Workflows.jsx        # Workflow list with CRUD actions
│           ├── WorkflowBuilder.jsx  # Visual drag-drop node editor + palette
│           ├── Executions.jsx       # Live Feed + History tabs + execution runner
│           ├── Messages.jsx         # Message history + status tracking across all channels
│           ├── Channels.jsx         # Channel account CRUD (WhatsApp, Telegram, Discord, Slack)
│           ├── AIChat.jsx           # AI chat + message generator + bulk send + workflow creator
│           ├── Settings.jsx         # Safety Score gauge + Blacklist + API Keys
│           └── Profile.jsx          # Profile management — avatar upload, personal info, account card

🏁 Getting Started

Prerequisites

Requirement Minimum Version Notes
Node.js ≥ 20.x ES Modules required
npm ≥ 10.x Comes with Node.js
Supabase Free tier PostgreSQL database
Groq API Key Optional AI features fall back to mock data without it

Local Development

1. Clone the Repository

git clone https://github.com/atharva101010/COHERENCE-26_S8UL.git
cd COHERENCE-26_S8UL

2. Install All Dependencies

npm run install:all

This single command installs dependencies for root, frontend, and backend.

3. Set Up Supabase Database

  1. Create a free project at supabase.com
  2. Go to the SQL Editor in your Supabase dashboard
  3. Create the required tables: leads, workflows, executions, messages, blacklist, daily_send_counts, credentials, channel_accounts, inbound_messages
  4. For the channel tables schema, refer to backend/migrations/001_channels.sql

4. Configure Environment Variables

Create backend/.env:

# Supabase (REQUIRED)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# AI Provider (OPTIONAL — mock fallback if not set)
GROQ_API_KEY=gsk_your-groq-api-key

# Server
PORT=3001
FRONTEND_URL=http://localhost:5173

# Email — SMTP (OPTIONAL — uses Ethereal test email if not set)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
SMTP_FROM=noreply@yourcompany.com

# Outreach Safety
DAILY_SEND_LIMIT=50

# Discord (OPTIONAL)
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

# Telegram (OPTIONAL)
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_CHAT_ID=your-chat-id

# Slack (OPTIONAL)
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

# WhatsApp — Meta Cloud API (OPTIONAL)
WHATSAPP_ACCESS_TOKEN=your-token
WHATSAPP_PHONE_NUMBER_ID=your-phone-id
WHATSAPP_VERIFY_TOKEN=flowreach-verify

# Twilio — SMS (OPTIONAL)
TWILIO_ACCOUNT_SID=ACxxxxxxxx
TWILIO_AUTH_TOKEN=your-auth-token
TWILIO_WHATSAPP_NUMBER=whatsapp:+14155238886

Create frontend/.env (for local dev — usually not needed):

VITE_API_URL=http://localhost:3001

5. Seed Demo Data (Optional)

cd backend
npm run seed

This creates 50 realistic leads, 12 execution records, 7 days of send history, and 3 blacklist entries.

6. Start the Development Servers

npm run dev
Service URL Description
Frontend http://localhost:5173 React + Vite dev server
Backend http://localhost:3001 Express API + Socket.io

7. Verify Everything Works

# Check backend health
curl http://localhost:3001/health
# → {"status":"ok","timestamp":"..."}

Open http://localhost:5173 in your browser.

🚀 Deploying to Render

The project includes a render.yaml for one-click deployment to Render:

  1. Push your code to a Git repository
  2. Connect the repo to Render
  3. Render will use the render.yaml configuration:
    • Build: Installs frontend dependencies, builds frontend, installs backend dependencies
    • Start: Runs node index.js from the backend directory
    • Static Serving: Backend serves the built frontend from frontend/dist/
  4. Set the required environment variables in Render's dashboard:
    • SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY (required)
    • GROQ_API_KEY (optional — for AI features)
    • Channel credentials as needed (Discord, Telegram, Slack, etc.)
  5. The frontend uses VITE_API_URL="" in production, so API requests go to the same origin

🔐 Environment Variables

Variable Required Default Description
SUPABASE_URL ✅ Yes — Your Supabase project URL
SUPABASE_SERVICE_ROLE_KEY ✅ Yes — Supabase service role key (from Project Settings → API)
GROQ_API_KEY ❌ No — Groq API key for AI generation. Without it, AI features return realistic mock data
PORT ❌ No 3001 Backend Express server port
FRONTEND_URL ❌ No http://localhost:5173 CORS allowed origin for the frontend
SMTP_HOST ❌ No — SMTP server hostname (e.g., smtp.gmail.com)
SMTP_PORT ❌ No 587 SMTP port (587 for TLS, 465 for SSL)
SMTP_USER ❌ No — SMTP login username/email
SMTP_PASS ❌ No — SMTP login password (use app-specific passwords)
SMTP_FROM ❌ No — Default "From" email address
DAILY_SEND_LIMIT ❌ No 50 Maximum emails allowed per day
DISCORD_WEBHOOK_URL ❌ No — Discord channel webhook URL
TELEGRAM_BOT_TOKEN ❌ No — Telegram Bot API token (from @BotFather)
TELEGRAM_CHAT_ID ❌ No — Default Telegram chat ID for sends
SLACK_WEBHOOK_URL ❌ No — Slack incoming webhook URL
WHATSAPP_ACCESS_TOKEN ❌ No — Meta Cloud API access token for WhatsApp
WHATSAPP_PHONE_NUMBER_ID ❌ No — WhatsApp phone number ID
WHATSAPP_VERIFY_TOKEN ❌ No flowreach-verify Webhook verification token for WhatsApp
TWILIO_ACCOUNT_SID ❌ No — Twilio account SID for SMS
TWILIO_AUTH_TOKEN ❌ No — Twilio auth token
TWILIO_WHATSAPP_NUMBER ❌ No — Twilio WhatsApp sender number
VITE_API_URL ❌ No http://localhost:3001 Frontend API base URL (empty string in production for same-origin)

Note: If SMTP is not configured, the email node uses Ethereal Email — a free test email service that captures emails without sending them. Similarly, Discord, Telegram, and Slack nodes log informative messages when their respective credentials are missing.

🗄 Database Schema

11 tables in Supabase PostgreSQL:

Table Definitions

leads — Contact Records

Column Type Constraints Description
id BIGINT Primary Key, Auto Unique lead ID
name TEXT Not Null Full name
email TEXT Unique, Not Null Email address
company TEXT — Company name
title TEXT — Job title
status TEXT Default: 'new' Current status (see flow below)
source TEXT Default: 'manual' Import source: csv_import, manual, api
custom_fields JSONB Default: '{}' Arbitrary key-value data
created_at TIMESTAMP Default: now() Creation timestamp
updated_at TIMESTAMP Default: now() Last update timestamp

workflows — Workflow Definitions

Column Type Constraints Description
id BIGINT Primary Key, Auto Unique workflow ID
name TEXT Not Null Workflow name
description TEXT — Workflow description
nodes TEXT — JSON stringified array of React Flow nodes
edges TEXT — JSON stringified array of React Flow edges
is_active BOOLEAN Default: true Active/inactive toggle
created_at TIMESTAMP Default: now() Creation timestamp
updated_at TIMESTAMP Default: now() Last update timestamp

executions — Execution Records

Column Type Constraints Description
id BIGINT Primary Key, Auto Unique execution ID
workflow_id BIGINT Foreign Key → workflows.id Associated workflow
lead_id BIGINT Foreign Key → leads.id Target lead
status TEXT Default: 'pending' pending / running / completed / failed
logs TEXT — JSON array of log entries
current_node TEXT — Currently executing node ID
started_at TIMESTAMP — Execution start time
completed_at TIMESTAMP — Execution end time
created_at TIMESTAMP Default: now() Record creation time

messages — Sent Messages

Column Type Constraints Description
id BIGINT Primary Key, Auto Unique message ID
lead_id BIGINT Foreign Key → leads.id Target lead
execution_id BIGINT Foreign Key → executions.id Parent execution
type TEXT — email, sms, slack, discord, telegram, whatsapp, ai_generated
subject TEXT — Email subject line
body TEXT — Message content
status TEXT Default: 'draft' draft / sent / delivered / failed / blocked / rate_limited
sent_at TIMESTAMP — When message was sent
created_at TIMESTAMP Default: now() Record creation time

blacklist — Blocked Emails/Domains

Column Type Constraints Description
id BIGINT Primary Key, Auto Unique entry ID
email TEXT Unique, Not Null Blocked email or domain pattern
reason TEXT — Reason for blocking
created_at TIMESTAMP Default: now() When added

daily_send_counts — Rate Limiting

Column Type Constraints Description
id BIGINT Primary Key, Auto Unique entry ID
date DATE Unique, Not Null Calendar date
count INTEGER Default: 0 Number of emails sent on this date

credentials — API Keys & Secrets

Column Type Constraints Description
id BIGINT Primary Key, Auto Unique credential ID
name TEXT Not Null Credential display name
type TEXT Not Null Provider type (see list below)
config JSONB Not Null Provider-specific config (API keys, tokens, etc.)
updated_at TIMESTAMP Default: now() Last update time
created_at TIMESTAMP Default: now() Creation time

Credential Types: groq, openai, anthropic, google, smtp, slack, twilio, api_key

channel_accounts — Connected Channel Accounts

Column Type Constraints Description
id BIGINT Primary Key, Auto Unique account ID
channel TEXT Not Null Channel type: whatsapp, telegram, discord, slack
account_name TEXT Not Null Display name for the account
config JSONB Not Null Channel-specific config (tokens, webhook URLs, etc.)
is_active BOOLEAN Default: true Active/inactive toggle
created_at TIMESTAMP Default: now() When connected
updated_at TIMESTAMP Default: now() Last updated

inbound_messages — Received Messages from Channels

Column Type Constraints Description
id BIGINT Primary Key, Auto Unique message ID
channel TEXT Not Null Source channel type
channel_account_id BIGINT Foreign Key → channel_accounts.id Associated account
sender_id TEXT — External sender identifier
sender_name TEXT — Sender display name
body TEXT — Message content
raw_payload JSONB — Full raw webhook payload
lead_id BIGINT Foreign Key → leads.id Matched lead (if any)
created_at TIMESTAMP Default: now() When received

settings — Application Settings

Column Type Constraints Description
id BIGINT Primary Key, Auto Unique setting ID
key TEXT Unique, Not Null Setting key
value JSONB — Setting value

profiles — User Profile

Column Type Constraints Description
id BIGINT Primary Key, Auto Unique profile ID
full_name TEXT — Full name
email TEXT — Email address
phone TEXT — Phone number
company TEXT — Company name
job_title TEXT — Job title
bio TEXT — Short bio
avatar_url TEXT — Avatar image URL (Supabase Storage)
timezone TEXT Default: 'UTC' User timezone
plan TEXT Default: 'Free' Subscription plan
created_at TIMESTAMP Default: now() Creation timestamp
updated_at TIMESTAMP Default: now() Last update timestamp

Lead Status Flow

new → contacted → replied → converted
                          ↘ bounced
                          ↘ unsubscribed

Message Statuses

Status Description
draft Generated but not yet sent
sent Successfully sent via SMTP/Twilio/Slack
delivered Delivery confirmed
failed Send attempt failed (SMTP error, etc.)
blocked Blocked by blacklist check
rate_limited Blocked by daily send limit

📡 API Reference (51+ Endpoints)

Health Check

Method Endpoint Description Response
GET /health Server health check {"status":"ok","timestamp":"ISO-8601"}

Leads API

Method Endpoint Description Query Params
GET /api/leads List leads (paginated) ?search=, ?status=, ?page=, ?limit=
GET /api/leads/:id Get single lead by ID —
POST /api/leads/bulk Bulk import leads Body: { leads: [{name, email, company, title, source}] }
PUT /api/leads/:id Update a lead Body: { name, email, company, title, status }
DELETE /api/leads/:id Delete a lead —

Bulk Import Response:

{
  "imported": 48,
  "skipped": 2,
  "errors": ["Row 5: Invalid email format", "Row 12: Duplicate email"]
}

Workflows API

Method Endpoint Description Body
GET /api/workflows List all workflows —
GET /api/workflows/:id Get workflow by ID —
POST /api/workflows Create workflow { name, description, nodes, edges }
PUT /api/workflows/:id Update workflow { name, description, nodes, edges, is_active }
DELETE /api/workflows/:id Delete workflow —
POST /api/workflows/seed-templates Load 5 template workflows —

Workflow Response (nodes/edges are parsed from JSON):

{
  "id": 1,
  "name": "Cold Outreach Sequence",
  "description": "AI-personalized cold email with follow-up",
  "nodes": [{"id":"1","type":"start","position":{"x":250,"y":0},"data":{}}],
  "edges": [{"id":"e1-2","source":"1","target":"2"}],
  "is_active": true
}

Executions API

Method Endpoint Description Body/Params
POST /api/executions/run Execute workflow on lead(s) { workflowId, leadIds: [1,2,3] }
GET /api/executions List all executions ?status= filter
GET /api/executions/:id Get execution with full logs —

Execution Run Flow:

  1. Validates workflow exists and has nodes
  2. Creates execution record per lead (status: pending)
  3. Starts async execution via WorkflowExecutor
  4. Emits real-time Socket.io events during execution
  5. Updates execution status to completed or failed

Statistics API

Method Endpoint Description
GET /api/stats/overview Full dashboard statistics

Response:

{
  "totalLeads": 50,
  "totalWorkflows": 5,
  "activeWorkflows": 3,
  "totalExecutions": 12,
  "leadsByStatus": [
    {"status": "new", "count": 15},
    {"status": "contacted", "count": 12},
    {"status": "replied", "count": 8},
    {"status": "converted", "count": 10},
    {"status": "bounced", "count": 5}
  ],
  "messagesLast7Days": [
    {"date": "2026-03-01", "count": 8},
    {"date": "2026-03-02", "count": 15}
  ],
  "recentLeads": [
    {"id": 1, "name": "John Smith", "email": "john@acme.com", "status": "new", "created_at": "..."}
  ]
}

AI & Messages API

Method Endpoint Description Body
POST /api/ai/generate Generate one AI message { lead, prompt, tone, messageType, credentialId, ...personalization }
POST /api/ai/preview Preview messages for multiple leads { leads: [...], prompt, tone, credentialId }
POST /api/ai/chat Chat with AI assistant { message, conversationHistory }
POST /api/ai/create-workflow Natural language → workflow { description }
POST /api/ai/send Send a message via any channel { leadId, channel, subject, body }
POST /api/ai/bulk-send Bulk send messages to multiple leads { leadIds, channel, subject, body }

AI Generate Personalization Fields:

{
  "lead": { "name": "Jane", "email": "jane@acme.com", "company": "Acme", "title": "CTO" },
  "prompt": "Write a cold outreach email about {{company}}'s growth",
  "tone": "professional",
  "messageType": "cold_outreach",
  "senderName": "Alex Johnson",
  "companyName": "FlowReach",
  "industry": "SaaS",
  "painPoints": "manual outreach, low response rates",
  "callToAction": "Book a 15-min demo",
  "signature": "Best regards, Alex",
  "language": "English",
  "credentialId": 1
}

Settings API

Method Endpoint Description
GET /api/settings/blacklist List all blacklisted emails/domains
POST /api/settings/blacklist Add email/domain to blacklist — Body: { email, reason }
DELETE /api/settings/blacklist/:id Remove from blacklist
GET /api/settings/daily-stats Today's send count vs limit
GET /api/settings/daily-stats/history Last 7 days send history
POST /api/settings/daily-stats/reset Reset today's send counter to 0
GET /api/settings/safety-score Calculate 100-point safety score

Safety Score Response:

{
  "score": 85,
  "maxScore": 100,
  "checks": [
    { "name": "SMTP Configured", "passed": true, "points": 20, "maxPoints": 20 },
    { "name": "AI Provider Key", "passed": true, "points": 20, "maxPoints": 20 },
    { "name": "Blacklist Active", "passed": true, "points": 15, "maxPoints": 15 },
    { "name": "Daily Limit Reasonable", "passed": true, "points": 15, "maxPoints": 15 },
    { "name": "Workflows Created", "passed": true, "points": 10, "maxPoints": 10 },
    { "name": "Leads Imported", "passed": true, "points": 10, "maxPoints": 10 },
    { "name": "Within Daily Limit", "passed": false, "points": 0, "maxPoints": 10 }
  ]
}

Credentials API

Method Endpoint Description
GET /api/credentials List all credentials (secrets masked in response)
GET /api/credentials/:id Get full credential data (unmasked)
GET /api/credentials/type/:type Filter credentials by provider type
POST /api/credentials Create new credential — Body: { name, type, config }
PUT /api/credentials/:id Update credential
DELETE /api/credentials/:id Delete credential

Credential Config Examples:

// Groq
{ "apiKey": "gsk_..." }

// SMTP
{ "host": "smtp.gmail.com", "port": 587, "user": "you@gmail.com", "pass": "app-password" }

// Slack
{ "botToken": "xoxb-...", "defaultChannel": "#outreach" }

// Twilio
{ "accountSid": "AC...", "authToken": "...", "fromNumber": "+1234567890" }

Seed/Demo API

Method Endpoint Description
POST /api/seed/reset Reset all demo data (re-runs seed.js)

Profile API

Method Endpoint Description Body
GET /api/profile Get user profile (returns defaults if none exists) —
PUT /api/profile Update profile info { full_name, email, phone, company, job_title, bio, timezone }
POST /api/profile/avatar Upload profile avatar photo { base64, filename, contentType }

Messages API

Method Endpoint Description Query Params
GET /api/messages List messages (paginated, filterable) ?type=, ?status=, ?channel=, ?page=, ?limit=
GET /api/messages/:id Get single message with full details —

Channels API

Method Endpoint Description Body
GET /api/channels/accounts List connected channel accounts ?channel= filter
POST /api/channels/accounts Connect new channel account { channel, account_name, config }
PUT /api/channels/accounts/:id Update channel account { account_name, config, is_active }
DELETE /api/channels/accounts/:id Disconnect channel —
GET /api/channels/inbox List inbound messages ?channel=, ?channel_account_id=
POST /api/channels/webhook/whatsapp WhatsApp inbound webhook Handled by Meta Cloud API
GET /api/channels/webhook/whatsapp WhatsApp webhook verification Verification challenge
POST /api/channels/webhook/telegram Telegram inbound webhook Handled by Telegram Bot API
POST /api/channels/webhook/discord Discord inbound webhook Discord interaction payload
POST /api/channels/webhook/slack Slack inbound webhook/events Slack Events API payload

🧩 Workflow Nodes (22 Types)

Triggers (3 Nodes)

Node Icon Description Config Options
Start ▶️ Play Manual workflow trigger — entry point for all workflows Trigger type: Manual, Scheduled, On Import, Webhook
Schedule 🕐 Clock Time-based trigger using cron expressions or intervals Frequency: Every minute/hour/day/week/month, custom cron, timezone
Webhook 🌐 Globe HTTP webhook trigger accepting external requests Path, Method (GET/POST/PUT), Response code

AI & Machine Learning (4 Nodes)

Node Icon Description Config Options
AI Generate ✨ Sparkles Generate personalized content using LLM Prompt template, tone (9 options), max length, message type (8 types), personalization fields
AI Agent 🧠 Brain Multi-provider AI agent for complex tasks Provider (Groq/OpenAI/Anthropic/Google), model selection, system prompt, user prompt, temperature (0-2), max tokens, credential linking
Summarizer 📄 FileText AI-powered text summarization Input text, style (bullets/paragraph/TLDR), max length
Classifier 🏷️ Tags Classify data into custom categories Input text, categories (comma-separated), confidence threshold

Communication (6 Nodes)

Node Icon Description Config Options
Email ✉️ Mail Send emails via SMTP Subject template, from name, SMTP credential selection, body from context
SMS 📱 Smartphone Send SMS via Twilio To phone template, message template, Twilio credential
Slack 💬 MessageSquare Send messages to Slack channels Channel name, message template, Slack credential/webhook
Discord 🎮 Gamepad2 Send messages to Discord channels Webhook URL, message template, username override
Telegram ✈️ Send Send messages via Telegram Bot Bot token, chat ID, message template, parse mode
WhatsApp 📱 Phone Send messages via WhatsApp Business API Phone number, template, Meta Cloud API credential

Logic & Flow Control (5 Nodes)

Node Icon Description Config Options
Condition 🔀 GitBranch If/else branching based on lead field Field (name/email/company/status/title), Operator (equals/not_equals/contains/greater_than/less_than), Value, Two output handles (Yes ✅ / No ❌)
Filter 🔍 Filter Filter leads by criteria Field, operator, value, Match/No Match outputs
Delay ⏱️ Timer Pause execution for a duration Duration (number), Unit (seconds/minutes/hours/days) — capped at 10s for demo
Split 📊 GitFork A/B split routing Mode (round_robin/percentage/by_field), Percentage (0-100), Field name
Merge 🔗 Merge Combine multiple branch inputs Mode (append/keep_first/keep_last/merge_by_key), Key field

Integrations (3 Nodes)

Node Icon Description Config Options
HTTP Request 🌐 Globe Call external REST APIs Method (GET/POST/PUT/PATCH/DELETE), URL, Headers (JSON), Body (JSON), Credential selection
Code 💻 Code Execute custom JavaScript or Python code Language (javascript/python), Code editor, Security-restricted execution
Update Lead 👤 UserCheck Update lead status in database New status dropdown (contacted/replied/converted/bounced/unsubscribed)

Flow (1 Node)

Node Icon Description Config Options
End ⏹️ Square Terminal node — workflow ends here None

Node Configuration Details

Every node component includes:

  • Drag Handle: GripVertical icon for repositioning on canvas
  • Styled Container: Colored background matching category (purple for AI, blue for triggers, green for communication, etc.)
  • Connection Handles: Top handle (input) + bottom handle(s) (output). Condition and Filter nodes have dual outputs (Yes/No or Match/No Match)
  • Label Text: Customizable via config panel

⚙️ Workflow Execution Engine (Deep Dive)

Execution Flow

┌─────────────┐     ┌──────────────────┐     ┌───────────────┐
│  POST /run   │────▶│  Create Execution │────▶│  Find Start   │
│  {workflow,  │     │  Record (pending) │     │  Node         │
│   leadIds}   │     └──────────────────┘     └───────┬───────┘
└─────────────┘                                       │
                                                      ▼
                                              ┌───────────────┐
                                              │  Execute Node  │◀─────┐
                                              │  (switch type) │      │
                                              └───────┬───────┘      │
                                                      │              │
                                    ┌─────────────────┼──────────────┤
                                    ▼                 ▼              │
                              ┌──────────┐    ┌──────────────┐      │
                              │  Emit    │    │  Find Next   │──────┘
                              │  Socket  │    │  Node (edges)│
                              │  Events  │    └──────────────┘
                              └──────────┘           │
                                                     ▼
                                              ┌──────────────┐
                                              │  End Node?   │
                                              │  Yes → Done  │
                                              │  No → Loop   │
                                              └──────────────┘

Per-Node Execution Logic

Node Type What Happens During Execution
Start Logs trigger type, emits start event
AI Generate Calls Groq SDK with prompt + lead data, stores result in messages table, passes generated text to next node
Email Checks blacklist → checks daily limit → sends via SMTP (or Ethereal) → logs result in messages table
Delay setTimeout with configured duration (max 10 seconds in demo mode)
Condition Evaluates lead field against operator + value, follows Yes or No edge
Update Lead Updates lead status in leads table
AI Agent Calls specified AI provider (Groq/OpenAI/etc.) with system + user prompts
Filter Evaluates filter criteria, follows Match or No Match edge
Split Routes to A or B path based on mode (random, percentage, field value)
HTTP Request Makes external HTTP call, captures response for next node
Code Executes JavaScript code in controlled context
Summarizer Summarizes input text using AI
Classifier Classifies input into provided categories
SMS Sends SMS via Twilio (if credentials configured)
Slack Posts message to Slack channel via webhook (if configured)
Discord Posts message to Discord channel via webhook URL
Telegram Sends message via Telegram Bot API (sendMessage)
WhatsApp Sends message via Meta Cloud API / Twilio WhatsApp
Merge Combines data from multiple input branches
End Marks execution as completed, emits completion event

Error Resilience

  • Each node execution is wrapped in try/catch
  • A failing node logs the error but doesn't crash the workflow
  • Execution status is set to failed only if an unrecoverable error occurs
  • All errors are emitted via Socket.io for real-time visibility
  • Log levels: info, warn, error — each stored with timestamp and node ID

📄 Pages & Components

All Pages (21 Routes)

Route Page Component Description
/ LandingPage.jsx Authentication page — Split-screen design with Sign In / Sign Up forms, Google OAuth, Supabase Auth integration. Auto-redirects to /dashboard if already logged in.
/dashboard Dashboard.jsx Analytics dashboard with 4 stat cards, bar chart (leads by status), line chart (messages/7 days), Kanban board (4 columns), recent leads table. Auto-refreshes every 10s.
/leads Leads.jsx Two tabs: All Leads (searchable table with pagination, status filters, edit/delete) and Import (3-step CSV/Excel wizard). Download Sample CSV button.
/workflows Workflows.jsx Grid of workflow cards with Load Templates, Create New, Duplicate, Delete. Shows node count, edge count, active status, last updated.
/workflows/:id WorkflowBuilder.jsx Full React Flow canvas with categorized node palette (7 categories, 22 nodes, search), NodeConfigPanel right sidebar, MiniMap, controls, save/execute buttons, lead selection modal.
/executions Executions.jsx Two tabs: Live Feed (real-time Socket.io log stream) and History (execution list with expandable logs). Stat cards: Total, Completed, Failed, Running.
/messages Messages.jsx Message history across all channels. Filter by type, status, channel. Search by lead or content. Expandable message cards with full details.
/channels Channels.jsx Channel account management for WhatsApp, Telegram, Discord, Slack. Add/edit/disconnect accounts. Status indicators and config forms per channel type.
/ai AIChat.jsx Three sub-views: Chat (conversational AI with 6 quick prompts), Message Generator (form with lead picker, channel selector, personalization, bulk send), Workflow Creator (natural language → workflow graph).
/settings Settings.jsx Three tabs: Safety Score (SVG arc gauge, 7 checks), Blacklist (add/remove/search), API Keys (credential CRUD for 8 providers). Reset Demo Data button.
/profile Profile.jsx Profile management with avatar photo upload (Supabase Storage), personal info form (name, email, phone, company, title, bio, timezone), account info card (plan, member since).
/templates Templates.jsx Message templates management.
/lead-scoring LeadScoring.jsx AI-powered lead scoring and prioritization.
/ab-testing ABTesting.jsx A/B testing for outreach campaigns.
/email-tracking EmailTracking.jsx Email open and click tracking analytics.
/follow-ups FollowUpSequences.jsx Automated follow-up sequence management.
/webhooks Webhooks.jsx Webhook configuration and management.
/lead-enrichment LeadEnrichment.jsx AI-powered lead data enrichment.
/analytics-export AnalyticsExport.jsx Export analytics data and reports.
/crm CRMIntegrations.jsx CRM integration settings and sync.
/calendar CalendarIntegration.jsx Calendar integration for meeting scheduling.
/team TeamCollaboration.jsx Team collaboration and role management.

Core Components

Component File Purpose
AppLayout components/AppLayout.jsx Root layout wrapping all protected pages. Contains Sidebar + <Outlet> + keyboard shortcut system + floating keyboard hint button. Includes Supabase session guard — redirects unauthenticated users to /.
Sidebar components/Sidebar.jsx Left navigation with 4 sections (Overview, AI, Tools, Metrics). 9 nav links. Brand logo, profile area at bottom.
Header components/Header.jsx Top bar with Socket.io connection status indicator, notification area.
LeadImport components/LeadImport.jsx 3-step import wizard. Step 1: drag-drop file. Step 2: column mapping (required: name, email; optional: company, title, source). Step 3: preview + import.
LeadsTable components/LeadsTable.jsx Paginated table (50/page). Search across name, email, company. Color-coded status badges. Edit/delete per row.
NodeConfigPanel components/NodeConfigPanel.jsx Right sidebar form panel in WorkflowBuilder. Renders different config forms based on selected node type. Supports all 22 node types with credential linking.
AIPreviewModal components/AIPreviewModal.jsx Modal showing AI-generated message previews for up to 5 leads. Shows subject, body, tone, source (Groq/Mock). Copy-to-clipboard + regenerate buttons.

UI Component Library

16 reusable UI components based on Radix UI primitives in components/ui/:

avatar, badge, breadcrumb, button, card, chart, dropdown-menu, input, progress, separator, sheet, sidebar, skeleton, table, tabs, tooltip

🔧 Frontend Service Layer

The lib/supabaseService.js file contains 30+ exported functions that serve as the data layer between React components and the backend API:

Leads Operations

Function Description
fetchLeads(search, status, page, limit) Fetch paginated leads with optional filters
fetchLeadById(id) Get single lead
bulkImportLeads(leads) Import array of leads via /api/leads/bulk
updateLead(id, data) Update lead fields
deleteLead(id) Delete a lead

Workflow Operations

Function Description
fetchWorkflows() List all workflows (parsed nodes/edges)
fetchWorkflowById(id) Get single workflow
createWorkflow(data) Create new workflow
updateWorkflow(id, data) Update workflow
deleteWorkflow(id) Delete workflow
seedWorkflowTemplates() Load 5 built-in templates

Messages Operations

Function Description
fetchMessages({ type, status, channel, page, limit }) Fetch paginated messages with filters
fetchMessageById(id) Get single message
deleteMessage(id) Delete a message

Execution Operations

Function Description
runWorkflowExecution(workflowId, leadIds) Execute workflow on selected leads
fetchExecutionsFromAPI(status) List executions with optional status filter
fetchExecutionById(id) Get execution with full logs

Statistics

Function Description
fetchStatsOverview() Get dashboard stats (leads, workflows, charts)

AI & Chat

Function Description
chatWithAI(message, history) Send message to AI chat
createWorkflowWithAI(description) Natural language → workflow

Settings & Safety

Function Description
fetchBlacklistAPI() List blacklisted emails
addToBlacklistAPI(email, reason) Add to blacklist
removeFromBlacklistAPI(id) Remove from blacklist
fetchDailyStats() Today's send count + 7-day history
fetchSafetyScore() Get 100-point safety score
resetDailyCount() Reset today's counter
resetSeedData() Reset all demo data

Credentials

Function Description
fetchCredentials() List all (masked)
fetchCredentialById(id) Get full credential
createCredential(data) Create new credential
updateCredential(id, data) Update credential
deleteCredential(id) Delete credential

Channels

Function Description
fetchChannelAccounts(channel?) List channel accounts (optional channel filter)
createChannelAccount(data) Connect new channel account
updateChannelAccount(id, data) Update account config
deleteChannelAccount(id) Disconnect channel account
fetchInboxMessages(filters) List inbound messages

🔌 Socket.io Real-time Events

Server → Client Events

Event Payload When Emitted
execution:log { executionId, log: { time, level, message, nodeId } } Every time a node logs during execution (info, warn, or error)
execution:status { executionId, status, currentNode, leadId, workflowId } When execution status changes (pending→running→completed/failed)

Client → Server

Event Description
connection Automatic on page load
disconnect On page close / network loss

Frontend Handling

  • Live Feed (Executions page): Listens to execution:log events and appends to log display in real-time
  • Status Updates: Listens to execution:status to update execution cards without polling
  • Connection Indicator: Shows green/red dot based on Socket.io connection state
  • Auto-Reconnect: Socket.io automatically retries connection with exponential backoff
  • Manual Reconnect: Button triggers socket.connect() for force-reconnection

🌱 Seed Data & Demo Mode

Run cd backend && npm run seed to populate the database with realistic demo data:

What Gets Created

Data Type Count Details
Leads 50 Realistic names, emails, companies (TechCorp, InnovateLabs, CloudSync, etc.), titles (CEO, CTO, VP Sales, etc.), mixed statuses
Executions 12 8 completed, 2 failed, 2 running — with realistic log entries
Daily Send Counts 7 Last 7 days, 3-30 messages per day
Blacklist 3 spam@example.com (spam), competitor@rival.com (competitor), unsub@test.com (unsubscribed)

Reset Demo Data

  • API: POST /api/seed/reset
  • UI: Settings page → "Reset Demo Data" button

🛡️ Safety Score System

The safety score is a 100-point gauge that evaluates your outreach setup:

Check Points Description
SMTP Configured 20 pts SMTP credentials exist (env or database)
AI Provider Key 20 pts At least one AI credential configured
Blacklist Active 15 pts At least one blacklist entry exists
Daily Limit Reasonable 15 pts Daily send limit is under 200
Workflows Created 10 pts At least 1 workflow exists
Leads Imported 10 pts At least 1 lead exists
Within Daily Limit 10 pts Today's sends haven't exceeded the limit

The safety score is displayed as an animated SVG arc gauge on the Settings page with a color gradient from red (0) to green (100).

📋 Built-in Workflow Templates

Load these with the "Load Templates" button on the Workflows page:

1. Cold Outreach Sequence

Start → AI Generate (cold email) → Email Send → Delay (3 days) → Condition (replied?) 
  → Yes: Update Lead (replied)
  → No: AI Generate (follow-up) → Email Send → End

2. Lead Nurture Drip

Start → AI Generate (welcome email) → Email Send → Delay (2 days) → Update Lead (contacted) → End

3. Re-engagement Campaign

Start → Condition (status = bounced?) 
  → Yes: AI Generate (win-back) → Email Send → End
  → No: Update Lead (unsubscribed) → End

4. AI-Powered Lead Scoring

Start → AI Agent (score lead 1-100) → Condition (score > 70?) 
  → Yes: Update Lead (contacted) → Email Send → End
  → No: Delay (7 days) → End

5. Multi-Channel Outreach

Start → Split (50/50 A/B) 
  → Path A: AI Generate → Email Send → Delay (1 day) → End
  → Path B: Discord/Telegram/Slack Send → Delay (2 days) → End

🧑‍💻 Development Scripts

# Install all dependencies (root + frontend + backend)
npm run install:all

# Start both frontend & backend concurrently
npm run dev

# Start frontend only (Vite on port 5173)
npm run dev:frontend

# Start backend only (Express on port 3001)
npm run dev:backend

# Seed demo data (50 leads, 12 executions, etc.)
cd backend && npm run seed

# Build frontend for production
cd frontend && npm run build

# Lint frontend code
cd frontend && npm run lint

🔧 Troubleshooting

Issue Solution
EADDRINUSE: address already in use :::3001 Kill the process using port 3001: taskkill /F /IM node.exe (Windows) or lsof -ti:3001 | xargs kill (Mac/Linux)
Port 5173 is in use Vite auto-picks the next port (5174). Or kill existing processes first.
AI features returning mock data Set GROQ_API_KEY in backend/.env or add a Groq credential in Settings → API Keys
Emails not sending Configure SMTP in .env or add SMTP credential in Settings. Without SMTP, emails go to Ethereal (test).
Database connection errors Verify SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY in backend/.env
Socket.io not connecting Ensure backend is running. Check browser console for WebSocket errors. Try the reconnect button.
Workflow execution fails Check the execution logs in Executions → History. Ensure the workflow has a Start node.
Discord messages not sending Verify DISCORD_WEBHOOK_URL is set correctly in .env or as a credential
Telegram messages not sending Verify TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID are set. Ensure the bot has permission to send to the chat.
Slack messages not sending Verify SLACK_WEBHOOK_URL is set. Ensure the webhook is active in your Slack workspace.
Build fails Run cd frontend && npx vite build to see specific errors. Ensure Node.js ≥ 20.x.

📊 Project Metrics

Metric Value
Total Source Files 90+
Frontend Pages 21
Frontend Components 56 (22 nodes + 21 pages + 7 core + 16 UI)
Backend Route Files 10
API Endpoints 51+
Workflow Node Types 22
Database Tables 11
Communication Channels 5 (Email, Discord, Telegram, Slack, SMS)
AI Providers Supported 4 (Groq, OpenAI, Anthropic, Google)
Service Layer Functions 30+
Credential Types 8
Seed Workflow Templates 5
Socket.io Event Types 2 (log, status)
Safety Score Checks 7
Keyboard Shortcuts 8
Vite Build Modules 2,719

👥 Team

Team S8UL — Built for COHERENCE-26 Hackathon

📜 License

This project was built for the COHERENCE-26 hackathon. All rights reserved.

Built with ❤️ by Team S8UL
React · Express · Supabase · Groq AI · Socket.io · Tailwind CSS
Email · Discord · Telegram · Slack · SMS

About

FlowReachAI is an AI-driven workflow automation platform that simplifies complex processes, boosts efficiency, and connects tools seamlessly using smart integrations and adaptive intelligence

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • JavaScript 99.4%
  • Other 0.6%