# GenesisDB

> GenesisDB is a GDPR-ready, auditable, production-ready event sourcing database for building event-driven applications.

## Overview

GenesisDB is a purpose-built event sourcing database engine designed for developers who want to build systems with complete audit trails, time-travel debugging, and event replay capabilities. Unlike traditional databases that store only current state, GenesisDB stores immutable events that form a complete history of all changes.

## Key Features

- **Fast Event Storage & Retrieval**: Blazing-fast reads and optimized writes for event-store operations
- **HTTP/ndjson Interface**: RESTful API with ndjson streaming for efficient data transfer
- **gRPC Endpoint**: High-performance Protocol Buffer support for service-to-service communication (Enterprise)
- **CloudEvents Compliance**: Fully compliant with CloudEvents v1.0 specification
- **Preconditions & Schema Validation**: Declarative business rule enforcement with GDBQL query language
- **Event Stream Hierarchy**: Path-like subject identifiers (e.g., `/customer/123/orders/456`)
- **GDPR Support**: Crypto erasure for right-to-be-forgotten while maintaining audit trails (Enterprise)
- **Prometheus Metrics**: Built-in observability with metrics export
- **Multi-Language SDKs**: JavaScript/TypeScript, Go, Python, Rust, Swift, PHP

## Editions

### Community Edition (Free)
- Full core event store engine
- Unlimited events and instances
- HTTP API, event streaming, preconditions
- No license key required
- Community support

### Enterprise Edition (EUR 19.90/month yearly)
- All Community features plus:
- Standalone query endpoint (/api/v1/query)
- gRPC endpoint
- Schema registration APIs
- Reference-based storage for GDPR
- Crypto erasure API
- Email support

## Documentation

- Main documentation: https://docs.genesisdb.io
- API reference: https://docs.genesisdb.io/sdks/curl
- Community Edition guide: https://docs.genesisdb.io/community-edition
- Deployment guide: https://docs.genesisdb.io/deployment

## Quick Start

### Docker
```bash
docker run -d --name genesisdb \
  -p 8080:8080 \
  -e GENESISDB_AUTH_TOKEN=<secret> \
  -e GENESISDB_TZ=UTC \
  -e GENESISDB_DATA_DIR=/app/data \
  genesisdb/genesisdb:latest
```

### Commit Events
```bash
curl -X POST http://localhost:8080/api/v1/commit \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "source": "my-app",
      "subject": "/users/123",
      "type": "user.created",
      "data": {"name": "John Doe"}
    }]
  }'
```

### Stream Events
```bash
curl -X POST http://localhost:8080/api/v1/stream \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "/users/123",
    "options": {}
  }'
```

## Core Concepts

- **Events**: Immutable records of things that happened, stored in past tense (e.g., `user.created`, `order.placed`)
- **Subjects**: Path-like identifiers representing entities events happen to (e.g., `/customer/123`)
- **Sources**: Origin identifiers for events (e.g., `order-service`, `payment-gateway`)
- **Streams**: Ordered sequences of events for a subject
- **Preconditions**: GDBQL queries that must pass before events are committed
- **Schemas**: JSON Schema definitions for validating event payloads

## API Methods

- `commitEvents()` - Persist events to the store (may fail on precondition)
- `streamEvents()` - Retrieve events for a subject
- `observeEvents()` - Subscribe to real-time event notifications
- `queryEvents()` - Execute GDBQL queries (Enterprise)
- `eraseSubject()` - Delete events for GDPR compliance (Enterprise)

## Environment Variables

- `GENESISDB_AUTH_TOKEN` - API authentication token
- `GENESISDB_TZ` - Timezone (e.g., UTC, Europe/Vienna)
- `GENESISDB_DATA_DIR` - Data storage directory
- `GENESISDB_METRICS` - Enable metrics endpoint
- `GENESISDB_LICENSE` - License key (omit for Community Edition)
- `GENESISDB_GRPC_ENABLED` - Enable gRPC endpoint
- `GENESISDB_GRPC_PORT` - gRPC port (default: 50051)

## Resources

- Website: https://www.genesisdb.io
- Documentation: https://docs.genesisdb.io
- Event Sourcing Guide: https://www.eventsourcing.dev
- Discord Community: https://discord.gg/wxMWeq9rDS
- VS Code Extension: https://marketplace.visualstudio.com/items?itemName=patriceckhart.genesisdb-vscode
- MCP Server: https://github.com/genesisdb-io/genesisdb-io-mcp-server

## SDKs

- JavaScript/TypeScript: https://github.com/genesisdb-io/genesisdb-io-client-js
- Go: https://github.com/genesisdb-io/genesisdb-io-client-go
- Swift: https://github.com/genesisdb-io/genesisdb-io-client-swift
- Python: https://github.com/genesisdb-io/genesisdb-io-client-python
- Rust: https://github.com/genesisdb-io/genesisdb-io-client-rust
- PHP: https://github.com/genesisdb-io/genesisdb-io-client-php

## Use Cases

- **Audit Systems**: Complete transaction history for compliance
- **Financial Applications**: Immutable record of all monetary events
- **E-commerce**: Order history, inventory changes, customer actions
- **IoT**: Time-series event data with full history
- **Microservices**: Event-driven architecture backbone