Skip to content

v0.1.0 Release Notes

Release Date: 2024-04-26

Highlights

  • Initial release of ProductGraph event ingestion service
  • PostgreSQL-based Starter architecture with Row-Level Security for multi-tenancy
  • OTel-compatible event schema with 40+ fields
  • Ent ORM for type-safe database operations

Architecture

This release implements the Starter architecture, designed for up to 1,000 paying users (~50M events/month):

┌─────────────────────────────────────────────────────────────────┐
│                    ProductGraph Service                          │
│                      (Single Binary)                             │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐ │
│  │   Ingestion  │  │  GraphQL API │  │   Background Workers   │ │
│  │  /v1/events  │  │   (Planned)  │  │       (Planned)        │ │
│  └──────┬───────┘  └──────┬───────┘  └───────────┬────────────┘ │
│         │                 │                      │              │
│         └─────────────────┴──────────────────────┘              │
│                           │                                      │
│                    ┌──────┴──────┐                              │
│                    │   Ent ORM   │                              │
│                    └──────┬──────┘                              │
└───────────────────────────┼─────────────────────────────────────┘
                            │
                            ▼
               ┌────────────────────────┐
               │   PostgreSQL 16+ (RLS) │
               │                        │
               │  • Events (BRIN index) │
               │  • Sessions            │
               │  • Journeys            │
               │  • Projects/Orgs       │
               └────────────────────────┘

Why Starter Architecture?

Benefit Description
Simplicity Single database to manage, easy debugging
Cost ~$150/month infrastructure
Deployment Single binary + PostgreSQL
Security RLS provides tenant isolation at database level

Scaling Path

When you outgrow Starter:

Trigger Solution
Analytics queries > 2s Add ClickHouse
Write throughput > 5K/sec Add Kafka
Real-time requirements Add Redis

See the Architecture Scaling Guide for detailed migration paths.

What's Included

Event Ingestion API

  • POST /v1/events - Batch event ingestion (max 1000 events)
  • GET /health - Health check endpoint
  • GET /ready - Readiness check endpoint
  • CORS middleware for development

Event Schema

OTel-compatible fields organized by namespace:

Namespace Fields
session.* id
event.* type, name, timestamp, sequence
page.* path, title, url, referrer
ui.* component.name, component.path, action, element
ui.state.* key, before, after
gen_ai.journey.* id, step.id, step.name
api.* method, path, status_code, duration_ms
error.* type, message, stack

Database Schemas (Ent)

  • Organization - Multi-tenant root entity
  • Project - API key scoped projects
  • Event - Telemetry events with full OTel fields
  • Session - Aggregated session data
  • Journey - Journey definitions with entry/exit conditions

All schemas include org_id for Row-Level Security.

Documentation

  • Product Requirements Document (PRD)
  • Technical Requirements Document (TRD)
  • Architecture Scaling Guide with cost analysis
  • MkDocs documentation site

Dependencies

Dependency Version Purpose
Go 1.22+ Runtime
PostgreSQL 16+ Database
Ent v0.14.6 ORM

Getting Started

# Start PostgreSQL
make docker-up

# Run the service
make run-ingestion

# Send test event
curl -X POST http://localhost:8080/v1/events \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "event_id": "evt_001",
      "project_id": "proj_demo",
      "session.id": "sess_001",
      "event.type": "page.view",
      "event.timestamp": "2024-01-15T10:30:00Z",
      "page.path": "/home"
    }]
  }'

Known Limitations

  • No GraphQL API yet (planned for v0.2.0)
  • No real-time WebSocket updates (planned for Growth architecture)
  • No session aggregation workers (in-memory only)
  • No screenshot capture support yet

Upgrade Path

This is the initial release. Future releases will add:

  • v0.2.0 - GraphQL API, session aggregation
  • v0.3.0 - Journey matching, funnel queries
  • v0.4.0 - React dashboard UI
  • v0.5.0 - Growth architecture support (Kafka, ClickHouse, Redis)