WebPulse Analytics v2.0

Next-Generation Real-Time Web Telemetry & Visitor Analytics

A privacy-focused, high-performance web analytics platform engineered for modern web applications.
Track live visitors, page performance, and custom telemetry events with zero hassle.

---

Current Release: Version 2.0 is the active, production-ready release of WebPulse Analytics. It brings a completely overhauled design system, a 3D interactive data network globe, 15+ comprehensive dashboard modules, additive Supabase SQL aggregations with 11 custom RPCs, and dual-layer resilient querying.

---

Table of Contents

• What's New in Version 2.0
• Key Features
• Architecture & Data Strategy
• Technology Stack
• Quick Start
  • Prerequisites
  • Environment Setup
  • Database Migrations
  • Running the Services
• Tracking Script & Integration
  • HTML Snippet
  • Custom Event Telemetry
  • REST Ingestion
• Application Route Map
• API Overview
• Project Structure
• Documentation Directory
• Security & Compliance
• Contributing & Community
• License

---

What's New in Version 2.0

WebPulse Analytics v2 is an end-to-end upgrade of both client and server architectures:

Module	Version 2.0 Upgrade
Design System	Dark Data Observatory: Semantic CSS tokens (theme.css), smooth dark/light mode switching using the native browser View Transitions API (circular click reveal), and refined SaaS typography.
Interactive Globe	3D Visitor Network: WebGL/Three.js interactive globe powered by react-globe.gl with centroid country mapping, drag-to-rotate, and live telemetry arcs.
UI Component Kit	Accessible primitives under src/components/ui/ (Icon, Button, Card, DataTable, Field, Display, Overlay, Blocks, Charts, State, Nav, Page).
Dashboard Suite	15+ Dedicated Views: Visitors, Sessions, Pages, Custom Events & Drilldowns, Traffic Sources, Geography, Real-Time Activity, Threshold Alerts, Audit Logs, and Shareable Reports.
Supabase Analytics Engine	Additive PostgreSQL schema with 11 high-performance RPC aggregation functions, composite B-tree indexes, partition-ready timestamp keys, and strict Row Level Security (RLS).
Resilient Data Strategy	Dual-source pipeline in src/lib/dataService.js: Direct Supabase PostgREST/RPC queries with automated Express 5 API fallback. Honest zero-data states without synthetic mocks.
Zero-Flash Preloader	Inlined SVG pulsing emblem in index.html with shimmer progress track eliminates white/blank flashes during asset loading.
Security Hardening	Dynamic Content Security Policy (CSP) for Supabase REST & WebSockets, Leaflet dark tile providers, rate limiting, and hashed API keys.

---

Key Features

• ⚡ Real-Time Visitor Streaming: Live telemetry and active visitor counts streamed via Socket.IO directly to your dashboard.
• 🌐 3D Geospatial Visualizations: Interactive WebGL visitor globe and high-definition Leaflet maps for granular geographic distribution.
• 🎯 Custom Event Telemetry: Track interactions, conversions, button clicks, and custom metadata with flexible JSONB payloads.
• 📊 Content & Page Performance: Monitor real-time pageviews, bounce rates, visit durations, entrance/exit paths, and scroll depth.
• 🧭 Attribution & Source Breakdown: Automatic tracking of search engines, social referrals, direct traffic, and campaign channels.
• 🛡️ Privacy & Compliance: Cookieless tracking options, hashed IP addresses, and respect for Do Not Track (DNT) headers.
• 🏢 Multi-Project Management: Manage multiple websites and apps under a single workspace with per-project tracking IDs and settings.
• 🔔 Multi-Channel Alerting: Instant threshold triggers and notifications dispatched via Transactional Email (Resend) and Telegram bots.
• 🔗 Shareable Public Reports: Generate secured, read-only dashboard tokens to share real-time metrics with clients and stakeholders.
• 💳 Billing & Quota Management: Built-in subscription tiers, usage limits, and Razorpay payment integration.

---

Architecture & Data Strategy

