A privacy-first, high-performance web analytics platform delivering click heatmaps, session replays, and funnel analytics through a single JavaScript snippet.
✅ Phase 1 Foundation (Complete)
- SDK core with event collection (clicks, page views, scroll tracking)
- Session management with 30-minute timeout
- Event batching and transport layer
- Privacy features (DNT respect, data masking)
- Monorepo structure with TypeScript
⏳ Still Needed
- Cloudflare Workers for data ingestion
- ClickHouse database setup
- Next.js dashboard
- Session replay (Phase 2)
- Funnel analytics (Phase 3)
Before you begin, you'll need accounts for these services:
-
Cloudflare (for Workers & R2 storage)
- Sign up at cloudflare.com
- You'll need your Account ID and API Token
-
ClickHouse Cloud (for analytics data)
- Sign up at clickhouse.cloud
- Create a new service and get connection details
-
Neon (for PostgreSQL metadata)
- Sign up at neon.tech
- Create a new project and get the connection string
-
Vercel (for dashboard hosting)
- Sign up at vercel.com
- Connect your GitHub account
# Clone the repository
git clone https://github.com/jonathanleane/Tapistry.git
cd Tapistry
# Install dependencies
npm installCreate a .env file in the root:
# Cloudflare
CF_ACCOUNT_ID=your_account_id
CF_API_TOKEN=your_api_token
R2_ACCESS_KEY_ID=your_r2_access_key
R2_SECRET_ACCESS_KEY=your_r2_secret_key
# ClickHouse Cloud
CLICKHOUSE_HOST=your_host.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your_password
# Neon PostgreSQL
DATABASE_URL=postgresql://user:pass@host/dbname
# Dashboard (for local development)
NEXTAUTH_SECRET=generate_a_secret_here
NEXTAUTH_URL=http://localhost:3000# Build shared types first
npm run build:shared
# Build the SDK
npm run build:sdk
# The SDK will be available at packages/sdk/dist/tapistry.jsThe SDK needs an ingestion endpoint to send data to. Create the Cloudflare Worker:
# Navigate to edge package
cd packages/edge
# Create the worker files (TODO: implement these)
# - src/index.ts (main worker)
# - src/routes/ingest.ts (handles /i endpoint)
# - src/validation.ts (validates events)
# - wrangler.toml (Cloudflare config)
# Deploy to Cloudflare
npx wrangler deploy-- Run these in your ClickHouse Cloud console
-- See migrations/clickhouse/001_initial.sql (needs to be created)-- Run these in your Neon console
-- See migrations/postgres/001_initial.sql (needs to be created)Create a test HTML file:
<!DOCTYPE html>
<html>
<head>
<title>Tapistry Test</title>
</head>
<body>
<h1>Testing Tapistry Analytics</h1>
<button id="test-button">Click Me</button>
<!-- Tapistry SDK -->
<script>
(function(w,d,s,u,k){w.tapistry=w.tapistry||function(){(w.tapistry.q=w.tapistry.q||[]).push(arguments)};
var js=d.createElement(s);js.async=1;js.src=u;js.dataset.project=k;
d.head.appendChild(js);
})(window,document,'script','./packages/sdk/dist/tapistry.js','YOUR_PROJECT_KEY');
tapistry('config', {
apiUrl: 'http://localhost:8787', // Your local Cloudflare Worker
debug: true
});
</script>
</body>
</html>cd packages/dashboard
# Create Next.js app structure (TODO)
# Implement pages:
# - Overview
# - Heatmaps
# - Session Replays
# - Funnels
npm run dev
# Dashboard will be at http://localhost:3000Tapistry/
├── packages/
│ ├── sdk/ ✅ Client-side JavaScript SDK
│ ├── shared/ ✅ Shared TypeScript types
│ ├── edge/ ❌ Cloudflare Workers (TODO)
│ └── dashboard/ ❌ Next.js dashboard (TODO)
├── migrations/
│ ├── clickhouse/ ❌ ClickHouse schemas (TODO)
│ └── postgres/ ❌ Neon schemas (TODO)
├── plan.md ✅ Detailed technical specification
├── CLAUDE.md ✅ AI development guide
└── README.md ✅ This file
# Run all tests
npm test
# Run specific package tests
npm run test --workspace=@tapistry/sdk
# Check bundle size
npm run size --workspace=@tapistry/sdk- ✅ Event collection (clicks, page views, scroll)
- ✅ Session management
- ✅ Event batching
- ✅ SPA route detection
- ✅ Privacy controls (DNT, masking)
- ❌ Session replay recording
- ❌ Custom event tracking
- ❌ User identification
- ❌ Cloudflare Worker ingestion
- ❌ ClickHouse event storage
- ❌ PostgreSQL metadata
- ❌ R2 replay storage
- ❌ Dashboard UI
- ❌ Authentication system
This project is in active development. The Phase 1 SDK foundation is complete, but the backend infrastructure and dashboard still need to be built.
Priority tasks:
- Implement Cloudflare Worker for data ingestion
- Set up ClickHouse schemas and materialized views
- Create basic dashboard with heatmap viewer
- Add authentication system
See plan.md for the complete technical specification.
Private project - not yet licensed for public use.
- Check browser console for errors
- Verify project key is set
- Ensure Cloudflare Worker is deployed
- Check SDK debug mode:
tapistry('debug', true) - Verify ingestion endpoint is accessible
- Check browser network tab for failed requests
- Run
npm run cleanand reinstall - Ensure Node.js >= 18.0.0
- Check TypeScript errors:
npm run typecheck
- Technical Specification - Complete project plan
- Development Guide - AI assistant context
- Cloudflare Workers Docs
- ClickHouse Docs
- Next.js Docs