Everflow

Full-featured affiliate marketing & partner management platform.
_{Track clicks, attribute conversions, manage partners, detect fraud, generate invoices — all self-hosted with zero external dependencies.}

Quick Start • Features • Architecture • API Reference • User Roles • Configuration

Quick Start

git clone https://github.com/crshdn/everflow.git
cd everflow
npm install
npm start

Open http://localhost:3000 and login:

Role	Email	Password
Admin	`admin@everflow.local`	`admin123`
Advertiser	`advertiser1@everflow.local`	`admin123`
Affiliate	`affiliate1@everflow.local`	`admin123`

The database auto-creates with seed data on first run — 9 users, 11 offers, 640 clicks, 90+ conversions, fraud rules, categories, and more.

Features

Tracking & Attribution

Feature	Description
Redirect Tracking	`302` redirect via `/track/:code` with full click recording
Direct Linking	JavaScript SDK for clickless attribution via first-party cookies
Impression Tracking	Pixel/SDK-based impression events for view-through attribution
SmartLinks	Auto-route traffic to best offer by geo, device, and OS targeting
SmartSwitch	KPI-based auto-optimization (CR / EPC / RPC) for SmartLink weights
Multi-Touch Attribution	5 models — last click, first click, linear, time decay, position-based
Offer Groups	Bundle offers with weighted/sequential/random rotation
Coupon Codes	Clickless conversion attribution via promo codes
QR Codes	Auto-generated QR code PNGs for any tracking link
Post-Conversion Events	Upsells, renewals, refunds, subscriptions — multiple events per conversion
Partner Postbacks	Outbound HTTP postbacks with macro replacement (`{click_id}`, `{payout}`, etc.)
GeoIP Detection	Country, city, region, ISP via ipwhois.io with in-memory TTL cache

Offer Management

Feature	Description
Multiple URLs	Weighted URL rotation per offer
Geo/Device Targeting	Allow/block rules by country, device, OS, IP range
Fail Traffic Routing	Custom redirects for blocked geo, cap reached, expired, etc.
Forwarding Rules	Conditional routing by affiliate, sub-ID, country, device
Visibility Controls	Whitelist/blacklist offers per affiliate
Custom Caps	Per-affiliate daily/monthly/total conversion caps
Scrub Rates	Per-affiliate conversion rejection rates
Creatives	Upload and manage banners, text links, email templates
Labels & Categories	Organize offers with tags and hierarchical categories

Partner Management

Feature	Description
Affiliate Portal	Self-service: browse offers, apply, view tracking links, manage postbacks
Advertiser Portal	Dashboard with KPIs, offer management, conversion logs, affiliate performance
Affiliate Tiers	Gold/Silver/Bronze with payout multipliers and auto-promotion
Channels	Classify traffic sources (email, social, native, search, display, etc.)
Business Units	Organizational scoping for multi-team environments
Marketplace	Discover affiliates by specialization, tier, and performance

Fraud Detection

Feature	Description
Rules Engine	Configurable rules for click frequency, UA anomaly, IP duplicates, conversion velocity, geo mismatch
Fraud Scoring	0–100 score per click based on composite signal analysis
Alerts Dashboard	Real-time fraud alerts with severity levels and review workflow
IP Blacklist	Manual + auto-populated blacklist with expiration
Traffic Health	Aggregate health metrics per affiliate and offer

Reporting & Analytics

Feature	Description
Performance Reports	By offer, affiliate, date, country, sub-ID — with hourly/daily/weekly/monthly intervals
Raw Clicks & Conversions	Full-detail logs with all fields, filterable and paginated
Funnel Reports	Impression → click → conversion → post-event drop-off analysis
LTV / Customer Value	Lifetime value aggregation across 7d, 30d, 90d, and lifetime windows
Attribution Reports	Side-by-side model comparison for conversion credit distribution
Postback Logs	Delivery status tracking for outbound partner postbacks
Saved Reports	Save and re-run custom report configurations
CSV Export	One-click export from any report

Payments & Invoicing

Feature	Description
Invoice Generation	Auto-generate per-affiliate invoices for billing periods
Payment Processing	Simulated batch processing (ACH, wire, PayPal, check)
Payment Methods	Affiliates manage their own payout methods
KYC Records	Document upload and admin review workflow
Bonus Rules	Automated bonus payouts based on conversion events

Platform