WebPulse Analytics v2 utilizes an optimized dual-path data flow engineered for sub-second dashboards and zero downtime:

[ Tracked Websites ]
         │ (HTTP POST /api/track)
         ▼
 ┌──────────────────────────────────────────────┐
 │             Express 5 Backend                │
 │  - Rate Limiter & Helmet CSP                │
 │  - Geolocation (geoip-lite) & User-Agent    │
 │  - Socket.IO Gateway Server                 │
 └──────┬────────────────────────────────┬──────┘
        │                                │ (Live WebSocket Events)
        ▼                                ▼
 ┌──────────────────────┐      ┌──────────────────────┐
 │   Supabase Postgres   │◄────┤  React 19 Dashboard  │
 │  - Core Tables       │      │  (Dual Data Service) │
 │  - 11 Analytics RPCs │      │  - Supabase Primary  │
 │  - RLS Security      │      │  - Express Fallback  │
 └──────────────────────┘      └──────────────────────┘

1. Ingestion Layer: Public endpoints (/api/track/:trackingId and /api/track/events) parse incoming pings, extract geo/device telemetry, and persist records to Supabase.
2. Real-Time Stream: Live events are broadcast via Socket.IO rooms scoped by project ID, triggering instantaneous dashboard metric increments.
3. Analytics Layer: The frontend queries high-speed SQL RPC functions directly via Supabase PostgREST. If permissions or connectivity require, dataService.js transparently falls back to the backend API.

---

Technology Stack

Frontend Application

• Framework: React 19 + Vite 7
• Routing: React Router 7
• Styling: Tailwind CSS 3 + Custom CSS Design System (theme.css, app.css)
• Visualizations: Recharts 3, react-globe.gl (Three.js), Leaflet
• Animations: Framer Motion 12, GSAP
• Icons: Lucide React
• Real-Time: Socket.IO Client 4
• Database Client: @supabase/supabase-js 2

Backend Service

• Runtime: Node.js 22 LTS
• Web Framework: Express 5
• Real-Time Server: Socket.IO 4
• Authentication: JWT, Google Auth Library, bcryptjs
• Telemetry Parsers: geoip-lite, ua-parser-js
• Security Middleware: Helmet 8, express-rate-limit, CORS, cookie-parser
• Notifications & Billing: Resend, Razorpay, Cloudinary, PDFKit

Database & Storage

• Database: Supabase PostgreSQL 15+
• Analytics Functions: 11 Custom PL/pgSQL RPC procedures (supabase/migrations/)
• Security: Row Level Security (RLS) policies with multi-tenant isolation

---

Quick Start

Prerequisites

• Node.js: v20.0.0 or higher (v22 LTS recommended)
• npm: v10 or higher
• Supabase Account: A Supabase project for PostgreSQL data storage

Environment Setup

1. Clone the repository:

   git clone https://github.com/heyshreee/Web-Pulse-Analytics.git
   cd Web-Pulse-Analytics

2. Configure Backend Environment:

   cd backend
   cp .env.example .env

   Edit backend/.env with your credentials:

   PORT=5000
   NODE_ENV=development
   FRONTEND_URL=http://localhost:5173
   BACKEND_URL=http://localhost:5000
   JWT_SECRET=your_jwt_secret_key
   CSRF_SECRET=your_csrf_secret_key
   SUPABASE_URL=https://your-project.supabase.co
   SUPABASE_ANON_KEY=your_supabase_anon_key
   SUPABASE_SERVICE_KEY=your_supabase_service_role_key

3. Configure Frontend Environment:

   cd ../frontend
   cp .env.example .env

   Edit frontend/.env:

   VITE_API_URL=http://localhost:5000
   VITE_SUPABASE_URL=https://your-project.supabase.co
   VITE_SUPABASE_ANON_KEY=your_supabase_anon_key

Database Migrations

Apply the versioned SQL migrations in supabase/migrations/ to your Supabase project in sequential order:

# Using Supabase CLI:
supabase db push

