Skip to Content
eventkit is in active development. APIs may change.
Getting Started

Getting Started

Welcome to eventkit! This guide will help you get up and running quickly.

Overview

eventkit is a production-ready kit for building event collection pipelines. Clone it, customize it, make it yours.

Quick Install

# Clone the repository
git clone https://github.com/prosdevlab/eventkit.git my-event-pipeline
cd my-event-pipeline
 
# Install dependencies
uv sync
 
# Start emulators (Firestore + Pub/Sub)
docker compose up -d
 
# Run the API server
export FIRESTORE_EMULATOR_HOST="localhost:8080"
export GCP_PROJECT_ID="test-project"
uv run uvicorn eventkit.api.app:app --reload

Send Your First Event

curl -X POST http://localhost:8000/api/v1/identify \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "traits": {
      "email": "user@example.com",
      "plan": "enterprise"
    }
  }'

Response:

{"status": "accepted"}

What’s Next?

Key Concepts

Flexible Ingestion

Accept any JSON payload at the edge. Invalid events go to an error store, never dropped.

Stream-Based Routing

Route events to named streams (users, events, pages) for independent processing.

Pluggable Storage

Default to GCS + BigQuery, or implement your own EventStore for any backend.

Production Patterns

  • Hash-based sequencing for consistent ordering
  • Ring buffer (Write-Ahead Log) for durability
  • Adaptive batching for efficient storage writes
  • Dead letter queue for validation failures

Architecture at a Glance

Components:

  • Collection API - FastAPI endpoints (/collect, /v1/identify, /v1/track)
  • Processing Pipeline - Adapters, Sequencer, EventLoader
  • Storage Layer - GCS + BigQuery, Firestore, or Custom

Common Use Cases

  • Build a lightweight CDP without vendor lock-in
  • Collect product analytics events at scale
  • Centralize event data from multiple sources
  • Create custom event processing pipelines
  • Prototype data architectures
Last updated on
ArchitectureGuides