🚀 Vibe Coding Kit

You are building a Mixpanel-like analytics platform for indie developers.

REQUIREMENTS:
- Event Ingestion API: Accept POST /api/events with {userId, eventName, properties, timestamp}
- Queue Processing: Use Redis/SQS to buffer events before storage
- Database: Store events in ClickHouse (or TimescaleDB as fallback)
- JavaScript SDK: Auto-track pageviews, clicks, form submissions, custom events
- Dashboard: Real-time analytics with charts for:
  * Event counts over time (line chart)
  * Top events (bar chart)
  * Unique users per day (trend)
  * Funnels (multi-step conversion tracking)
  * Retention cohorts (day 1, day 7, day 30 retention)
  * User segmentation (filter by properties)
- API: GraphQL or REST endpoints for querying analytics
- Auth: Simple API key authentication
- Data Retention: Configurable, default 90 days

TECH STACK:
- Backend: Next.js API routes or Fastify
- Queue: Upstash Redis or AWS SQS
- Database: ClickHouse (primary) or TimescaleDB (fallback)
- Frontend: React + Tremor + Recharts
- SDK: Vanilla JS, ~2-3KB minified, no dependencies

ARCHITECTURE:
1. Client sends events via lightweight JS snippet
2. Events hit the ingestion API (/api/events)
3. API validates and pushes to Redis queue
4. Background worker pulls from queue, batches events
5. Batch insert into ClickHouse
6. Dashboard queries ClickHouse for real-time analytics
7. GraphQL/REST API serves data to frontend

FEATURES TO BUILD (Priority Order):
1. **Event Ingestion**
   - Accept events at high volume
   - Batch writes to database
   - Handle duplicate detection (idempotent)
   - Track event timestamp, userId, properties

2. **JavaScript SDK**
   - Auto-track pageviews (document.location)
   - Auto-track clicks on data-analytics-event elements
   - Custom event API: analytics.track('event_name', {prop: value})
   - Auto-batch and send every 5 seconds or when buffer hits 50 events
   - Persist in localStorage to handle offline

3. **Funnel Analysis**
   - Define a series of steps (e.g., signup → verify_email → first_purchase)
   - Track drop-off at each step
   - Show conversion rate % and absolute counts
   - Support date range filtering

4. **Retention Cohorts**
   - Cohort by signup date or any event
   - Track % of users active on day 1, 7, 14, 30
   - Visualize cohort retention curves
   - Compare cohorts over time

5. **User Segmentation**
   - Filter users by properties (country, plan, signup_source, etc.)
   - Save segments as reusable filters
   - Show segment size and retention
   - Analyze event patterns within segments

6. **Real-Time Dashboard**
   - Event counts with sparklines
   - Live user count (users seen in last 5 minutes)
   - Top events happening right now
   - System status (events/sec, queue depth)

FEATURES TO SKIP (for MVP):
- Predictive analytics, anomaly detection, ML models
- Custom cohort builder UI (use raw SQL)
- White-label / multi-tenant
- Advanced attribution
- Heatmaps / session recording

DATABASE SCHEMA:
```sql
CREATE TABLE events (
  event_id UUID,
  project_id String,
  user_id String,
  event_name String,
  properties JSON,
  timestamp DateTime,
  date Date,
  country String,
  device String
) ENGINE = MergeTree()
ORDER BY (project_id, user_id, timestamp)
PARTITION BY date;
```

CODE STYLE:
- TypeScript everywhere
- Zod for validation
- Clear error messages
- Logging for debugging
- Unit tests for core logic

PERFORMANCE:
- Ingest 10k events/sec minimum
- Query response <500ms for 90-day range
- Dashboard load in <2 seconds
- SDK injection time <50ms

Start with the event ingestion API and SDK. Then build the storage layer. Finally, add the dashboard and analysis features.

This should take 2-3 weeks for a solid MVP.