How to vibe codePiwik PRO

Prerequisites

• Node.jsfree

  Required for running the Next.js development environment and building the full-stack application.

• GitHubfree

  Version control and deployment pipeline integration.

AI coding tools

• Claude Code

  Agentic terminal coding tool capable of scaffolding the complete full-stack analytics engine and writing complex database queries.

• Cursor

  AI-native editor for refining dashboard visualization components and tag manager rule builder interfaces.

Build guide

1. 01Project Scaffolding and Database Schema Setup

   Initialize the Next.js application with Tailwind CSS, configure Neon Postgres connection, and establish tables for tenants, sites, tracking events, tag rules, and consent preferences.

   Initialize a new Next.js 16 project with TypeScript and Tailwind CSS v4. Set up Drizzle ORM connected to Neon Postgres. Create the core database schema for an analytics suite: a 'sites' table (id, name, domain, created_at), an 'events' table (id, site_id, visitor_id, session_id, event_type, url, referrer, properties JSONB, timestamp), a 'tags' table (id, site_id, name, trigger_rules JSONB, code_snippet, enabled), and a 'consent_preferences' table (id, visitor_id, site_id, categories JSONB, updated_at). Ensure proper foreign key constraints, indexes on (site_id, timestamp) for event aggregation queries, and write comprehensive migration files. Include acceptance criteria verifying connection and successful schema migration.

   ⧉copy promptopen in Claude CodeCopen in Codexopen in Cursor

2. 02Authentication & Multi-Site Dashboard Shell

   Implement authentication using better-auth and build the main analytics dashboard shell allowing users to create sites and view high-level project settings.

   Implement better-auth in the Next.js app supporting email/password sign-in and user session management. Build a protected dashboard layout with a sidebar navigation ('Analytics', 'Tag Manager', 'Consent Manager', 'Settings'). Create a site-switcher component in the header that fetches the authenticated user's sites from Neon, allows creating a new site via a modal form, and stores the active site ID in React context or URL params. Ensure all API endpoints validate user ownership of the selected site. Write robust error handling for unauthenticated states and database timeouts.

   ⧉copy promptopen in Claude CodeCopen in Codexopen in Cursor

3. 03Client-Side Tracking Script & Ingestion Endpoint

   Develop a lightweight JavaScript tracking snippet and an asynchronous backend ingestion endpoint to capture pageviews and custom events securely.

   Build a high-performance, lightweight client-side tracking script (tracker.js) that can be embedded on external websites. The script should automatically capture pageviews, referrers, screen resolution, and allow manual tracking via window.piwikClone.push(). It must send data via a beacon or fetch POST request to an API endpoint at /api/collect. Implement the backend route /api/collect in Next.js: parse incoming payloads, validate site tokens, sanitize IP addresses (anonymize by zeroing the last octet for GDPR compliance), and batch insert event records into the Neon 'events' table. Add CORS headers to permit cross-origin tracking requests while handling rate limiting and malformed payloads gracefully.

   ⧉copy promptopen in Claude CodeCopen in Codexopen in Cursor

4. 04Analytics Reporting Engine and Dashboards

   Create analytical aggregation queries and UI views displaying traffic trends, top pages, referrers, and conversion funnels over customizable date ranges.

   Build the Analytics module dashboard in Next.js. Create backend SQL aggregation queries using Drizzle to compute: total pageviews, unique visitors, bounce rate, top landing pages, and referral sources grouped by day and time range. Build responsive UI charts and data tables using Tailwind CSS and lightweight charting components. Implement date-range picker filters (last 7 days, 30 days, custom range) that pass parameters to the API routes. Ensure queries execute efficiently against the indexed events table without memory exhaustion. Add export-to-CSV functionality for raw event summaries.

   ⧉copy promptopen in Claude CodeCopen in Codexopen in Cursor

5. 05Tag Manager (PPMS) & Script Injector

   Build a tag management interface allowing users to define custom tracking tags and trigger rules, paired with a dynamic script delivery endpoint.

   Develop the Tag Manager interface where users can create, edit, and toggle custom tags (HTML/JS snippets) and configure trigger rules (e.g., URL contains '/checkout', event equals 'purchase'). Build a script delivery endpoint at /js/container-[siteId].js that dynamically compiles and serves the active tags and triggers for a given site as a single minified JavaScript bundle. The delivered container script must evaluate trigger rules client-side before executing injected tags. Implement a preview mode toggle in the dashboard that appends a debug logging wrapper to the injected container for testing deployments safely.

   ⧉copy promptopen in Claude CodeCopen in Codexopen in Cursor

6. 06Consent Manager (CMP) & Data Activation Rules

   Implement a cookie consent banner widget to capture user preferences and a basic data activation rule engine to trigger actions based on visitor segments.

   Build a Consent Manager Platform (CMP) module. Create a customizable cookie banner component that visitors see on tracked sites, offering granular opt-in categories (Analytics, Marketing, Functional). Store consent choices in local storage and sync them back to the 'consent_preferences' table via API. Modify the tracking script and tag manager loader to check consent state before firing scripts or recording behavioral data. Additionally, build a basic Data Activation rules engine in the dashboard: allow users to set up simple real-time triggers (e.g., if user views cart > 3 times, display a targeted banner hook or export webhook payload to an external URL). Test the end-to-end flow from consent banner interaction to downstream activation trigger.

   ⧉copy promptopen in Claude CodeCopen in Codexopen in Cursor

Cost vs paying for Piwik PRO