A Google Analytics alternative, written in node and typescript
  • TypeScript 95.5%
  • Shell 1.5%
  • HTML 1.4%
  • JavaScript 0.8%
  • CSS 0.5%
  • Other 0.3%
Find a file
2026-03-05 21:35:10 -05:00
backend fixes 2025-12-27 12:30:13 -05:00
frontend fixes 2026-03-05 21:35:10 -05:00
tracking fix double counting 2025-12-22 03:03:28 -05:00
.env.example first commit 2025-12-21 15:45:27 -05:00
.gitignore first commit 2025-12-21 15:45:27 -05:00
apply-migrations.sh finish new feature list 2025-12-25 20:38:57 -05:00
cleanup_duplicates.sh fix duplicate issue hopefully 2025-12-27 12:23:11 -05:00
cleanup_duplicates.sql fix duplicate issue hopefully 2025-12-27 12:23:11 -05:00
docker-compose.yml fix errors 2025-12-21 16:26:48 -05:00
IMPROVEMENTS.md new features 2025-12-21 22:13:14 -05:00
LICENSE first commit 2025-12-21 15:45:27 -05:00
Makefile first commit 2025-12-21 15:45:27 -05:00
NEW_FEATURES.md new features 2025-12-21 21:57:09 -05:00
README.md readme 2025-12-22 02:46:01 -05:00
test-tracking.html fix errors 2025-12-21 16:34:45 -05:00
UI_FEATURES.md new features 2025-12-21 22:13:14 -05:00

Analytics - Privacy-Respecting Web Analytics

Version 2.0.0

A modern, open-source, privacy-first analytics platform built as an alternative to Google Analytics. Track your website visitors without compromising their privacy.

Features

Core Analytics

  • Privacy-First: No cookies, anonymized IPs, no personal data collection
  • Beautiful Dashboard: Modern UI with dark mode and comprehensive visualizations
  • Multi-Website Support: Manage analytics for multiple websites from one dashboard
  • Real-Time Stats: See active visitors and live pageview data
  • Custom Events: Track user interactions beyond pageviews
  • Self-Hosted: Full control of your data with Docker deployment
  • Fast & Scalable: Built on PostgreSQL + TimescaleDB for time-series optimization

Engagement Analytics

  • Entry & Exit Pages: See where visitors land and where they leave
  • Return Visitor Tracking: New vs returning visitor metrics
  • Session Analytics: Page depth distribution and session flow analysis
  • Retention Metrics: Average visit days and sessions per visitor

Behavior Analytics

  • Scroll Depth Tracking: Monitor how far users scroll on pages
  • Click Heatmaps: Visualize where users click (coming soon)
  • User Experience Issues: Track rage clicks and dead clicks (coming soon)

Content Analytics

  • Page Performance: Detailed page statistics with time on page
  • Reading Progress: Track content engagement metrics (coming soon)
  • 404 Error Tracking: Monitor broken links and missing pages
  • Search Query Tracking: Internal site search analytics (coming soon)

Traffic Source Analytics

  • Referrer Analysis: See where your traffic comes from
  • UTM Campaign Tracking: Full campaign parameter support
  • Referrer Categories: Auto-categorized traffic sources (Search, Social, Direct, Email, Referral)
  • Traffic Patterns: Hourly/daily heatmap visualization

Advanced Features

  • IP Blocklist: Block IPs from tracking with visit attempt counter
  • Data Import/Export: CSV import/export for backup and migration
  • Dark Mode: Beautiful dark theme throughout the application
  • Form Analytics: Track form interactions and conversions
  • Custom Dashboards: Save and schedule reports (coming soon)
  • API Keys: Programmatic access to your analytics data
  • Team Collaboration: Multi-user support with annotations

Tech Stack

Backend

  • Node.js with TypeScript
  • Fastify - Fast and efficient web framework
  • PostgreSQL with TimescaleDB - Time-series optimized database
  • Redis - Caching and session management
  • Zod - Runtime type validation

