Specifications

Technical specifications and design documents for eventkit features.

Overview

eventkit follows a spec-driven development process inspired by GitHub’s spec-kit .

Each feature gets three documents:

• spec.md - What: goals, scope, requirements
• plan.md - How: implementation strategy, file structure
• tasks.md - Work: task breakdown, checklists

See Spec-Driven Development for the full workflow.

Active Specifications

Core Pipeline

The foundational event ingestion and processing pipeline.

Status: ✅ Implemented

Key Features:

• RawEvent model (flexible JSON ingestion)
• ValidationPipeline (composable validators)
• SegmentSchemaAdapter (Segment-compatible events)
• Sequencer (hash-based routing)
• EventLoader (batching and buffering)
• Processor (orchestration)

Location: specs/core-pipeline/

GCS + BigQuery Storage

Production storage backend with Parquet files and warehouse loading.

Status: ✅ Implemented

Key Features:

• GCSEventStore (Hive-partitioned Parquet)
• BigQueryLoader (background polling and batch loading)
• WarehouseLoader protocol (pluggable warehouses)

Location: specs/gcs-bigquery-storage/

Ring Buffer (Write-Ahead Log)

Durability layer for preventing event loss.

Status: ✅ Implemented

Key Features:

• SQLite-based ring buffer with WAL mode
• RingBufferPublisher (background thread)
• Automatic cleanup (time and size based)

Location: specs/ring-buffer/

Prometheus Metrics

Observability and monitoring with Prometheus metrics.

Status: ✅ Implemented

Key Features:

• Dedicated metrics server (port 9090)
• Event throughput metrics
• Queue depth gauges
• Storage write metrics

Location: specs/prometheus-metrics/

Performance Benchmarks

Performance testing and validation framework.

Status: ✅ Implemented

Key Features:

• Flexible benchmark modes (validate, queue, store)
• GCS emulator support
• Throughput validation (10k+ events/sec)

Location: specs/performance-benchmarks/

Archived Specifications

Older specifications that have been implemented and consolidated into the main documentation.

Location: specs/archive/

Specification Process

1. Research - Understand the landscape
2. Spec - Document goals and requirements
3. Plan - Design implementation strategy
4. Tasks - Break down into atomic tasks
5. Implement - Build it (TDD)
6. Review - Code review and merge

See Spec-Driven Development for details.

Contributing

To propose a new feature:

1. Create a discussion in GitHub Discussions
2. If approved, create a spec directory: specs/your-feature/
3. Write spec.md, plan.md, tasks.md
4. Open a PR for review
5. Once spec is approved, implement tasks

See Contributing for the full process.

Resources

• GitHub spec-kit  - Inspiration for our workflow
• Workflow - Our spec-driven process
• Architecture - System architecture overview