A lightweight, privacy-first web analytics platform designed to be simple to operate, easy to extend, and production-ready.

4Insights helps website owners understand how people use their sites — which pages are popular, how visitors move between pages, and what content works best — without spying on anyone.

It's designed so you can get started quickly: add a tiny snippet of code to your site, and the system collects anonymous, summary information that helps you improve your site.

• Privacy-First - No personal identifiers, no tracking cookies, no user profiling
• Lightweight - Minimal JavaScript tracker (~2KB gzipped)
• Self-Hosted - Full control over your data
• Real-Time - See metrics as they happen
• Simple - Easy to deploy and operate
• Extensible - Modular architecture with pluggable storage and auth

4Insights consists of four microservices:

┌─────────────┐
│   Browser   │
│  (Tracker)  │
└──────┬──────┘
       │ pageview events
       ↓
┌─────────────┐     ┌──────────────┐
│  Collector  │────→│ NDJSON Files │
│  (Deno)     │     │  (Storage)   │
└─────────────┘     └──────────────┘
       ↑
       │ metrics query
       │
┌─────────────┐     ┌──────────────┐
│  Dashboard  │────→│     Auth     │
│   Backend   │     │   Service    │
│   (BFF)     │     │   (Demo)     │
└──────┬──────┘     └──────────────┘
       │
       ↓
┌─────────────┐
│  Dashboard  │
│  Frontend   │
│ (SvelteKit) │
└─────────────┘

• Tracker - Client-side JavaScript snippet that captures pageviews
• Collector - Deno service that ingests, validates, and stores events
• Auth - Demo authentication service for API credentials and sessions
• Dashboard Backend (BFF) - Backend-for-frontend that validates tokens and aggregates metrics
• Dashboard Frontend - SvelteKit application for viewing analytics

• Deno v2.x+ (for backend services)
• Node.js >=18 (for frontend)
• Docker (optional, for containerized deployment)

git clone https://github.com/MalindiFrank/4insights.git
cd 4insights

# Copy example env files
cp auth/demo/server/.env.example auth/demo/server/.env
cp collector/.env.example collector/.env
cp dashboard/backend/.env.example dashboard/backend/.env
cp dashboard/frontend-new/.env.example dashboard/frontend-new/.env

# Using Make (recommended)
make start-all

# Or using Docker
docker-compose up

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

1. Click "Generate Credentials" to create an API key
2. Copy the API key and passphrase
3. Click "Login" and enter your credentials
4. View your analytics dashboard

• Development Guide - Local development setup and workflows
• Deployment Guide - Production deployment instructions
• Configuration Guide - Environment variables and runtime config
• CORS Fixes Guide - CORS implementation and troubleshooting

• Tracker - Client-side tracking snippet
• Collector - Event ingestion service
• Auth Service - Demo authentication
• Dashboard Backend - BFF service
• Dashboard Frontend - SvelteKit UI

# All services
make start-all

# Or in tmux (separate panes)
make dev-tmux

# All checks and tests
make verify

# Frontend type checking
cd dashboard/frontend-new && npm run check

# E2E tests
cd dashboard/frontend-new && npm run test:e2e

# Deno services
deno fmt
deno lint

# Frontend
cd dashboard/frontend-new && npm run check

# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

4Insights can be deployed to:

• Render.com - Recommended for Docker containers
• Fly.io - Great for global edge deployment
• Vercel - Frontend only (backend services elsewhere)

See Deployment Guide for detailed instructions.

All services use runtime environment variables - no rebuild needed when URLs change!

# Backend services (Deno)
AUTH_BASE_URL=http://localhost:8001
COLLECTOR_BASE_URL=http://localhost:8000

# Frontend (SvelteKit)
DASHBOARD_BACKEND_URL=http://localhost:8010
AUTH_SERVICE_URL=http://localhost:8001
COLLECTOR_URL=http://localhost:8000

# CORS Security (comma-separated allowed origins - no wildcards)
AUTH_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000,http://localhost:8010
BACKEND_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000
COLLECTOR_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000,http://localhost:8010

See Configuration Guide and CORS Fixes Guide for complete details.

4Insights is privacy-first by design:

• No personal identifiers - No cookies, no fingerprinting, no user tracking
• Anonymous data only - Aggregated pageviews and paths
• HTTPS required - Transport security for production
• Explicit CORS origins - No wildcards (*), only allowed origins accepted
• Credential support - Secure cross-origin requests with Access-Control-Allow-Credentials
• • API key scoping - Site-level access control
• • Rate limiting - Protection against abuse
• • Self-hosted - You control your data

Contributions are welcome! Please follow these guidelines:

1. Keep changes small - One logical change per PR
2. Add tests - Cover new functionality
3. Follow style - Use deno fmt and npm run check
4. Update docs - Keep documentation in sync

See Development Guide for setup instructions.

MIT License - see LICENSE file for details.

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs/

Built with using Deno, SvelteKit, and TypeScript