# Alternatively: Execute the SQL files in Supabase SQL Editor:
# 1. 20261001000001_core_schema.sql
# 2. 20261001000002_analytics_tables.sql
# 3. 20261001000003_indexes.sql
# 4. 20261001000004_analytics_functions.sql
# 5. 20261001000005_rls_security.sql
# 6. 20261008000001_fix_security_and_performance_linter.sql

Note: Database migrations are never executed automatically by CI/CD workflows to prevent accidental production downtime.

Running the Services

1. Install and run the Backend:

   cd backend
   npm install
   npm run dev

   The API server will listen on http://localhost:5000.

2. Install and run the Frontend:

   cd frontend
   npm install
   npm run dev

   The Vite development server will open on http://localhost:5173.

---

Tracking Script & Integration

WebPulse Analytics v2 provides a lightweight client tracker that can be embedded into any web property.

1. Standard HTML Embed

Add the following snippet before the closing </head> tag on your website:

<!-- WebPulse Analytics v2 Tracker -->
<script
  defer
  src="http://localhost:5000/api/track/script.js"
  data-site="YOUR_PROJECT_TRACKING_ID">
</script>

2. Custom Event Telemetry

Send custom interaction events from your application code:

// Track button clicks, conversions, or signups
if (window.webpulse) {
  window.webpulse('track', 'button_click', {
    button_name: 'upgrade_cta',
    plan_tier: 'pro_annual',
    value: 120
  });
}

3. REST API Ingestion

You can also record events server-side using standard HTTP requests:

POST /api/track/events HTTP/1.1
Host: localhost:5000
Content-Type: application/json

{
  "trackingId": "YOUR_PROJECT_TRACKING_ID",
  "eventName": "checkout_completed",
  "url": "https://example.com/checkout/success",
  "metadata": {
    "currency": "USD",
    "amount": 49.99
  }
}

---

Application Route Map

The v2 frontend offers a complete suite of marketing, authentication, and telemetry views:

Dashboard & Analytics Views

Route	View Description
/dashboard	Executive KPI overview, traffic trends, and live visitor counter
/dashboard/visitors	Unique visitor counts, returning rates, and device breakdowns
/dashboard/sessions	Session duration metrics, entrance/exit pages, and bounce rates
/dashboard/pages	Top content, URL performance, and real-time pageview logs
/dashboard/events	Telemetry events summary and custom event frequency
/dashboard/events/:name	Granular drilldown for specific telemetry event triggers
/dashboard/sources	Acquisition channels, referrers, and campaign attribution
/dashboard/geography	3D Visitor Network Globe and regional geographic metrics
/dashboard/live	Real-time live activity stream powered by WebSockets
/dashboard/alerts	Alert threshold rules, anomaly monitors, and notification logs
/dashboard/projects	Project directory, website switcher, and site configurations
/dashboard/activity	Workspace audit logs and administrator activity history
/dashboard/api-key	Project API key generation, revocation, and security tokens
/dashboard/billing	Subscription tiers, invoices, and payment receipts
/dashboard/settings	Sectioned workspace, account, and team settings hub
/share/:shareToken	Public, tokenized read-only analytics dashboard

Public & Marketing Views

Route	Description
/	Landing page featuring Dark Data Observatory and interactive globe
/features	Platform feature breakdown and technical specifications
/pricing	Subscription plans with monthly/annual billing toggle
/blog	Product updates, engineering notes, and release logs
/integrations	Supported third-party integrations and CMS plugins
/api	Interactive API documentation with syntax highlighting
/security	Security architecture, compliance, and encryption standards
/community	Open-source community channels and contributor links
/help	Knowledge base, FAQs, and support center
/docs	Comprehensive technical documentation hub

---

API Overview

WebPulse Analytics organizes its REST endpoints into structured resources:

