Intelligent Routing

Entrolytics features a hybrid architecture with both Node.js and Edge Runtime support for data collection. The intelligent routing system automatically selects the optimal adapter based on your website settings and plan tier.

Why Dual Runtimes?

Different applications have different requirements:

• Edge Runtime: Optimized for speed and global distribution (sub-50ms latency)
• Node.js Runtime: Full-featured with advanced capabilities (ClickHouse, MaxMind GeoIP)

Not all setups and use cases are edge-compatible, so Entrolytics provides 100% full support for both runtimes.

Collection Endpoints

Entrolytics provides three collection endpoints:

POST /api/collect (Recommended)

Intelligent routing endpoint - Automatically selects the optimal adapter.

• Runtime: Hybrid (Node.js with routing logic)
• Use Case: Default for all SDKs and tracking scripts
• Features: Auto-optimization, plan-based routing
• Selection Logic:
  • Free/Pro tiers → Edge adapter (fast, cost-effective)
  • Business/Enterprise → Node.js adapter (advanced features)
  • Configurable per website via ingestMode setting

Example:

curl -X POST https://entrolytics.click/api/collect \
  -H "Content-Type: application/json" \
  -d '{
    "type": "event",
    "payload": {
      "website": "your-website-id",
      "url": "/dashboard",
      "hostname": "example.com"
    }
  }'

POST /api/send

Direct Node.js endpoint - Full-featured with Node.js capabilities.

• Runtime: Node.js only
• Use Case: Advanced features, custom implementations
• Features:
  • ClickHouse data export
  • MaxMind GeoIP lookups (city-level accuracy)
  • Custom event processing
  • Advanced analytics transformations

When to use:

• Self-hosted deployments without edge runtime
• Applications requiring ClickHouse integration
• Need for advanced geo-targeting with MaxMind
• Custom server-side analytics workflows

Example:

curl -X POST https://entrolytics.click/api/send \
  -H "Content-Type: application/json" \
  -d '{
    "type": "event",
    "payload": {
      "website": "your-website-id",
      "url": "/product/123",
      "hostname": "shop.example.com"
    }
  }'

POST /api/send-native

Direct Edge endpoint - Optimized for global low-latency.

• Runtime: Edge only (Vercel/Netlify/Cloudflare compatible)
• Use Case: Global distribution, low latency, edge functions
• Features:
  • Sub-50ms response times globally
  • Fast cold starts (<100ms)
  • Edge-compatible rate limiting (Upstash Redis)
  • Provider header geo data extraction
• Limitations:
  • No ClickHouse export
  • No MaxMind GeoIP (uses provider headers)
  • Basic geo data only (country, region from headers)

When to use:

• Vercel/Netlify edge functions
• Edge-to-edge communication
• Applications prioritizing latency over features
• Globally distributed serverless apps

Example:

curl -X POST https://entrolytics.click/api/send-native \
  -H "Content-Type: application/json" \
  -d '{
    "type": "event",
    "payload": {
      "website": "your-website-id",
      "url": "/blog/post-1",
      "hostname": "blog.example.com"
    }
  }'

Ingest Mode Configuration

Configure your website's ingest mode in the Entrolytics dashboard:

Auto (Recommended)

Automatically selects the best adapter based on plan tier:

• Free/Pro: Edge adapter for cost-effectiveness
• Business/Enterprise: Node.js adapter for advanced features

Node.js

Forces Node.js adapter for all requests:

• Use when you need ClickHouse integration
• Required for MaxMind GeoIP lookups
• Best for self-hosted deployments

Edge

Forces Edge adapter for all requests:

• Use when latency is critical
• Best for edge function deployments (Vercel, Netlify)
• Ideal for globally distributed applications

Performance Comparison

Rate Limiting

Both adapters implement rate limiting:

Node.js Adapter

• Tiered rate limits based on plan
• Redis-based distributed rate limiting
• Configurable per-plan limits

Edge Adapter

• Edge-compatible rate limiting via Upstash Redis HTTP
• Same tiered limits as Node.js
• Sub-millisecond overhead

Rate Limits by Plan:

• Free: 60 requests/minute
• Pro: 120 requests/minute
• Business: 300 requests/minute
• Enterprise: 1000 requests/minute

Monthly Quotas

Both adapters enforce monthly event quotas:

• Free: 10,000 events/month
• Pro: 100,000 events/month
• Business: 1,000,000 events/month
• Enterprise: 10,000,000 events/month

Quota tracking is handled via Redis caching with automatic resets.

Routing Analytics

The routing system records metrics for monitoring:

• Adapter Usage: Track Node.js vs Edge usage
• Response Times: Monitor performance per adapter
• Error Rates: Detect issues with specific adapters
• Mode Distribution: Analyze auto/node/edge mode usage

Access routing analytics in the admin dashboard at /admin/routing.

SDK Configuration

Configure the collection endpoint in your SDKs:

React SDK

import { EntrolyticsProvider } from '@entro314labs/entro-react';

function App() {
  return (
    <EntrolyticsProvider
      websiteId="your-website-id"
      endpointMode="auto" // or "node" or "edge"
    >
      <YourApp />
    </EntrolyticsProvider>
  );
}

Next.js SDK

// app/providers.tsx
import { EntrolyticsProvider } from '@entro314labs/entro-nextjs';

export function Providers({ children }) {
  return (
    <EntrolyticsProvider
      websiteId={process.env.NEXT_PUBLIC_ENTROLYTICS_WEBSITE_ID}
      endpointMode="auto" // Intelligent routing
    >
      {children}
    </EntrolyticsProvider>
  );
}

Custom Endpoint Override

<EntrolyticsProvider
  websiteId="your-website-id"
  endpoint="/api/send-native" // Direct endpoint override
>
  {children}
</EntrolyticsProvider>

Self-Hosting Considerations

For self-hosted deployments:

Without Edge Runtime

# Force all traffic to Node.js adapter
ENTROLYTICS_FORCE_NODE_ROUTING=true

All collection endpoints will use the Node.js adapter, even if edge mode is requested.

With Edge Runtime (Vercel, Netlify, Cloudflare)

# Enable edge routing (default)
ENTROLYTICS_FORCE_EDGE_ROUTING=false

# Configure Upstash Redis for edge functions
UPSTASH_REDIS_REST_URL=https://...
UPSTASH_REDIS_REST_TOKEN=...

Edge functions require Upstash Redis for rate limiting and quota management.

Best Practices

For Client-Side Tracking

Use Auto mode (/api/collect) to benefit from intelligent routing:

window.entrolytics.init({
  websiteId: 'your-id',
  // No endpoint specified - uses /api/collect by default
});

For Server-Side Tracking

Choose based on your infrastructure:

Vercel/Netlify Edge Functions:

const response = await fetch('https://entrolytics.click/api/send-native', {
  method: 'POST',
  body: JSON.stringify(event)
});

Node.js Servers:

const response = await fetch('https://entrolytics.click/api/send', {
  method: 'POST',
  body: JSON.stringify(event)
});

For Integrations

Vercel Integration: Automatically configured to use /api/send-native Netlify Plugin: Edge functions use /api/send-native, client scripts use /api/collect

Monitoring

Monitor routing health via:

1. Admin Dashboard: /admin/routing
2. Health Check: GET /api/health/integrations includes routing status
3. Logs: Check application logs for routing decisions

Troubleshooting

High Latency

If experiencing high latency:

1. Check if using optimal endpoint for your infrastructure
2. Consider switching to edge adapter for distributed apps
3. Review rate limit configuration

Missing Geo Data

Edge adapter uses provider headers for geo data:

• Country, region from Cloudflare/Vercel/Netlify headers
• No city-level accuracy (use Node.js adapter with MaxMind for detailed geo)

Rate Limit Exceeded

If hitting rate limits:

1. Upgrade plan tier for higher limits
2. Implement client-side request batching
3. Use session-based deduplication

Related Documentation

• API Reference - Complete API documentation
• React SDK - React integration guide
• Next.js SDK - Next.js integration guide
• Vercel Integration - Vercel marketplace integration
• Netlify Plugin - Netlify build plugin