Visitor Analytics

Visitor Analytics provides PuppyPad members with privacy-focused insights into site traffic. The system tracks page views and referring domains without using cookies or storing IP addresses. Site owners view statistics for the last 30 days via a dedicated dashboard.

Sources: PLAN.md:204-208, README.md:16-19, src/views.js:464-474

Data Collection Logic

The application tracks views within the site router when a visitor requests a member page. The system filters out search engine robots and crawlers by checking the User-Agent header against a predefined list of bot patterns.

Tracking Criteria

For a request to trigger an analytics update, it must meet the following conditions:

• The HTTP method is GET.
• The response status is 200 OK or 304 Not Modified.
• The User-Agent does not match the BOT_UA regular expression.
• The requested file has an .html or .htm extension.

Sources: src/server.js:52-53, src/server.js:256-271, test/app.test.js:487-502

Bot Filtering

The system uses the BOT_UA constant to identify non-human traffic. This pattern matches common strings such as "bot", "crawl", "spider", "slurp", "preview", and "headless".

Sources: src/server.js:52

Flow of Collection

The following diagram illustrates the lifecycle of a page request and the subsequent update to the analytics database.

The system records the path (truncated to 200 characters) and the referring host (truncated to 200 characters).

Sources: src/server.js:256-275

Database Schema

PuppyPad uses two primary SQLite tables to persist analytics data. These tables aggregate views by user, day, and specific attribute (path or host).

Analytics Tables

Sources: src/server.js:272-274, test/app.test.js:500-502

Hit Counter

In addition to detailed analytics, a global hit counter exists for each site. This counter increments when a visitor loads a page, restricted to one increment per IP address per hour. Members can display this as a widget using an SVG image.

Sources: src/server.js:203-210, src/widgets.js:31-35

Data Retention and Housekeeping

PuppyPad maintains analytics data for a rolling 30-day window. An automated housekeeping process runs every hour to remove expired records.

Retention Policy

• Page Views/Referrers: Deleted after 30 days.
• Guestbook/Report IPs: Deleted after 90 days.
• Housekeeping Interval: Every 3600000ms (1 hour).

Sources: src/server.js:54-55, src/server.js:907-913, src/server.js:941

Member Dashboard Integration

Owners access analytics through the /dashboard/stats route. The view displays three distinct categories of data:

1. Views per day: A summary of total page views over the last 30 days.
2. Top pages: A ranked list of the most visited paths on the site.
3. Referrers: A ranked list of external websites where visitors originated.

Sources: src/views.js:464-474, src/server.js:770-778

Analytics View Logic

The server fetches stats using SQL aggregations:

SELECT day, SUM(views) views FROM page_views 
WHERE user_id = @id AND day >= @since 
GROUP BY day ORDER BY day DESC;

Sources: src/server.js:774-776

Summary

The Visitor Analytics system provides a compromise between meaningful traffic data and user privacy. By aggregating data by date and domain rather than tracking individual users, PuppyPad ensures site owners understand their audience without violating visitor privacy or requiring complex cookie consent mechanisms.

Sources: README.md:16-19, src/views.js:466-468