Frontend

  • React with TypeScript
  • Vite - Lightning-fast build tool
  • TailwindCSS - Utility-first styling
  • Recharts - Beautiful, composable charts
  • React Query - Powerful data fetching
  • Zustand - Simple state management

Infrastructure

  • Docker & Docker Compose - Easy deployment
  • Nginx - Static file serving and routing

Quick Start

Prerequisites

  • Docker and Docker Compose
  • Node.js 20+ (for local development)

Installation

  1. Clone the repository

    git clone <your-repo-url>
    cd stats
    
  2. Create environment file

    cp .env.example .env
    
  3. Edit .env with secure values

    DB_PASSWORD=your_secure_password
    JWT_SECRET=your_jwt_secret_key
    API_URL=http://localhost:3000
    
  4. Start with Docker Compose

    docker-compose up -d
    
  5. Access the application

Local Development

Backend

cd backend
npm install
npm run dev

Frontend

cd frontend
npm install
npm run dev

Adding Tracking to Your Website

After creating a website in the dashboard:

  1. Copy the tracking code from the website management page
  2. Add it to your website's <head> section:
<script async defer data-website-id="YOUR_WEBSITE_ID" src="http://your-analytics-domain.com/tracker.js"></script>

Track Custom Events

// Track button clicks
document.querySelector('#signup-button').addEventListener('click', () => {
  window.analytics.track('signup_click', {
    plan: 'premium',
    source: 'homepage'
  });
});

// Track form submissions
window.analytics.track('newsletter_signup', {
  email_category: 'weekly'
});

API Endpoints

Authentication

  • POST /api/auth/register - Create account
  • POST /api/auth/login - Login
  • GET /api/auth/me - Get current user

Websites

  • GET /api/websites - List websites
  • POST /api/websites - Create website
  • GET /api/websites/:id - Get website
  • PUT /api/websites/:id - Update website
  • DELETE /api/websites/:id - Delete website

Statistics

  • GET /api/stats/overview - Overview statistics
  • GET /api/stats/timeseries - Time-series data
  • GET /api/stats/pages - Top pages
  • GET /api/stats/referrers - Top referrers
  • GET /api/stats/browsers - Browser breakdown
  • GET /api/stats/os - Operating system breakdown
  • GET /api/stats/devices - Device breakdown
  • GET /api/stats/countries - Geographic breakdown
  • GET /api/stats/realtime - Real-time active visitors
  • GET /api/stats/entry-pages - Entry (landing) pages
  • GET /api/stats/exit-pages - Exit pages with exit rates
  • GET /api/stats/retention - Return visitor metrics
  • GET /api/stats/page-depth - Pages per session distribution
  • GET /api/stats/traffic-patterns - Hourly/daily traffic heatmap
  • GET /api/stats/campaigns - UTM campaign analytics
  • GET /api/stats/referrer-categories - Categorized referrer sources

Tracking

  • POST /api/track/pageview - Track pageview
  • POST /api/track/event - Track custom event
  • POST /api/track/scroll - Track scroll depth
  • POST /api/track/click - Track clicks for heatmap

IP Blocklist

  • GET /api/blocklist - List blocked IPs
  • POST /api/blocklist - Add IP to blocklist
  • DELETE /api/blocklist/:id - Remove IP from blocklist

Import/Export

  • POST /api/import/umami - Import from Umami
  • POST /api/import/analytics - Import from CSV
  • GET /api/import/export/:websiteId - Export to CSV

Database Schema

The application uses PostgreSQL with TimescaleDB for efficient time-series data storage:

Core Tables

  • users - User accounts and authentication
  • websites - Tracked websites
  • pageviews - Pageview events (hypertable)
  • events - Custom events (hypertable)
  • session_paths - Session flow tracking

