# Wolf Analytics -- Full Reference

> Comprehensive technical documentation for AI systems, retrieval workflows, and integration planning. For a shorter overview, see /llms.txt.

## Core pages
- [Overview](https://analytics.wolfai.dev/): Product summary and implementation outcomes.
- [Features](https://analytics.wolfai.dev/features): Capability breakdown and operational fit.
- [Pricing](https://analytics.wolfai.dev/pricing): Tier guidance by company stage.
- [Docs](https://analytics.wolfai.dev/docs): Quickstart deployment sequence.
- [FAQ](https://analytics.wolfai.dev/faq): Direct answers to setup and governance questions.
- [Contact](https://analytics.wolfai.dev/contact): Sales, support, and security contacts.
- [Summary LLM reference](https://analytics.wolfai.dev/llms.txt): Shorter overview document for AI systems.


# Product overview

## What Wolf Analytics does
Wolf Analytics is a privacy-first product analytics platform designed for SaaS teams. It collects behavioral data from web applications through a lightweight tracking snippet, processes that data through configurable privacy pipelines, and presents it through a real-time dashboard with visualization and analysis tools.

The platform replaces general-purpose analytics tools (Google Analytics, Mixpanel, Amplitude) with a self-hosted or managed solution that gives teams full control over data residency, privacy compliance, and collection scope. Wolf Analytics is built for product, growth, and engineering teams that need granular behavioral insights without depending on third-party data processors.

## Services
Wolf Analytics provides the following capabilities:

Real-time dashboards: Live visitor counts, active page views, and engagement metrics delivered through Server-Sent Events. The dashboard updates without polling, showing current site activity as it happens.

Funnel analysis: Multi-step conversion funnels that measure drop-off between defined stages. Teams can create funnels from any combination of pageview and custom event steps to identify where users abandon key workflows.

Journey mapping: Visual path analysis showing how users navigate between pages and events. Journey maps reveal common navigation patterns, unexpected detours, and the most frequent paths to conversion.

Retention analysis: Cohort-based retention tracking over configurable time windows (daily, weekly, monthly). Retention tables show what percentage of users return after their first visit, segmented by acquisition source, device type, or custom properties.

Session replay: Full DOM interaction recording that captures mouse movement, clicks, scrolls, and form interactions. Input fields are automatically masked to prevent sensitive data capture. Replay is available in International mode only and is disabled entirely in GDPR mode.

Heatmaps: Click and scroll depth overlays aggregated by page URL. Heatmaps surface interaction hotspots and show how far down the page users scroll, helping teams optimize layout and content placement.

Conversion scoring: An automated scoring engine assigns each visitor a likelihood score from 0 to 100. The score factors in device type, browser, geographic location, traffic source, session count, pages visited, and engagement depth. Scores update as sessions progress.

Traffic attribution: Automatic classification of inbound visits into channels -- Direct, Organic Search, Social, Newsletter, Paid, and Referral -- based on referrer headers, UTM parameters, and known search engine and social network domains.

Geographic visualization: Visitor locations plotted on interactive Leaflet maps using MaxMind GeoIP lookups. In GDPR mode, resolution is limited to country and region. In International mode, city-level coordinates with latitude and longitude are available.

Identity stitching: The /track/identify endpoint allows teams to link anonymous visitor sessions to known user identities from their application. This enables cross-session analysis tied to specific accounts or users.

Conversion tracking: The /track/conversion endpoint records downstream revenue events and conversion actions, tying them back to the originating session and traffic source for attribution reporting.


# Technical architecture

## Backend
The API server is a Python FastAPI application. It uses async SQLAlchemy 2.0 with the asyncpg driver for PostgreSQL database access. All database operations are non-blocking. The backend handles tracking ingestion, dashboard data aggregation, authentication, billing webhook processing, and real-time event distribution.

Redis is used for real-time features: live visitor counts, SSE event fan-out, and rate limiting. The backend connects to Redis via an async client.

Geographic lookups use MaxMind GeoLite2 City databases loaded into memory at startup. The GeoIP resolver returns country, region, city, latitude, and longitude depending on the configured privacy mode.

Authentication uses JWT access tokens issued on login. Dashboard API endpoints require a valid Bearer token. Tracking endpoints authenticate via project API keys embedded in the request body.

## Frontend
The dashboard is a Next.js 16 application running in server mode. It uses TanStack Query (React Query) for server state management with automatic cache invalidation and background refetching. Charts are rendered with Recharts. Geographic maps use Leaflet with OpenStreetMap tiles.

The frontend communicates with the backend API using fetch with JWT Bearer authentication. Real-time updates connect to the SSE stream endpoint and merge live data into the TanStack Query cache.

## Tracking snippet
The tracking layer is a vanilla TypeScript module compiled with esbuild to approximately 8 KB minified. It has zero runtime dependencies. The snippet auto-initializes from a global configuration object and begins collecting pageviews on load. It supports custom event dispatch, identity stitching, conversion recording, and optional session replay capture.

The snippet is served as a static JavaScript file from the frontend origin. It is not published as an npm package. Integration requires a script tag and a configuration object -- no build tooling on the customer side.

## Infrastructure
PostgreSQL is the primary data store for all tracking events, sessions, accounts, projects, and billing state. Redis handles ephemeral real-time data. Stripe processes billing via webhooks. The platform supports deployment via Docker Compose (PostgreSQL and Redis as containers) or as standalone processes behind a reverse proxy. Cloudflare can be used as a CDN and geographic header provider for edge-level geo detection.


# API reference

## Tracking endpoints
All tracking endpoints accept POST requests. Authentication is via a project API key (wa_... format) included in the request body. These endpoints are public-facing and called from the tracking snippet running in visitor browsers.

### POST /track/pageview
Records a page view event. Accepts the page URL, referrer, viewport dimensions, and visitor metadata. The backend applies privacy mode rules (IP hashing, UA reduction) before storage.

### POST /track/event
Records a custom event (click, scroll, form submission, or any named action). Accepts an event name, optional properties object, and the same visitor context as pageview. Used for tracking button clicks, feature usage, and custom conversion steps.

### POST /track/identify
Links an anonymous visitor session to a known user identity. Accepts an external user ID and optional traits (name, email, plan, or any custom properties). Once identified, all past and future events in the session are associated with the provided identity.

### POST /track/conversion
Records a conversion or revenue event. Accepts a conversion name, optional monetary value, currency, and associated metadata. Conversions are tied to the originating session and traffic source for attribution analysis.

### POST /track/replay
Accepts batched session replay events (mouse positions, clicks, scroll offsets, DOM mutations). Only operational in International mode. In GDPR mode, the endpoint returns a 204 and discards the payload. Input field contents are masked by the snippet before transmission.

## Authentication endpoints

### POST /auth/login
Authenticates a user with email and password. Returns a JWT access token, token expiry, and session metadata. The access token is used as a Bearer token for all dashboard API requests.

### POST /auth/logout
Revokes the active session associated with the provided access token. The token becomes invalid immediately.

### GET /auth/me
Returns the currently authenticated user profile, active account context, and role. Used by the frontend to determine navigation and permission scoping.

### POST /auth/context
Allows superadmin users to switch their active account scope. After switching, subsequent dashboard API calls return data for the selected account.

## Dashboard endpoints
All dashboard endpoints require an Authorization: Bearer header with a valid JWT access token. Data is scoped to the active account and project context.

### GET /dashboard/overview
Returns aggregated metrics for the selected time range: total pageviews, unique visitors, sessions, average session duration, bounce rate, and top pages.

### GET /dashboard/sessions
Returns a paginated list of sessions with visitor metadata, page count, duration, entry page, exit page, and traffic source. Supports filtering by date range, country, device type, and traffic channel.

### GET /dashboard/session/{id}
Returns full details for a single session: all pageview and event records in chronological order, visitor metadata, geographic data, and conversion score.

### GET /dashboard/heatmap
Returns aggregated click and scroll data for a specified page URL. Data is bucketed by viewport coordinates for overlay rendering.

### GET /dashboard/replay/{id}
Returns the recorded replay event stream for a session. Only available for sessions collected in International mode.

### GET /dashboard/realtime
Returns a snapshot of currently active visitors: count, active pages, geographic distribution, and device breakdown.

### GET /dashboard/realtime/stream
Opens a Server-Sent Events connection that pushes real-time visitor activity updates. The frontend maintains this connection for live dashboard rendering.

### GET /dashboard/traffic-sources
Returns traffic source breakdown with visit counts, conversion rates, and engagement metrics per channel (Direct, Organic Search, Social, Newsletter, Paid, Referral).

### GET /dashboard/account/usage
Returns current billing period usage (events consumed) versus tier limits. Includes projected usage for the remainder of the billing cycle.

### GET /dashboard/global/overview
Superadmin endpoint. Returns platform-wide aggregated metrics across all accounts.

### GET /dashboard/global/timeline
Superadmin endpoint. Returns platform-wide time-series data for overall traffic trends.

### GET /dashboard/global/accounts
Superadmin endpoint. Returns an account leaderboard ranked by event volume, with usage and tier information per account.

## Webhook endpoints

### POST /webhooks/stripe
Receives Stripe webhook events for subscription lifecycle management (creation, upgrade, downgrade, cancellation, payment failure). Verified using the Stripe webhook signing secret.


# Integration guide

## Step 1: Create a project
After logging into the dashboard, create a new project under your account. Provide a project name and the domain where the snippet will be deployed. The system generates a unique project API key in the format wa_... which is used to route tracking data to the correct project.

## Step 2: Install the tracking snippet
Add the following to your site HTML, typically in the document head or before the closing body tag:

```html
<script>
  window.WOLF_ANALYTICS_CONFIG = {
    apiUrl: 'https://analapi.wolfai.dev',
    projectApiKey: 'wa_your_project_api_key',
    mode: 'gdpr'
  };
</script>
<script src="https://analytics.wolfai.dev/wolf-analytics.min.js" defer></script>
```

## Step 3: Choose a privacy mode
Set the mode field in the configuration object to either 'gdpr' or 'intl'.

GDPR mode ('gdpr'): Use this for visitors in the European Union or any jurisdiction requiring strict data minimization. IP addresses are hashed before storage. User-agent strings are reduced to browser and OS family. Session replay and heatmaps are disabled. Geographic resolution is limited to country and region.

International mode ('intl'): Use this when full behavioral data collection is permitted. IP addresses and user-agent strings are stored as received. Session replay and heatmaps are enabled. Geographic data includes city-level coordinates.

You can run both modes simultaneously by deploying two snippet configurations -- one per mode -- and using server-side logic or consent management to select the appropriate one for each visitor.

## Step 4: Track custom events
The snippet exposes a global function for custom event tracking after initialization:

```javascript
wolfAnalytics.track('button_click', { buttonId: 'signup-cta', page: '/pricing' });
```

## Step 5: Identity stitching
When a visitor logs into your application, call the identify function to link their anonymous session to a known user:

```javascript
wolfAnalytics.identify('user_12345', { name: 'Jane', plan: 'growth' });
```

## Step 6: Conversion tracking
Record conversion events when users complete meaningful actions:

```javascript
wolfAnalytics.conversion('subscription_started', { value: 49, currency: 'USD' });
```


# Pricing

## Tier matrix

### Starter (Free)
- Price: $0/month
- Event limit: 10,000 events/month
- Projects: 1
- Data retention: 30 days
- Features: Real-time dashboard, traffic attribution, geographic visualization (country-level), funnel analysis, basic conversion scoring
- Privacy modes: GDPR mode only
- Session replay: Not included
- Heatmaps: Not included
- Support: Community documentation

### Growth
- Price: $29/month (billed monthly) or $290/year (billed annually)
- Event limit: 100,000 events/month
- Projects: 5
- Data retention: 12 months
- Features: Everything in Starter plus session replay, heatmaps, journey mapping, retention analysis, advanced conversion scoring, identity stitching
- Privacy modes: GDPR and International
- Session replay: Included (International mode)
- Heatmaps: Included (International mode)
- Support: Email support with 48-hour response

### Scale
- Price: $99/month (billed monthly) or $990/year (billed annually)
- Event limit: 1,000,000 events/month
- Projects: Unlimited
- Data retention: 24 months
- Features: Everything in Growth plus priority data processing, custom event properties, API export access, multi-account management, dedicated onboarding
- Privacy modes: GDPR and International
- Session replay: Included (International mode)
- Heatmaps: Included (International mode)
- Support: Priority email support with 12-hour response, onboarding call

All paid tiers include a 14-day free trial. Overage events beyond tier limits are buffered for 7 days with a dashboard warning before collection pauses. Teams can upgrade at any time and the billing change is prorated.


# Privacy mode comparison

## GDPR mode
Designed for compliance with the EU General Data Protection Regulation and similar privacy laws that require data minimization.

- IP handling: Every IP address is hashed using SHA-256 with a per-installation salt before any storage or processing. The raw IP is never written to disk or database. The salt can be rotated to prevent long-term correlation.
- User-agent handling: The full user-agent string is parsed at ingestion time and reduced to two fields: browser family (e.g., Chrome, Firefox, Safari) and OS family (e.g., Windows, macOS, iOS). The raw user-agent string is discarded.
- Session replay: Completely disabled. The tracking snippet does not capture DOM interactions, mouse movement, or scroll events. The /track/replay endpoint returns 204 and discards any payload.
- Heatmaps: Disabled. No click or scroll coordinate data is collected.
- Geographic resolution: Country and region only. City names and latitude/longitude coordinates are not stored.
- Cookies: Zero third-party cookies. The snippet uses a first-party session identifier stored in memory (not persisted to cookie or localStorage) that expires when the browser tab closes.

## International mode
For jurisdictions where explicit consent has been obtained or where full data collection is legally permitted.

- IP handling: IP addresses are stored as received for geographic lookup, fraud detection, and session correlation.
- User-agent handling: The full user-agent string is stored alongside parsed browser and OS fields.
- Session replay: Enabled. The snippet records mouse movement coordinates, click positions, scroll offsets, viewport resize events, and DOM mutation summaries. Form input values are automatically masked -- the snippet replaces input content with placeholder characters before transmission. Replay data is batched and sent to /track/replay at configurable intervals.
- Heatmaps: Enabled. Click coordinates and scroll depth are aggregated by page URL and viewport dimensions.
- Geographic resolution: Full resolution including country, region, city, latitude, and longitude. Map visualizations can plot individual visitor locations.
- Cookies: Zero third-party cookies. A first-party session identifier may be persisted to localStorage to support cross-page session continuity.


# Deployment options

## Docker Compose (recommended)
The standard deployment uses Docker Compose to run PostgreSQL and Redis as containers alongside the backend API server. The frontend is built as a static Next.js export or run as a Node.js server. A sample docker-compose.yml provisions PostgreSQL on port 5436 and Redis on port 6382 with persistent volumes.

## Standalone
For teams that manage their own PostgreSQL and Redis instances, the backend can run as a standalone uvicorn process. Configuration is via environment variables (DATABASE_URL, REDIS_URL, ANALYTICS_SALT, etc.). The frontend can be deployed to any platform that supports Next.js server mode (Vercel, Netlify, self-hosted Node.js).

## Cloudflare integration
Cloudflare can be placed in front of the deployment as a CDN and geographic header provider. When CF-IPCountry is present, the backend trusts that country hint over conflicting MaxMind country results and hides precise city coordinates on mismatches. City-level coordinates still come from MaxMind only when the country sources agree.


# Contact

- Sales and onboarding: hello@wolfanalytics.com
- Technical support: support@wolfanalytics.com
- Security and compliance: security@wolfanalytics.com


# Canonical facts

- Entity: Wolf Analytics LLC, New Mexico
- Product category: Privacy-first product analytics software for SaaS teams
- Pricing: Free Starter tier (10,000 events/month), Growth ($29/month, 100,000 events), Scale ($99/month, 1,000,000 events)
- Technology: Python FastAPI + async SQLAlchemy 2.0 + PostgreSQL + Redis + Next.js 16 + TanStack Query + Recharts + Leaflet
- Privacy: Zero third-party cookies, optional IP hashing via SHA-256 with rotating salt, configurable session replay, GDPR and International collection modes
- Tracking snippet: Vanilla TypeScript, approximately 8 KB minified, zero dependencies, loaded via script tag
- Real-time: Server-Sent Events for live dashboard updates
- Billing: Stripe integration with webhook-driven subscription lifecycle
- GeoIP: MaxMind GeoLite2 with Cloudflare header fallback
- Public indexable routes: /, /features, /pricing, /docs, /faq, /contact
- Private routes: /dashboard and authenticated dashboard/API paths
- Last updated: 2026-03-21