Endpoint Base	Methods	Purpose
/api/track	POST, GET	Public tracking ingest, tracker script delivery, and live counts
/api/v1/analytics	GET	Dashboard summaries, time-series metrics, geo, and content stats
/api/v1/auth	POST, GET	User registration, login, logout, password reset, and Google OAuth
/api/v1/projects	GET, POST, PUT, DELETE	Workspace projects, tracking credentials, and share links
/api/v1/users	GET, PUT	Profile settings, notification preferences, and password updates
/api/v1/plans	GET	Available subscription tiers and resource quotas
/api/v1/payment	POST	Razorpay order creation, payment verification, and invoices
/api/v1/notifications	GET, PUT, DELETE	In-app user notifications and dispatch management
/api/v1/usage	GET	Current billing cycle event volume and plan quota consumption

For complete request/response schemas, refer to the API Reference.

---

Project Structure

Web-Pulse-Analytics/
├── backend/                  # Node.js & Express 5 API Server
│   ├── src/
│   │   ├── config/           # Environment and third-party service configs
│   │   ├── controllers/      # Route request handlers
│   │   ├── errors/           # Centralized AppError classes
│   │   ├── middlewares/      # Auth, CORS, Helmet, Rate Limiter, Error handling
│   │   ├── routes/           # REST route definitions (v1 + track)
│   │   ├── services/         # Business logic (analytics, email, payments)
│   │   ├── socket/           # Socket.IO visitor streaming setup
│   │   └── utils/            # Shared utilities (crypto, IP, formatters)
│   └── package.json
├── frontend/                 # React 19 + Vite Single-Page Application
│   ├── public/               # Static assets, branding, and icons
│   ├── src/
│   │   ├── components/       # Reusable UI primitives, App Shell, & Modals
│   │   │   └── ui/           # Unified v2 UI kit (Button, Card, DataTable, etc.)
│   │   ├── context/          # React Contexts (Theme, Toast, Project)
│   │   ├── hooks/            # Custom application hooks
│   │   ├── lib/              # Dual data service client (dataService.js)
│   │   ├── pages/            # 36+ Route views (Dashboard, Marketing, Auth)
│   │   ├── styles/           # Design system tokens (theme.css, app.css)
│   │   └── utils/            # API client and formatting helpers
│   └── package.json
├── supabase/                 # Supabase PostgreSQL Migrations
│   └── migrations/           # 6 Versioned SQL migration scripts
├── docs/                     # Detailed architectural and user guides
├── .github/                  # CI/CD Workflows, security scans, and templates
├── LICENSE                   # MIT License (Created Jan 17, 2026)
└── README.md                 # Project documentation

---

Documentation Directory

Deep dive into the architecture, deployment, and security of WebPulse Analytics:

• 📖 Getting Started Guide — Comprehensive local setup and configuration.
• 🏗️ Architecture Deep Dive — System design, data pipeline, and real-time streams.
• 📡 API Reference — Full REST endpoint documentation and parameters.
• 🔍 Tracking Guide — Client integration, bot protection, and custom events.
• 💾 Database Schema — Supabase PostgreSQL schema, tables, and RPC functions.
• 🔒 Security & Privacy — Hardening guide, CSP, RLS policies, and vulnerability reporting.
• 🚀 Deployment Guide — Production setup for Vercel, Render, Railway, or VPS.
• 🛠️ Troubleshooting — Common operational issues and solutions.
• 🗺️ Roadmap — Project milestones and release planning.

---

Security & Compliance

Security is a foundational pillar of WebPulse Analytics v2:

• Strict Content Security Policy: Dynamic CSP headers guarding against unauthorized scripts and connections.
• Row Level Security (RLS): Strict Supabase database policies preventing cross-tenant data leaks.
• Automated Security Pipelines: CodeQL static analysis, Gitleaks secret detection, and Dependabot automated vulnerability updates.
• Private Disclosure: If you uncover a security vulnerability, please review our Security Policy to report it privately.

---

Contributing & Community

We warmly welcome contributions from the community!

• Check out CONTRIBUTING.md to get started.
• Review our Code of Conduct to maintain an inclusive environment.
• Browse issues labeled good first issue to make your first contribution.

---

License

This project is licensed under the MIT License (Repository created on January 17, 2026).
See the LICENSE file for the full license text.