Analytics Tables

  • scroll_depth - Scroll tracking data
  • click_heatmaps - Click position data
  • form_analytics - Form interaction tracking
  • error_404 - Broken link tracking
  • search_queries - Site search tracking

Configuration Tables

  • ip_blocklist - Blocked IPs with attempt counter
  • api_keys - API access tokens
  • teams - Team management
  • team_members - Team member roles
  • custom_dashboards - Saved dashboards
  • saved_reports - Saved report configurations
  • user_preferences - User settings and themes
  • custom_branding - Custom logos and colors

Aggregates

  • pageviews_hourly - Hourly aggregates (continuous aggregate)
  • pageviews_daily - Daily aggregates (continuous aggregate)

Privacy Features

  1. No Cookies: Uses daily-rotated hashed visitor IDs
  2. IP Anonymization: IPs are hashed and never stored
  3. No Fingerprinting: Minimal browser data collection
  4. Country-Level Only: Geographic data limited to country
  5. Data Retention: Configurable retention policy (default: 2 years)
  6. GDPR Compliant: No personal data collection

Performance

  • TimescaleDB: Optimized for time-series queries
  • Continuous Aggregates: Pre-computed hourly/daily stats
  • Redis Caching: Fast repeated queries
  • Efficient Indexing: Optimized database indexes
  • Compression: Automatic data compression for old data

Umami Migration

To import data from Umami:

  1. Export your Umami data
  2. Use the import API endpoint:
curl -X POST http://localhost:3000/api/import/umami \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"websiteId": 1, "umamiData": [...]}'

Production Deployment

Security Checklist

  • Change default passwords in .env
  • Use strong JWT secret (32+ characters)
  • Enable HTTPS (use Let's Encrypt)
  • Configure firewall (only ports 80, 443)
  • Set up database backups
  • Configure log rotation
  • Enable rate limiting (already configured)
# docker-compose.prod.yml
version: '3.8'

services:
  db:
    restart: always
    volumes:
      - /var/lib/postgresql/data:/var/lib/postgresql/data

  redis:
    restart: always

  backend:
    restart: always
    environment:
      NODE_ENV: production

  frontend:
    restart: always

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx-prod.conf:/etc/nginx/nginx.conf
      - /etc/letsencrypt:/etc/letsencrypt

Recent Updates (v2.0.0)

New Features

  • ✅ Dark Mode - Full dark theme support
  • ✅ IP Blocklist - Block IPs with visit attempt tracking
  • ✅ CSV Import/Export - Backup and restore analytics data
  • ✅ Entry/Exit Pages - Landing and exit page analytics
  • ✅ Return Visitors - New vs returning visitor tracking
  • ✅ Page Depth - Session page count distribution
  • ✅ Traffic Patterns - Hourly/daily heatmap visualization
  • ✅ UTM Campaigns - Full campaign tracking
  • ✅ Referrer Categories - Auto-categorized traffic sources
  • ✅ Collapsible Navigation - Organized sidebar with sections
  • ✅ Scroll Tracking - Monitor scroll depth on pages
  • ✅ Click Heatmaps - Track click positions
  • ✅ Form Analytics - Form interaction tracking
  • ✅ 404 Tracking - Broken link monitoring
  • ✅ Team Collaboration - Multi-user support

Coming Soon

  • Email reports
  • Funnel analysis
  • A/B testing support
  • Goals and conversions
  • API webhooks
  • Rage click detection
  • Dead click detection
  • Reading progress tracking
  • Core Web Vitals
  • Page speed insights
  • Mobile app

Contributing

Contributions are welcome! Please follow these steps:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

MIT License - feel free to use this for any purpose.

Support

  • GitHub Issues: Report bugs and feature requests
  • Documentation: See /docs folder (coming soon)

Acknowledgments

Built with inspiration from:

  • Umami Analytics
  • Plausible Analytics
  • Matomo (formerly Piwik)

Made with privacy in mind