Feature	Description
API Key Auth	SHA-256 hashed keys with scopes, expiration, and prefix display
Webhook System	Event-driven webhooks with HMAC signatures and delivery logs
Rate Limiting	In-memory sliding window (100/min API, 1000/min tracking)
Audit Logging	Every write operation logged with user, IP, entity, and details
GDPR Tools	Data export (JSON) and anonymization (hash PII, clear IPs)
Multi-Currency	Exchange rate table with conversion helpers
White-Label	Custom company name, logo, and brand colors via settings
PWA	Service worker, offline page, installable manifest
Integrations Framework	Adapter stubs for Google Ads, Meta CAPI, TikTok, Shopify, HubSpot, Salesforce, Zapier, IPQS, Anura

Architecture

everflow/
├── server.js                  # Express app, middleware, route mounting
├── src/
│   ├── auth.js                # Login/logout/me endpoints
│   ├── db.js                  # SQLite schema (63 tables) + seed data
│   ├── middleware/
│   │   ├── auth.js            # Session + API key authentication
│   │   ├── apikey.js          # Pre-route API key resolver
│   │   └── rate-limit.js      # Sliding window rate limiter
│   ├── utils/
│   │   └── paginate.js        # Generic SQL pagination helper
│   ├── routes/                # 27 route modules
│   │   ├── offers.js          # CRUD + targeting, caps, scrub rates, URLs
│   │   ├── tracking.js        # Click redirect, offer groups, SmartLinks, QR
│   │   ├── conversions.js     # Postback ingest, bulk import, fraud checks
│   │   ├── reports.js         # 15+ report types + fraud management
│   │   ├── payments.js        # Invoices, payments, payment methods, KYC
│   │   └── ...                # 22 more route modules
│   └── services/              # 13 business logic modules
│       ├── fraud-engine.js    # Click/conversion fraud evaluation
│       ├── attribution.js     # Multi-touch attribution models
│       ├── geoip.js           # IP geolocation with caching
│       ├── postback-sender.js # Outbound postback firing
│       ├── invoice-generator.js
│       ├── smart-switch-engine.js
│       └── integrations/      # 9 platform adapters
├── public/
│   ├── css/app.css            # Dark theme with CSS variables
│   ├── js/app.js              # Shell, navigation, auth boot
│   ├── js/*.js                # 25+ page-specific modules
│   ├── js/sdk/                # Client-side tracking SDK
│   ├── sw.js                  # Service worker
│   └── manifest.json          # PWA manifest
└── views/                     # 35 HTML pages

Stack

Layer	Technology	Why
Runtime	Node.js 18+	Modern JS, native `fetch`, `--watch` mode
Framework	Express 4	Battle-tested, minimal, extensible
Database	SQLite (better-sqlite3)	Zero config, single file, synchronous queries, WAL mode
Sessions	express-session + connect-sqlite3	Server-side sessions, no JWT complexity
Frontend	Vanilla JS + Tailwind CSS (CDN) + Chart.js	No build step, instant reload, zero tooling
Auth	bcrypt + session cookies	Secure password hashing, httpOnly cookies

Data Flow

                                          ┌─────────────┐
  Advertiser                              │  Offer URLs  │
  Landing Page  ◄──── 302 Redirect ◄──── │  Targeting   │
                                          │  Fail Traffic│
                                          └──────┬───────┘
                                                 │
  Visitor ──► /track/:code ──► Click Recorded ──►│
         │                     ├── GeoIP Lookup   │
         │                     ├── Fraud Scoring  │
         │                     ├── Cap Check      │
         │                     └── Attribution     │
         │                          Touchpoint     │
         │                                         │
         └──► /api/postback ──► Conversion ────────┘
                                ├── Scrub Rate Check
                                ├── Custom Cap Check
                                ├── Fraud Evaluation
                                ├── Partner Postback ──► Affiliate Tracker
                                ├── Webhook Dispatch ──► External Systems
                                └── Invoice Line Item

API Reference

All endpoints are under /api/ and return JSON. Authenticate via session cookie or X-Eflow-API-Key header.

Auth

Method	Endpoint	Description
`POST`	`/api/auth/login`	Login with email/password
`POST`	`/api/auth/logout`	End session
`GET`	`/api/auth/me`	Current user info

Offers

Method	Endpoint	Description
`GET`	`/api/offers`	List offers (scoped by role)
`POST`	`/api/offers`	Create offer
`GET`	`/api/offers/:id`	Offer detail + targeting, URLs, caps, creatives
`PUT`	`/api/offers/:id`	Update offer
`DELETE`	`/api/offers/:id`	Delete offer
`GET`	`/api/offers/my/offers`	Affiliate's approved offers with stats
`POST`	`/api/offers/:id/apply`	Affiliate applies to offer

Offer Sub-Resources

Method	Endpoint	Description
`POST/GET/PUT/DELETE`	`/api/offers/:id/urls`	Multiple landing page URLs
`POST/GET/PUT/DELETE`	`/api/offers/:id/targeting`	Geo/device/OS targeting rules
`POST/GET/PUT/DELETE`	`/api/offers/:id/fail-traffic`	Fail traffic redirects
`POST/GET/PUT/DELETE`	`/api/offers/:id/forwarding-rules`	Conditional routing
`POST/GET/DELETE`	`/api/offers/:id/visibility`	Affiliate whitelist/blacklist
`POST/GET/PUT/DELETE`	`/api/offers/:id/custom-caps`	Per-affiliate caps
`POST/GET/PUT/DELETE`	`/api/offers/:id/scrub-rates`	Per-affiliate scrub rates
`POST/GET/PUT/DELETE`	`/api/offers/:id/creatives`	Banner/text creatives

Tracking

Method	Endpoint	Description
`GET`	`/track/:code`	Click redirect (main tracking URL)
`GET`	`/track/og/:code`	Offer group redirect
`GET`	`/track/sl/:code`	SmartLink redirect
`GET`	`/api/tracking-links/:id/qr`	QR code PNG
`GET`	`/api/postback`	Inbound conversion postback

SDK

Method	Endpoint	Description
`POST`	`/api/sdk/impression`	Record impression
`POST`	`/api/sdk/click`	Direct linking click
`POST`	`/api/sdk/conversion`	Client-side conversion
`POST`	`/api/sdk/event`	Generic event (app installs, etc.)

Conversions

Method	Endpoint	Description
`GET`	`/api/conversions`	List conversions (paginated, scoped)
`POST`	`/api/conversions`	Manual conversion entry (admin)
`POST`	`/api/conversions/import`	Bulk import (admin)
`PUT`	`/api/conversions/bulk-update`	Bulk status update

Reports

Method	Endpoint	Description
`GET`	`/api/reports/overview`	Dashboard KPIs + charts
`GET`	`/api/reports/by-offer`	Performance by offer
`GET`	`/api/reports/by-affiliate`	Performance by affiliate
`GET`	`/api/reports/by-date`	Time series (`?interval=hourly\|daily\|weekly\|monthly`)
`GET`	`/api/reports/by-country`	Geographic breakdown
`GET`	`/api/reports/by-sub`	Sub-ID breakdown (`?sub_field=sub1..sub5`)
`GET`	`/api/reports/raw-clicks`	Individual click records
`GET`	`/api/reports/raw-conversions`	Individual conversion records
`GET`	`/api/reports/ltv`	Customer lifetime value
`GET`	`/api/reports/attribution`	Multi-model attribution comparison
`GET`	`/api/reports/postback-logs`	Outbound postback delivery logs

More Endpoints

Fraud Detection (admin)

Method	Endpoint	Description
`GET/PUT`	`/api/fraud/alerts`	Fraud alerts + review
`GET/POST/PUT/DELETE`	`/api/fraud/rules`	Fraud rule management
`GET/POST/DELETE`	`/api/fraud/ip-blacklist`	IP blacklist
`GET`	`/api/fraud/traffic-health`	Traffic quality metrics

Payments

Method	Endpoint	Description
`POST`	`/api/invoices/generate`	Generate invoices for period
`GET`	`/api/invoices`	List invoices
`PUT`	`/api/invoices/:id/approve`	Approve invoice
`POST`	`/api/payments/process`	Batch process approved invoices
`GET`	`/api/payments`	Payment history
`POST/GET/PUT/DELETE`	`/api/payment-methods`	Affiliate payment methods

Platform

Method	Endpoint	Description
`POST/GET/DELETE`	`/api/api-keys`	API key management
`GET`	`/api/audit-logs`	Audit trail
`POST/GET/PUT/DELETE`	`/api/webhooks`	Webhook subscriptions
`POST/GET`	`/api/gdpr/export\|delete\|consent`	GDPR tools
`GET/POST/PUT/DELETE`	`/api/partner-postbacks`	Partner postback URLs
`GET/POST/PUT/DELETE`	`/api/coupon-codes`	Coupon code management
`GET/POST/PUT/DELETE`	`/api/offer-groups`	Offer group management
`GET/POST/PUT/DELETE`	`/api/smart-links`	SmartLink management
`GET/PUT`	`/api/notifications`	In-app notifications
`GET/POST/PUT/DELETE`	`/api/labels`	Label management
`GET/POST/PUT/DELETE`	`/api/categories`	Category management
`GET/POST/PUT/DELETE`	`/api/channels`	Channel management
`GET/POST/PUT/DELETE`	`/api/funnels`	Funnel definitions
`POST/GET/PUT/DELETE`	`/api/reports/saved`	Saved report configs

User Roles

Admin

Full platform access — manage all offers, affiliates, advertisers, fraud rules, invoices, settings, integrations, and system configuration.

Advertiser

Create and manage own offers only (ownership enforced server-side)
View conversions and reports scoped to own offers
See which affiliates drive their traffic
Access marketplace, offer groups, coupon codes
Cannot access: settings, fraud, affiliates list, audit logs

Affiliate

Portal — browse available offers, apply, manage approved offers with tracking links
View own clicks, conversions, earnings, and reports
Manage postbacks, payment methods, coupon codes, API keys
Cannot access: settings, fraud, offer creation, other affiliates' data

All data scoping is enforced at the SQL query level — not just the UI.

Configuration

Environment Variables

Variable	Default	Description
`PORT`	`3000`	HTTP port
`HOST`	`127.0.0.1`	Bind address
`SESSION_SECRET`	`everflow-clone-dev-secret`	Session encryption key
`GEOIP_API_KEY`	(none)	ipwhois.io API key (optional, works without for basic lookups)

Admin Settings

Configurable at runtime via /settings (admin only):

Setting	Description
`company_name`	Platform name (shown in sidebar)
`brand_primary_color`	Theme color (CSS variable override)
`brand_accent_color`	Secondary accent color
`brand_logo_url`	Custom logo URL
`postback_url`	Default inbound postback URL
`default_payout`	Default offer payout amount
`smtp_host/port/user/pass/from`	Email notification settings

Database

SQLite database auto-creates at data/everflow.db on first run. To reset:

rm data/everflow.db data/sessions.db
npm start

JavaScript SDK

Drop-in client-side tracking for direct linking and clickless attribution:

<script src="https://your-domain.com/public/js/sdk/everflow-sdk.js"></script>
<script>
  EverflowSDK.init({ api_url: 'https://your-domain.com' });

  // Track impression
  EverflowSDK.impression({ offer_id: 1, affiliate_id: 5 });

  // Direct link click (no redirect)
  EverflowSDK.click({ offer_id: 1, affiliate_id: 5 });

  // Fire conversion
  EverflowSDK.conversion({ transaction_id: 'order-123', amount: 49.99 });
</script>

The SDK automatically reads ?ef_aid= and ?ef_oid= URL parameters and stores attribution in first-party cookies.

Seed Data

The database ships with realistic demo data:

Entity	Count	Details
Users	9	1 admin, 3 advertisers, 5 affiliates
Offers	11	Health, Finance, Insurance, Software, Gaming, etc.
Clicks	640	Distributed across 30 days with geo/device variety
Conversions	90+	Mixed approved/pending/rejected statuses
Categories	9	Health, Finance, Insurance, Software, Gaming, Ecommerce, B2B, Travel, Entertainment
Fraud Rules	5	Click frequency, UA anomaly, conversion velocity, geo mismatch, IP duplicate
Affiliate Tiers	4	Standard, Silver, Gold, Platinum
Notifications	3	Fraud alert, milestone, approval

Stats

89 JavaScript files  ·  35 HTML views  ·  63 database tables
27 route modules  ·  13 services  ·  8,500+ lines of code
0 build tools  ·  8 npm dependencies  ·  1 database file

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
public		public
src		src
views		views
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
SPEC.md		SPEC.md
package-lock.json		package-lock.json
package.json		package.json
server.js		server.js

Folders and files

Latest commit

History

Repository files navigation

Everflow

Quick Start

Features

Tracking & Attribution

Offer Management

Partner Management

Fraud Detection

Reporting & Analytics

Payments & Invoicing

Platform

Architecture

Stack

Data Flow

API Reference

Auth

Offers

Tracking

SDK

Conversions

Reports

Fraud Detection (admin)

Payments

Platform

User Roles

Admin

Advertiser

Affiliate

Configuration

Environment Variables

Admin Settings

Database

JavaScript SDK

Seed Data

Stats

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors 2

Languages

Packages